actor-gate 0.1.0

package/src/next/pages/direct-auth-handlers.js

@@ -0,0 +1,425 @@
+import { AuthServiceError } from '../../core/services/auth-error';
+import { clearPagesAuthCookie, setPagesAuthCookie, } from './cookies';
+import { sendPagesRedirect } from './response';
+import { withPagesAuthRoute } from './wrapper';
+import { assertBearerOnlyActorPolicy, assertCsrfForCookieMutation, DEFAULT_ACCESS_TOKEN_COOKIE_NAME, DEFAULT_REFRESH_TOKEN_COOKIE_NAME, extractRefreshToken, parseNonNegativeSafeInteger, resolveAccessTokenTransportAdapter, resolveCookieSecureFlag, resolveLoginMethod, resolvePathnameFromUrl, } from '../shared/direct-auth-utils';
+import { parseBodyToRecord, toSingleString } from '../shared/oauth-utils';
+function sendMethodNotAllowed(res, allowedMethods) {
+    res.setHeader('Allow', allowedMethods.join(', '));
+    res.status(405).json({
+        error: 'method_not_allowed',
+        error_description: 'HTTP method not allowed for auth route.',
+    });
+}
+function buildTokenOutput(input) {
+    const expiresIn = Math.max(0, input.accessClaims.exp - input.accessClaims.iat);
+    return {
+        access_token: input.accessToken,
+        token_type: 'Bearer',
+        expires_in: expiresIn,
+        ...(input.refreshToken === undefined
+            ? {}
+            : { refresh_token: input.refreshToken }),
+        ...(input.clientSession === undefined
+            ? {}
+            : { clientSession: input.clientSession }),
+    };
+}
+function resolveCookiesConfig(config) {
+    return {
+        enabled: config?.enabled ?? true,
+        accessTokenCookieName: toSingleString(config?.accessTokenCookieName) ??
+            DEFAULT_ACCESS_TOKEN_COOKIE_NAME,
+        refreshTokenCookieName: toSingleString(config?.refreshTokenCookieName) ??
+            DEFAULT_REFRESH_TOKEN_COOKIE_NAME,
+        path: toSingleString(config?.path) ?? '/',
+        sameSite: config?.sameSite ?? 'lax',
+        secure: resolveCookieSecureFlag({
+            ...(config?.secure === undefined ? {} : { secure: config.secure }),
+            ...(config?.secureInProduction === undefined
+                ? {}
+                : { secureInProduction: config.secureInProduction }),
+        }),
+        refreshTokenMaxAgeSeconds: parseNonNegativeSafeInteger(config?.refreshTokenMaxAgeSeconds ?? 60 * 60 * 24 * 30, 'cookies.refreshTokenMaxAgeSeconds'),
+    };
+}
+function clearAuthCookies(res, cookiesConfig) {
+    if (!cookiesConfig.enabled) {
+        return;
+    }
+    clearPagesAuthCookie(res, {
+        name: cookiesConfig.accessTokenCookieName,
+        path: cookiesConfig.path,
+        sameSite: cookiesConfig.sameSite,
+        secure: cookiesConfig.secure,
+    });
+    clearPagesAuthCookie(res, {
+        name: cookiesConfig.refreshTokenCookieName,
+        path: cookiesConfig.path,
+        sameSite: cookiesConfig.sameSite,
+        secure: cookiesConfig.secure,
+    });
+}
+function applyAuthCookies(input) {
+    if (!input.cookiesConfig.enabled) {
+        return;
+    }
+    setPagesAuthCookie(input.res, {
+        name: input.cookiesConfig.accessTokenCookieName,
+        value: input.accessToken,
+        maxAgeSeconds: input.accessTokenMaxAgeSeconds,
+        path: input.cookiesConfig.path,
+        sameSite: input.cookiesConfig.sameSite,
+        secure: input.cookiesConfig.secure,
+    });
+    if (input.refreshToken !== undefined) {
+        setPagesAuthCookie(input.res, {
+            name: input.cookiesConfig.refreshTokenCookieName,
+            value: input.refreshToken,
+            maxAgeSeconds: input.cookiesConfig.refreshTokenMaxAgeSeconds,
+            path: input.cookiesConfig.path,
+            sameSite: input.cookiesConfig.sameSite,
+            secure: input.cookiesConfig.secure,
+        });
+    }
+}
+function parseQuery(req) {
+    return req.query;
+}
+function requireLoginMethods(loginMethods) {
+    if (!loginMethods || Object.keys(loginMethods).length === 0) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'No login methods are configured.',
+        });
+    }
+    return loginMethods;
+}
+function requireLoginMethod(input) {
+    const adapter = input.loginMethods[input.method];
+    if (!adapter) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: `Unsupported login method "${input.method}".`,
+        });
+    }
+    return adapter;
+}
+export function createPagesDirectAuthHandlers(options) {
+    const cookiesConfig = resolveCookiesConfig(options.cookies);
+    const refreshTokenFieldName = toSingleString(options.refreshTokenFieldName) ?? 'refresh_token';
+    const accessTokenTransport = resolveAccessTokenTransportAdapter(options.accessTokenTransport);
+    const logoutAllowMissingCredentials = options.logoutAllowMissingCredentials ?? true;
+    const refresh = withPagesAuthRoute({
+        ...(options.requestIdHeaderName === undefined
+            ? {}
+            : { requestIdHeaderName: options.requestIdHeaderName }),
+        ...(options.authorizationHeaderName === undefined
+            ? {}
+            : { authorizationHeaderName: options.authorizationHeaderName }),
+        handler: async ({ req, res, requestId, transport }) => {
+            if (req.method !== 'POST') {
+                sendMethodNotAllowed(res, ['POST']);
+                return;
+            }
+            const body = parseBodyToRecord(req.body);
+            const pathname = resolvePathnameFromUrl(req.url);
+            const cookies = transport.cookies ?? {};
+            const extractedRefreshToken = extractRefreshToken({
+                body,
+                cookies,
+                bodyFieldName: refreshTokenFieldName,
+                cookieName: cookiesConfig.refreshTokenCookieName,
+                ...(options.refreshTokenPriority === undefined
+                    ? {}
+                    : { priority: options.refreshTokenPriority }),
+            });
+            assertCsrfForCookieMutation({
+                method: req.method,
+                pathname,
+                cookies,
+                headers: req.headers,
+                body,
+                cookieAuthenticated: extractedRefreshToken.source === 'cookie',
+                ...(options.csrf === undefined ? {} : { config: options.csrf }),
+            });
+            if (extractedRefreshToken.token === undefined) {
+                throw new AuthServiceError({
+                    code: 'unauthorized',
+                    message: 'Refresh token is required.',
+                });
+            }
+            const refreshed = await options.directAuthService.refresh({
+                refreshToken: extractedRefreshToken.token,
+                ...(requestId === undefined ? {} : { requestId }),
+            });
+            const output = buildTokenOutput({
+                accessToken: refreshed.accessToken,
+                accessClaims: refreshed.accessClaims,
+                ...(refreshed.refreshToken === undefined
+                    ? {}
+                    : { refreshToken: refreshed.refreshToken }),
+                ...(refreshed.clientSession === undefined
+                    ? {}
+                    : { clientSession: refreshed.clientSession }),
+            });
+            if (extractedRefreshToken.source === 'cookie') {
+                applyAuthCookies({
+                    res,
+                    cookiesConfig,
+                    accessToken: refreshed.accessToken,
+                    accessTokenMaxAgeSeconds: output.expires_in,
+                    refreshToken: refreshed.refreshToken ?? extractedRefreshToken.token,
+                });
+            }
+            return output;
+        },
+    });
+    const logout = withPagesAuthRoute({
+        ...(options.requestIdHeaderName === undefined
+            ? {}
+            : { requestIdHeaderName: options.requestIdHeaderName }),
+        ...(options.authorizationHeaderName === undefined
+            ? {}
+            : { authorizationHeaderName: options.authorizationHeaderName }),
+        handler: async ({ req, res, requestId, transport }) => {
+            if (req.method !== 'POST') {
+                sendMethodNotAllowed(res, ['POST']);
+                return;
+            }
+            const body = parseBodyToRecord(req.body);
+            const pathname = resolvePathnameFromUrl(req.url);
+            const cookies = transport.cookies ?? {};
+            const extractedRefreshToken = extractRefreshToken({
+                body,
+                cookies,
+                bodyFieldName: refreshTokenFieldName,
+                cookieName: cookiesConfig.refreshTokenCookieName,
+                ...(options.refreshTokenPriority === undefined
+                    ? {}
+                    : { priority: options.refreshTokenPriority }),
+            });
+            const extractedAccessToken = accessTokenTransport.extractAccessToken({
+                transport,
+            });
+            assertCsrfForCookieMutation({
+                method: req.method,
+                pathname,
+                cookies,
+                headers: req.headers,
+                body,
+                cookieAuthenticated: extractedRefreshToken.source === 'cookie' ||
+                    extractedAccessToken.source === 'cookie',
+                ...(options.csrf === undefined ? {} : { config: options.csrf }),
+            });
+            let validatedAccess;
+            if (extractedAccessToken.token) {
+                validatedAccess = await options.directAuthService.validateAccessToken({
+                    accessToken: extractedAccessToken.token,
+                    ...(requestId === undefined ? {} : { requestId }),
+                    ...(options.expectedAudience === undefined
+                        ? {}
+                        : { expectedAudience: options.expectedAudience }),
+                    ...(options.allowedActors === undefined
+                        ? {}
+                        : { allowedActors: options.allowedActors }),
+                });
+                assertBearerOnlyActorPolicy({
+                    actor: validatedAccess.claims.actor,
+                    ...(extractedAccessToken.source === undefined
+                        ? {}
+                        : { source: extractedAccessToken.source }),
+                    ...(options.accessTokenTransport?.requireBearerForActors === undefined
+                        ? {}
+                        : {
+                            requireBearerForActors: options.accessTokenTransport.requireBearerForActors,
+                        }),
+                });
+            }
+            const sessionId = options.parseSessionId?.(body.session_id);
+            const resolvedSessionId = sessionId ?? validatedAccess?.authContext.sessionId;
+            if (resolvedSessionId === undefined &&
+                extractedRefreshToken.token === undefined &&
+                validatedAccess === undefined) {
+                clearAuthCookies(res, cookiesConfig);
+                if (logoutAllowMissingCredentials) {
+                    return {
+                        ok: true,
+                        session_revoked: false,
+                        refresh_token_revoked: false,
+                        access_token_revoked: false,
+                    };
+                }
+                throw new AuthServiceError({
+                    code: 'invalid_request',
+                    message: 'At least one logout credential (session_id, refresh_token, or access token) is required.',
+                });
+            }
+            const result = await options.directAuthService.logout({
+                ...(requestId === undefined ? {} : { requestId }),
+                ...(resolvedSessionId === undefined
+                    ? {}
+                    : { sessionId: resolvedSessionId }),
+                ...(extractedRefreshToken.token === undefined
+                    ? {}
+                    : { refreshToken: extractedRefreshToken.token }),
+                ...(validatedAccess === undefined
+                    ? {}
+                    : {
+                        accessTokenJti: validatedAccess.claims.jti,
+                        accessTokenExpiresAtUnix: validatedAccess.claims.exp,
+                    }),
+            });
+            clearAuthCookies(res, cookiesConfig);
+            return {
+                ok: true,
+                session_revoked: result.sessionRevoked,
+                refresh_token_revoked: result.refreshTokenRevoked,
+                access_token_revoked: result.accessTokenRevoked,
+            };
+        },
+    });
+    const loginStart = withPagesAuthRoute({
+        ...(options.requestIdHeaderName === undefined
+            ? {}
+            : { requestIdHeaderName: options.requestIdHeaderName }),
+        handler: async ({ req, res }) => {
+            if (req.method !== 'POST') {
+                sendMethodNotAllowed(res, ['POST']);
+                return;
+            }
+            const loginMethods = requireLoginMethods(options.loginMethods);
+            const body = parseBodyToRecord(req.body);
+            const query = parseQuery(req);
+            const method = resolveLoginMethod({
+                pathname: resolvePathnameFromUrl(req.url),
+                phase: 'start',
+                body,
+                queryMethod: query.method,
+                ...(options.defaultLoginMethod === undefined
+                    ? {}
+                    : { defaultMethod: options.defaultLoginMethod }),
+            });
+            const adapter = requireLoginMethod({
+                loginMethods,
+                method,
+            });
+            if (!adapter.start) {
+                throw new AuthServiceError({
+                    code: 'invalid_request',
+                    message: `Login method "${method}" does not implement start.`,
+                });
+            }
+            await adapter.start(body);
+            return { ok: true };
+        },
+    });
+    const loginFinish = withPagesAuthRoute({
+        ...(options.requestIdHeaderName === undefined
+            ? {}
+            : { requestIdHeaderName: options.requestIdHeaderName }),
+        handler: async ({ req, res, requestId }) => {
+            if (req.method !== 'GET') {
+                sendMethodNotAllowed(res, ['GET']);
+                return;
+            }
+            const loginMethods = requireLoginMethods(options.loginMethods);
+            const query = parseQuery(req);
+            const method = resolveLoginMethod({
+                pathname: resolvePathnameFromUrl(req.url),
+                phase: 'finish',
+                queryMethod: query.method,
+                ...(options.defaultLoginMethod === undefined
+                    ? {}
+                    : { defaultMethod: options.defaultLoginMethod }),
+            });
+            const adapter = requireLoginMethod({
+                loginMethods,
+                method,
+            });
+            const finishResult = await adapter.finish(query);
+            if (finishResult === null) {
+                throw new AuthServiceError({
+                    code: 'unauthorized',
+                    message: 'Login method did not authenticate a user.',
+                });
+            }
+            if (!options.issueLogin) {
+                return { ok: true };
+            }
+            const issued = await options.issueLogin({
+                req,
+                res,
+                method,
+                userId: finishResult.userId,
+                ...(requestId === undefined ? {} : { requestId }),
+            });
+            if (!issued) {
+                return { ok: true };
+            }
+            if (issued.accessToken !== undefined) {
+                if (issued.accessClaims === undefined) {
+                    throw new AuthServiceError({
+                        code: 'invalid_request',
+                        message: 'issueLogin must include accessClaims when accessToken is provided.',
+                    });
+                }
+                const tokenOutput = buildTokenOutput({
+                    accessToken: issued.accessToken,
+                    accessClaims: issued.accessClaims,
+                    ...(issued.refreshToken === undefined
+                        ? {}
+                        : { refreshToken: issued.refreshToken }),
+                    ...(issued.clientSession === undefined
+                        ? {}
+                        : { clientSession: issued.clientSession }),
+                });
+                applyAuthCookies({
+                    res,
+                    cookiesConfig,
+                    accessToken: issued.accessToken,
+                    accessTokenMaxAgeSeconds: tokenOutput.expires_in,
+                    ...(issued.refreshToken === undefined
+                        ? {}
+                        : { refreshToken: issued.refreshToken }),
+                });
+                if (issued.redirectTo) {
+                    return {
+                        location: issued.redirectTo,
+                        ...(issued.statusCode === undefined
+                            ? {}
+                            : { statusCode: issued.statusCode }),
+                    };
+                }
+                return issued.body ?? tokenOutput;
+            }
+            if (issued.redirectTo) {
+                return {
+                    location: issued.redirectTo,
+                    ...(issued.statusCode === undefined
+                        ? {}
+                        : { statusCode: issued.statusCode }),
+                };
+            }
+            return issued.body ?? { ok: true };
+        },
+        send: ({ res, output }) => {
+            const location = output.location;
+            if (typeof location === 'string') {
+                const statusCode = output.statusCode;
+                sendPagesRedirect(res, {
+                    location,
+                    ...(typeof statusCode === 'number' ? { statusCode } : {}),
+                });
+                return;
+            }
+            res.status(200).json(output);
+        },
+    });
+    return {
+        refresh,
+        logout,
+        loginStart,
+        loginFinish,
+    };
+}

