Documentation

Core Functions

Core authentication functions in @warpy-auth-sdk/core.

Core Authentication Functions

@warpy-auth-sdk/core provides several core functions for authentication. These are the main functions you'll use in your application.

authenticate

Main authentication function that handles OAuth, email, and MCP agent login flows

authenticate(config: AuthConfig, request?: Request, payload?: MCPLoginPayload): Promise<AuthenticateResult>

Parameters

configAuthConfigrequired

Authentication configuration with provider and secret

requestRequest

HTTP request object (for OAuth/email flows)

payloadMCPLoginPayload

MCP agent login payload (for agent authentication)

Returns

Promise<AuthenticateResult>

Example

import { authenticate, google } from '@warpy-auth-sdk/core';

// OAuth authentication
const result = await authenticate(
  {
    secret: process.env.AUTH_SECRET!,
    provider: google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      redirectUri: process.env.GOOGLE_REDIRECT_URI!,
    }),
  },
  request
);

if (result.session) {
  // User is authenticated
  console.log('User:', result.session.user);
} else if (result.redirectUrl) {
  // Redirect to OAuth provider
  return Response.redirect(result.redirectUrl);
}

getSession

Retrieve the current session from request cookies

getSession(request: Request, secret: string): Promise<Session | null>

Parameters

requestRequestrequired

HTTP request with cookies

secretstringrequired

JWT signing secret

Returns

Promise<Session | null>

Example

import { getSession } from '@warpy-auth-sdk/core';

export async function GET(request: Request) {
  const session = await getSession(request, process.env.AUTH_SECRET!);
  
  if (!session) {
    return Response.json({ error: 'Not authenticated' }, { status: 401 });
  }
  
  return Response.json({ user: session.user });
}

signOut

Sign out the user and clear session cookies

signOut(request: Request, config: AuthConfig): Promise<void>

Parameters

requestRequestrequired

HTTP request

configAuthConfigrequired

Authentication configuration

Returns

Promise<void>

Example

import { signOut } from '@warpy-auth-sdk/core';

export async function POST(request: Request) {
  await signOut(request, {
    secret: process.env.AUTH_SECRET!,
    provider: google({ /* ... */ }),
  });
  
  return Response.json({ success: true });
}

verifyAgentToken

Verify MCP agent token from Authorization header

verifyAgentToken(request: Request, secret: string): Promise<Session | null>

Parameters

requestRequestrequired

HTTP request with Authorization header

secretstringrequired

JWT signing secret

Returns

Promise<Session | null>

Example

import { verifyAgentToken } from '@warpy-auth-sdk/core';

export async function GET(request: Request) {
  const session = await verifyAgentToken(request, process.env.AUTH_SECRET!);
  
  if (!session || !session.scopes?.includes('read')) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }
  
  return Response.json({ data: 'Protected data' });
}

Type Definitions

Core types used throughout @warpy-auth-sdk/core:

interface AuthConfig {
  secret: string;
  provider: Provider;
  adapter?: Adapter;
  callbacks?: {
    user?: (user: User, context: { provider: string }) => Promise<User>;
    jwt?: (token: JWT) => JWT;
    session?: (session: Session) => Session;
  };
}

interface Session {
  user: {
    id: string;
    email: string;
    name?: string;
    picture?: string;
  };
  expires: Date;
  token?: string;
  type?: 'standard' | 'mcp-agent';
  scopes?: string[];
  agentId?: string;
}

interface AuthenticateResult {
  session?: Session;
  error?: string;
  redirectUrl?: string;
}

Error Handling

All core functions can throw errors. Handle them appropriately:

try {
  const session = await getSession(request, process.env.AUTH_SECRET!);
  // Handle session
} catch (error) {
  console.error('Authentication error:', error);
  return Response.json({ error: 'Authentication failed' }, { status: 500 });
}

Best Practices

  • Always handle authentication errors gracefully
  • Use try-catch blocks around authentication calls
  • Validate environment variables at startup
  • Log authentication events for debugging
Provider API
Core Functions | @warpy-auth-sdk/core