actor-gate 0.1.0

package/src/next/shared/oauth-utils.d.ts

@@ -0,0 +1,45 @@
+export declare function parseBodyToRecord(body: unknown): Record<string, unknown>;
+export declare function parseCodeMethod(value: unknown, defaultMethod?: 'S256' | 'plain'): 'S256' | 'plain';
+export declare function parseScopes(value: unknown, fallback: readonly string[]): string[];
+export declare function parseBoolean(value: unknown, defaultValue: boolean): boolean;
+export declare function parsePositiveSafeInteger(value: unknown, fieldName: string): number;
+export type ParsedAuthorizeRequest = {
+    responseType: 'code';
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    codeMethod: 'S256' | 'plain';
+    scopes: string[];
+    state?: string;
+};
+export declare function parseAuthorizeRequest(input: {
+    query: Record<string, unknown>;
+    requiredScope: string;
+    defaultCodeMethod?: 'S256' | 'plain';
+    requireState?: boolean;
+}): ParsedAuthorizeRequest;
+export type ParsedOAuthTokenRequest = {
+    grantType: 'authorization_code';
+    clientId: string;
+    clientSecret: string | null;
+    authorizationCode: string;
+    redirectUri: string;
+    codeVerifier: string;
+} | {
+    grantType: 'refresh_token';
+    clientId: string;
+    clientSecret: string | null;
+    refreshToken: string;
+} | {
+    grantType: 'client_credentials';
+    clientId: string;
+    clientSecret: string | null;
+};
+export declare function parseOAuthTokenRequest(input: {
+    body: unknown;
+    authorizationHeader?: string;
+    allowClientCredentials?: boolean;
+    allowGrantTypeInference?: boolean;
+}): ParsedOAuthTokenRequest;
+export declare function appendUrlParams(baseUrl: string, params: Record<string, string | undefined>): string;
+export declare function toSingleString(value: unknown): string | undefined;

package/src/next/shared/oauth-utils.js