package/src/next/pages/index.d.ts

@@ -0,0 +1,8 @@
+export { buildPagesAccessTokenTransportInput, getPagesAuthorizationHeader, getPagesCookies, getPagesRequestId, parseCookieHeader, } from './request';
+export { appendSetCookieHeader, clearPagesAuthCookie, serializeSetCookie, setPagesAuthCookie, setPagesCookie, type CookieSameSite, type PagesCookieOptions, } from './cookies';
+export { sendPagesAuthError, sendPagesRedirect, sendPagesSystemError, type PagesAuthErrorResponseBody, } from './response';
+export { withPagesAuthRoute, type PagesAuthRouteContext, type WithPagesAuthRouteOptions, } from './wrapper';
+export { withPagesProtectedRoute, type PagesProtectedAuth, type PagesProtectedRouteContext, type WithPagesProtectedRouteOptions, } from './protected-route';
+export { createPagesAuthCatchAllHandler, type CreatePagesAuthCatchAllHandlerOptions, type PagesAuthCatchAllHandler, } from './catch-all';
+export { createPagesMcpHandler, createPagesOAuthHandlers, createPagesWellKnownHandlers, type CreatePagesMcpHandlerOptions, type CreatePagesOAuthHandlersOptions, type CreatePagesWellKnownHandlersOptions, type PagesOAuthHandlers, type PagesWellKnownHandlers, } from './mcp-oauth-handlers';
+export { createPagesDirectAuthHandlers, type CreatePagesDirectAuthHandlersOptions, type DirectCookieConfig as PagesDirectCookieConfig, type PagesDirectAuthHandlers, type PagesDirectLoginIssueResult, } from './direct-auth-handlers';