@@ -0,0 +1,308 @@
+import { AuthServiceError } from '../../core/services/auth-error';
+function toNonEmptyString(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const normalized = toNonEmptyString(item);
+            if (normalized !== undefined) {
+                return normalized;
+            }
+        }
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function assertObjectRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'Request body must be an object.',
+        });
+    }
+    return value;
+}
+function parseStringBody(body) {
+    const trimmed = body.trim();
+    if (trimmed.length === 0) {
+        return {};
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(trimmed);
+    }
+    catch (jsonError) {
+        const params = new URLSearchParams(trimmed);
+        if (params.size === 0) {
+            throw new AuthServiceError({
+                code: 'invalid_request',
+                message: 'Request body must be valid JSON or URL-encoded form data.',
+                cause: jsonError,
+            });
+        }
+        const output = {};
+        params.forEach((paramValue, paramName) => {
+            output[paramName] = paramValue;
+        });
+        return output;
+    }
+    return assertObjectRecord(parsedJson);
+}
+export function parseBodyToRecord(body) {
+    if (body === null || body === undefined) {
+        return {};
+    }
+    if (typeof body === 'string') {
+        return parseStringBody(body);
+    }
+    if (body instanceof URLSearchParams) {
+        const output = {};
+        body.forEach((paramValue, paramName) => {
+            output[paramName] = paramValue;
+        });
+        return output;
+    }
+    return assertObjectRecord(body);
+}
+export function parseCodeMethod(value, defaultMethod = 'S256') {
+    const normalized = toNonEmptyString(value);
+    if (normalized === undefined) {
+        return defaultMethod;
+    }
+    if (normalized !== 'S256' && normalized !== 'plain') {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'Unsupported PKCE code_challenge_method.',
+        });
+    }
+    return normalized;
+}
+export function parseScopes(value, fallback) {
+    const normalized = toNonEmptyString(value);
+    if (normalized === undefined) {
+        return [...fallback];
+    }
+    return normalized
+        .split(/\s+/)
+        .map(scope => scope.trim())
+        .filter(scope => scope.length > 0);
+}
+export function parseBoolean(value, defaultValue) {
+    if (value === undefined || value === null) {
+        return defaultValue;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (value === 1) {
+            return true;
+        }
+        if (value === 0) {
+            return false;
+        }
+    }
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === 'true' || normalized === '1' || normalized === 'yes') {
+            return true;
+        }
+        if (normalized === 'false' || normalized === '0' || normalized === 'no') {
+            return false;
+        }
+    }
+    throw new AuthServiceError({
+        code: 'invalid_request',
+        message: 'Boolean field is invalid.',
+    });
+}
+export function parsePositiveSafeInteger(value, fieldName) {
+    const normalized = typeof value === 'number'
+        ? value
+        : Number.parseInt(toNonEmptyString(value) ?? '', 10);
+    if (!Number.isSafeInteger(normalized) || normalized <= 0) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: `${fieldName} must be a positive safe integer.`,
+        });
+    }
+    return normalized;
+}
+function parseBasicCredentials(authorizationHeader) {
+    if (!authorizationHeader) {
+        return null;
+    }
+    const match = authorizationHeader.match(/^Basic\s+(.+)$/i);
+    if (!match) {
+        return null;
+    }
+    let decoded;
+    try {
+        decoded = Buffer.from(match[1], 'base64').toString('utf8');
+    }
+    catch (error) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'Invalid Basic authorization header.',
+            cause: error,
+        });
+    }
+    const separatorIndex = decoded.indexOf(':');
+    if (separatorIndex <= 0) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'Invalid Basic authorization header.',
+        });
+    }
+    const clientId = decoded.slice(0, separatorIndex);
+    const clientSecretRaw = decoded.slice(separatorIndex + 1);
+    return {
+        clientId,
+        clientSecret: clientSecretRaw.length > 0 ? clientSecretRaw : null,
+    };
+}
+function requireField(body, fieldName) {
+    const value = toNonEmptyString(body[fieldName]);
+    if (value === undefined) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: `Missing required field "${fieldName}".`,
+        });
+    }
+    return value;
+}
+export function parseAuthorizeRequest(input) {
+    const responseTypeRaw = toNonEmptyString(input.query.response_type) ?? 'code';
+    if (responseTypeRaw !== 'code') {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'Unsupported response_type.',
+        });
+    }
+    const clientId = toNonEmptyString(input.query.client_id);
+    const redirectUri = toNonEmptyString(input.query.redirect_uri);
+    const codeChallenge = toNonEmptyString(input.query.code_challenge);
+    const state = toNonEmptyString(input.query.state);
+    if (clientId === undefined || redirectUri === undefined) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'Missing required authorize query parameters.',
+        });
+    }
+    if (codeChallenge === undefined) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'Missing required query parameter "code_challenge".',
+        });
+    }
+    const requireState = input.requireState ?? true;
+    if (requireState && state === undefined) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'Missing required query parameter "state".',
+        });
+    }
+    const codeMethod = parseCodeMethod(input.query.code_challenge_method, input.defaultCodeMethod ?? 'S256');
+    const scopes = parseScopes(input.query.scope, [input.requiredScope]);
+    if (!scopes.includes(input.requiredScope)) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: `Missing required scope "${input.requiredScope}".`,
+        });
+    }
+    return {
+        responseType: 'code',
+        clientId,
+        redirectUri,
+        codeChallenge,
+        codeMethod,
+        scopes,
+        ...(state === undefined ? {} : { state }),
+    };
+}
+export function parseOAuthTokenRequest(input) {
+    const body = parseBodyToRecord(input.body);
+    const allowGrantTypeInference = input.allowGrantTypeInference ?? true;
+    const basicClient = parseBasicCredentials(input.authorizationHeader);
+    const bodyClientId = toNonEmptyString(body.client_id);
+    if (basicClient &&
+        bodyClientId !== undefined &&
+        basicClient.clientId !== bodyClientId) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'client_id must match between Authorization header and request body.',
+        });
+    }
+    const clientId = basicClient?.clientId ?? bodyClientId;
+    const clientSecret = basicClient?.clientSecret ?? toNonEmptyString(body.client_secret) ?? null;
+    if (clientId === undefined) {
+        throw new AuthServiceError({
+            code: 'invalid_client',
+            message: 'OAuth client credentials are required.',
+        });
+    }
+    const grantTypeRaw = toNonEmptyString(body.grant_type);
+    const inferredGrantType = allowGrantTypeInference && grantTypeRaw === undefined
+        ? toNonEmptyString(body.code)
+            ? 'authorization_code'
+            : toNonEmptyString(body.refresh_token)
+                ? 'refresh_token'
+                : null
+        : null;
+    const grantType = (grantTypeRaw ?? inferredGrantType);
+    if (!grantType) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: 'Missing required field "grant_type".',
+        });
+    }
+    if (grantType === 'authorization_code') {
+        return {
+            grantType,
+            clientId,
+            clientSecret,
+            authorizationCode: requireField(body, 'code'),
+            redirectUri: requireField(body, 'redirect_uri'),
+            codeVerifier: requireField(body, 'code_verifier'),
+        };
+    }
+    if (grantType === 'refresh_token') {
+        return {
+            grantType,
+            clientId,
+            clientSecret,
+            refreshToken: requireField(body, 'refresh_token'),
+        };
+    }
+    if (grantType === 'client_credentials') {
+        if (!input.allowClientCredentials) {
+            throw new AuthServiceError({
+                code: 'invalid_grant',
+                message: 'Grant type "client_credentials" is not enabled.',
+            });
+        }
+        return {
+            grantType,
+            clientId,
+            clientSecret,
+        };
+    }
+    throw new AuthServiceError({
+        code: 'invalid_request',
+        message: `Unsupported grant_type "${grantType}".`,
+    });
+}
+export function appendUrlParams(baseUrl, params) {
+    const url = new URL(baseUrl);
+    Object.entries(params).forEach(([name, value]) => {
+        if (value !== undefined) {
+            url.searchParams.set(name, value);
+        }
+    });
+    return url.toString();
+}
+export function toSingleString(value) {
+    return toNonEmptyString(value);
+}

package/src/next/shared/well-known-utils.d.ts

@@ -0,0 +1,46 @@
+import type { OAuthGrantType } from '../../core/adapters/oauth-grant-type';
+export declare function resolveRequestOrigin(input: {
+    requestUrl?: string;
+    hostHeader?: string;
+    forwardedHostHeader?: string;
+    forwardedProtoHeader?: string;
+    fallbackOrigin?: string;
+}): string;
+export type WellKnownMetadata = {
+    oauthProtectedResource: {
+        resource: string;
+        authorization_servers: string[];
+    };
+    oauthAuthorizationServer: {
+        issuer: string;
+        authorization_endpoint: string;
+        token_endpoint: string;
+        response_types_supported: string[];
+        grant_types_supported: OAuthGrantType[];
+        code_challenge_methods_supported: Array<'S256' | 'plain'>;
+        token_endpoint_auth_methods_supported: string[];
+        scopes_supported: string[];
+    };
+    openidConfiguration: {
+        issuer: string;
+        authorization_endpoint: string;
+        token_endpoint: string;
+        response_types_supported: string[];
+        grant_types_supported: OAuthGrantType[];
+        code_challenge_methods_supported: Array<'S256' | 'plain'>;
+        scopes_supported: string[];
+        token_endpoint_auth_methods_supported: string[];
+    };
+};
+export declare function buildWellKnownMetadata(input: {
+    issuer: string;
+    authorizationEndpoint?: string;
+    tokenEndpoint?: string;
+    protectedResource?: string;
+    authorizationServers?: readonly string[];
+    responseTypesSupported?: readonly string[];
+    grantTypesSupported?: readonly OAuthGrantType[];
+    codeChallengeMethodsSupported?: ReadonlyArray<'S256' | 'plain'>;
+    tokenEndpointAuthMethodsSupported?: readonly string[];
+    scopesSupported?: readonly string[];
+}): WellKnownMetadata;

package/src/next/shared/well-known-utils.js