package/src/next/pages/index.js

@@ -0,0 +1,8 @@
+export { buildPagesAccessTokenTransportInput, getPagesAuthorizationHeader, getPagesCookies, getPagesRequestId, parseCookieHeader, } from './request';
+export { appendSetCookieHeader, clearPagesAuthCookie, serializeSetCookie, setPagesAuthCookie, setPagesCookie, } from './cookies';
+export { sendPagesAuthError, sendPagesRedirect, sendPagesSystemError, } from './response';
+export { withPagesAuthRoute, } from './wrapper';
+export { withPagesProtectedRoute, } from './protected-route';
+export { createPagesAuthCatchAllHandler, } from './catch-all';
+export { createPagesMcpHandler, createPagesOAuthHandlers, createPagesWellKnownHandlers, } from './mcp-oauth-handlers';
+export { createPagesDirectAuthHandlers, } from './direct-auth-handlers';

package/src/next/pages/mcp-oauth-handlers.d.ts

@@ -0,0 +1,77 @@
+import type { NextApiHandler, NextApiRequest, NextApiResponse } from 'next';
+import type { OAuthGrantType } from '../../core/adapters/oauth-grant-type';
+import type { McpAuthService, McpAuthenticationResult, OAuthService } from '../../core/services/index';
+import type { AuthActor } from '../../core/types/auth-contract';
+export type CreatePagesMcpHandlerOptions<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>> = {
+    mcpAuthService: McpAuthService<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;
+    handleRequest: (input: {
+        req: NextApiRequest;
+        res: NextApiResponse;
+        body: unknown;
+        authentication: McpAuthenticationResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;
+        requestId?: string;
+    }) => Promise<unknown | void> | unknown | void;
+    parseBody?: (req: NextApiRequest) => unknown;
+    expectedAudience?: string;
+    allowedActors?: readonly TActor[] | ReadonlySet<TActor>;
+    challengeScope?: string;
+    resourceMetadataUrl?: string;
+    requestIdHeaderName?: string;
+    authorizationHeaderName?: string;
+};
+export declare function createPagesMcpHandler<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>>(options: CreatePagesMcpHandlerOptions<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>): NextApiHandler;
+export type CreatePagesOAuthHandlersOptions<TUserId, TActor extends AuthActor = AuthActor, TExtClaims extends Record<string, unknown> = Record<string, never>> = {
+    oauthService: OAuthService<TUserId, TActor, TExtClaims>;
+    resolveUserId: (input: {
+        req: NextApiRequest;
+        res: NextApiResponse;
+        requestId: string;
+        approved: boolean;
+    }) => Promise<TUserId | null> | TUserId | null;
+    requiredScope?: string;
+    requireState?: boolean;
+    defaultCodeMethod?: 'S256' | 'plain';
+    generateRequestId?: () => string;
+    getAuthorizeLoginLocation?: (input: {
+        req: NextApiRequest;
+        requestId: string;
+        expiresAtUnix: number;
+    }) => string;
+    token?: {
+        authorizationCodeSessionTtlSeconds?: number;
+        issueRefreshToken?: boolean;
+        allowGrantTypeInference?: boolean;
+        clientCredentials?: {
+            enabled?: boolean;
+            sessionTtlSeconds?: number;
+        };
+    };
+    requestIdHeaderName?: string;
+    authorizationHeaderName?: string;
+};
+export type PagesOAuthHandlers = {
+    authorize: NextApiHandler;
+    authorizeConfirm: NextApiHandler;
+    token: NextApiHandler;
+};
+export declare function createPagesOAuthHandlers<TUserId, TActor extends AuthActor = AuthActor, TExtClaims extends Record<string, unknown> = Record<string, never>>(options: CreatePagesOAuthHandlersOptions<TUserId, TActor, TExtClaims>): PagesOAuthHandlers;
+export type CreatePagesWellKnownHandlersOptions = {
+    issuer?: string | ((req: NextApiRequest) => string);
+    authorizationEndpoint?: string;
+    tokenEndpoint?: string;
+    protectedResource?: string | ((req: NextApiRequest) => string);
+    authorizationServers?: ReadonlyArray<string> | ((req: NextApiRequest) => ReadonlyArray<string>);
+    responseTypesSupported?: readonly string[];
+    grantTypesSupported?: readonly OAuthGrantType[];
+    codeChallengeMethodsSupported?: ReadonlyArray<'S256' | 'plain'>;
+    tokenEndpointAuthMethodsSupported?: readonly string[];
+    scopesSupported?: readonly string[];
+    cacheControlHeader?: string;
+    fallbackOrigin?: string;
+};
+export type PagesWellKnownHandlers = {
+    oauthProtectedResource: NextApiHandler;
+    oauthAuthorizationServer: NextApiHandler;
+    openidConfiguration: NextApiHandler;
+};
+export declare function createPagesWellKnownHandlers(options?: CreatePagesWellKnownHandlersOptions): PagesWellKnownHandlers;