@@ -0,0 +1,108 @@
+function firstHeaderToken(value) {
+    if (!value) {
+        return undefined;
+    }
+    const first = value.split(',')[0]?.trim();
+    return first && first.length > 0 ? first : undefined;
+}
+function normalizeOrigin(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Origin must be a non-empty string.');
+    }
+    if (/^https?:\/\//i.test(trimmed)) {
+        return new URL(trimmed).origin;
+    }
+    return new URL(`https://${trimmed}`).origin;
+}
+function normalizePathOrUrl(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Path must be a non-empty string.');
+    }
+    return trimmed;
+}
+function resolveAbsoluteUrl(origin, pathOrUrl) {
+    const normalized = normalizePathOrUrl(pathOrUrl);
+    if (/^https?:\/\//i.test(normalized)) {
+        return new URL(normalized).toString();
+    }
+    const withLeadingSlash = normalized.startsWith('/')
+        ? normalized
+        : `/${normalized}`;
+    return new URL(withLeadingSlash, origin).toString();
+}
+export function resolveRequestOrigin(input) {
+    if (input.requestUrl) {
+        try {
+            return new URL(input.requestUrl).origin;
+        }
+        catch {
+            // Falls through to header-based resolution.
+        }
+    }
+    const forwardedHost = firstHeaderToken(input.forwardedHostHeader);
+    const forwardedProto = firstHeaderToken(input.forwardedProtoHeader);
+    if (forwardedHost) {
+        const protocol = forwardedProto ?? 'https';
+        return normalizeOrigin(`${protocol}://${forwardedHost}`);
+    }
+    const host = firstHeaderToken(input.hostHeader);
+    if (host) {
+        const protocol = forwardedProto ??
+            (host.includes('localhost') || host.startsWith('127.')
+                ? 'http'
+                : 'https');
+        return normalizeOrigin(`${protocol}://${host}`);
+    }
+    return normalizeOrigin(input.fallbackOrigin ?? 'http://localhost');
+}
+export function buildWellKnownMetadata(input) {
+    const issuer = normalizeOrigin(input.issuer);
+    const authorizationEndpoint = resolveAbsoluteUrl(issuer, input.authorizationEndpoint ?? '/authorize');
+    const tokenEndpoint = resolveAbsoluteUrl(issuer, input.tokenEndpoint ?? '/token');
+    const protectedResource = resolveAbsoluteUrl(issuer, input.protectedResource ?? '/');
+    const authorizationServers = (input.authorizationServers ?? [issuer]).map(server => normalizeOrigin(server));
+    const responseTypesSupported = [
+        ...(input.responseTypesSupported ?? ['code']),
+    ];
+    const grantTypesSupported = [
+        ...(input.grantTypesSupported ?? ['authorization_code', 'refresh_token']),
+    ];
+    const codeChallengeMethodsSupported = [
+        ...(input.codeChallengeMethodsSupported ?? ['S256', 'plain']),
+    ];
+    const tokenEndpointAuthMethodsSupported = [
+        ...(input.tokenEndpointAuthMethodsSupported ?? [
+            'client_secret_basic',
+            'client_secret_post',
+        ]),
+    ];
+    const scopesSupported = [...(input.scopesSupported ?? ['mcp:access'])];
+    return {
+        oauthProtectedResource: {
+            resource: protectedResource,
+            authorization_servers: authorizationServers,
+        },
+        oauthAuthorizationServer: {
+            issuer,
+            authorization_endpoint: authorizationEndpoint,
+            token_endpoint: tokenEndpoint,
+            response_types_supported: responseTypesSupported,
+            grant_types_supported: grantTypesSupported,
+            code_challenge_methods_supported: codeChallengeMethodsSupported,
+            token_endpoint_auth_methods_supported: tokenEndpointAuthMethodsSupported,
+            scopes_supported: scopesSupported,
+        },
+        openidConfiguration: {
+            issuer,
+            authorization_endpoint: authorizationEndpoint,
+            token_endpoint: tokenEndpoint,
+            response_types_supported: responseTypesSupported,
+            grant_types_supported: grantTypesSupported,
+            code_challenge_methods_supported: codeChallengeMethodsSupported,
+            token_endpoint_auth_methods_supported: tokenEndpointAuthMethodsSupported,
+            scopes_supported: scopesSupported,
+        },
+    };
+}

package/src/testing/in-memory/in-memory-access-token-revocation-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { AccessTokenRevocationAdapter } from '../../core/adapters/access-token-revocation-adapter';
+export declare function createInMemoryAccessTokenRevocationAdapter(): AccessTokenRevocationAdapter;

package/src/testing/in-memory/in-memory-access-token-revocation-adapter.js

@@ -0,0 +1,14 @@
+export function createInMemoryAccessTokenRevocationAdapter() {
+    const revokedJtis = new Map();
+    return {
+        async revokeJti(input) {
+            revokedJtis.set(input.jti, {
+                expiresAtUnix: input.expiresAtUnix,
+                ...(input.reason === undefined ? {} : { reason: input.reason }),
+            });
+        },
+        async isRevoked(jti) {
+            return revokedJtis.has(jti);
+        },
+    };
+}

package/src/testing/in-memory/in-memory-authorization-code-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { AuthorizationCodeAdapter } from '../../core/adapters/authorization-code-adapter';
+export declare function createInMemoryAuthorizationCodeAdapter<TUserId>(): AuthorizationCodeAdapter<TUserId>;

package/src/testing/in-memory/in-memory-authorization-code-adapter.js

@@ -0,0 +1,36 @@
+export function createInMemoryAuthorizationCodeAdapter() {
+    const records = new Map();
+    return {
+        async create(input) {
+            records.set(input.codeHash, {
+                userId: input.userId,
+                codeHash: input.codeHash,
+                clientId: input.clientId,
+                redirectUri: input.redirectUri,
+                codeChallenge: input.codeChallenge,
+                codeMethod: input.codeMethod,
+                expiresAtUnix: input.expiresAtUnix,
+            });
+        },
+        async consume(codeHash, nowUnix) {
+            const record = records.get(codeHash);
+            if (!record) {
+                return null;
+            }
+            if (record.consumedAtUnix === undefined ||
+                record.consumedAtUnix === null) {
+                record.consumedAtUnix = nowUnix;
+                records.set(codeHash, record);
+            }
+            return {
+                userId: record.userId,
+                clientId: record.clientId,
+                redirectUri: record.redirectUri,
+                codeChallenge: record.codeChallenge,
+                codeMethod: record.codeMethod,
+                expiresAtUnix: record.expiresAtUnix,
+                consumedAtUnix: record.consumedAtUnix,
+            };
+        },
+    };
+}

package/src/testing/in-memory/in-memory-oauth-client-adapter.d.ts

@@ -0,0 +1,14 @@
+import type { OAuthClientAdapter } from '../../core/adapters/oauth-client-adapter';
+import type { OAuthGrantType } from '../../core/adapters/oauth-grant-type';
+import type { AuthActor } from '../../core/types/auth-contract';
+export type InMemoryOAuthClient<TActor extends AuthActor, TUserId> = {
+    clientId: string;
+    clientSecret: string | null;
+    actor: TActor;
+    userId: TUserId;
+    allowedGrantTypes?: readonly OAuthGrantType[];
+    disabled?: boolean;
+};
+export declare function createInMemoryOAuthClientAdapter<TActor extends AuthActor, TUserId>(input: {
+    clients: readonly InMemoryOAuthClient<TActor, TUserId>[];
+}): OAuthClientAdapter<TActor, TUserId>;

package/src/testing/in-memory/in-memory-oauth-client-adapter.js

@@ -0,0 +1,26 @@
+export function createInMemoryOAuthClientAdapter(input) {
+    const clientsById = new Map();
+    for (const client of input.clients) {
+        clientsById.set(client.clientId, client);
+    }
+    return {
+        async validateClient(request) {
+            const client = clientsById.get(request.clientId);
+            if (!client || client.disabled) {
+                return null;
+            }
+            if (client.clientSecret !== request.clientSecret) {
+                return null;
+            }
+            if (client.allowedGrantTypes !== undefined &&
+                !client.allowedGrantTypes.includes(request.grantType)) {
+                return null;
+            }
+            return {
+                clientId: client.clientId,
+                actor: client.actor,
+                userId: client.userId,
+            };
+        },
+    };
+}

package/src/testing/in-memory/in-memory-pending-auth-request-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { PendingAuthRequestAdapter } from '../../core/adapters/pending-auth-request-adapter';
+export declare function createInMemoryPendingAuthRequestAdapter<TPendingAuthRequest>(): PendingAuthRequestAdapter<TPendingAuthRequest>;

package/src/testing/in-memory/in-memory-pending-auth-request-adapter.js

@@ -0,0 +1,43 @@
+export function createInMemoryPendingAuthRequestAdapter() {
+    const records = new Map();
+    return {
+        async create(input) {
+            records.set(input.requestId, {
+                payload: structuredClone(input.payload),
+                expiresAtUnix: input.expiresAtUnix,
+            });
+        },
+        async find(requestId) {
+            const record = records.get(requestId);
+            if (!record) {
+                return null;
+            }
+            return {
+                payload: structuredClone(record.payload),
+                expiresAtUnix: record.expiresAtUnix,
+                ...(record.consumedAtUnix === undefined
+                    ? {}
+                    : { consumedAtUnix: record.consumedAtUnix }),
+            };
+        },
+        async consume(requestId, nowUnix) {
+            const record = records.get(requestId);
+            if (!record) {
+                return null;
+            }
+            if (record.consumedAtUnix === undefined ||
+                record.consumedAtUnix === null) {
+                record.consumedAtUnix = nowUnix;
+                records.set(requestId, record);
+            }
+            return {
+                payload: structuredClone(record.payload),
+                expiresAtUnix: record.expiresAtUnix,
+                consumedAtUnix: record.consumedAtUnix,
+            };
+        },
+        async delete(requestId) {
+            records.delete(requestId);
+        },
+    };
+}

package/src/testing/in-memory/in-memory-refresh-token-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { RefreshTokenAdapter } from '../../core/adapters/refresh-token-adapter';
+export declare function createInMemoryRefreshTokenAdapter<TSessionId>(): RefreshTokenAdapter<TSessionId>;