actor-gate 0.1.0

package/src/core/services/oauth-service.js

@@ -0,0 +1,571 @@
+import { verifyPkce } from '../oauth/pkce';
+import { AuthServiceError, isAuthServiceError } from './auth-error';
+import { emitAuditEvent, reportServiceError } from './observability';
+function assertPositiveSafeInteger(value, fieldName) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new AuthServiceError({
+            code: 'invalid_request',
+            message: `${fieldName} must be a positive safe integer.`,
+        });
+    }
+}
+export function createOAuthService(input) {
+    const nowUnix = input.nowUnix ?? (() => Math.floor(Date.now() / 1000));
+    assertPositiveSafeInteger(input.authorizationCodeTtlSeconds, 'authorizationCodeTtlSeconds');
+    assertPositiveSafeInteger(input.pendingAuthRequestTtlSeconds, 'pendingAuthRequestTtlSeconds');
+    if (input.refreshTokenAdapter) {
+        if (input.refreshTokenTtlSeconds === undefined) {
+            throw new AuthServiceError({
+                code: 'invalid_request',
+                message: 'refreshTokenTtlSeconds is required when refreshTokenAdapter is configured.',
+            });
+        }
+        assertPositiveSafeInteger(input.refreshTokenTtlSeconds, 'refreshTokenTtlSeconds');
+    }
+    return {
+        async startAuthorization({ requestId, clientId, redirectUri, codeChallenge, codeMethod, scopes, state, auditRequestId, }) {
+            const now = nowUnix();
+            if (requestId.length === 0) {
+                throw new AuthServiceError({
+                    code: 'invalid_request',
+                    message: 'requestId must be a non-empty string.',
+                });
+            }
+            if (codeChallenge.length === 0) {
+                throw new AuthServiceError({
+                    code: 'invalid_request',
+                    message: 'codeChallenge must be a non-empty string.',
+                });
+            }
+            if (!input.oauthPolicy.isAllowedClientId(clientId)) {
+                throw new AuthServiceError({
+                    code: 'invalid_client',
+                    message: 'OAuth client is not allowed.',
+                });
+            }
+            if (!input.oauthPolicy.isAllowedRedirectUri(redirectUri)) {
+                throw new AuthServiceError({
+                    code: 'invalid_request',
+                    message: 'Redirect URI is not allowed.',
+                });
+            }
+            if (!scopes.includes(input.oauthPolicy.requiredScopeForMcp)) {
+                throw new AuthServiceError({
+                    code: 'invalid_request',
+                    message: 'Missing required MCP scope.',
+                });
+            }
+            try {
+                const expiresAtUnix = now + input.pendingAuthRequestTtlSeconds;
+                await input.pendingAuthRequestAdapter.create({
+                    requestId,
+                    payload: {
+                        clientId,
+                        redirectUri,
+                        codeChallenge,
+                        codeMethod,
+                        scopes: [...scopes],
+                        ...(state === undefined ? {} : { state }),
+                    },
+                    expiresAtUnix,
+                });
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId: auditRequestId,
+                    event: {
+                        name: 'oauth_authorize_started',
+                        atUnix: now,
+                        clientId,
+                    },
+                });
+                return {
+                    requestId,
+                    expiresAtUnix,
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'oauth-service.startAuthorization',
+                    error,
+                    requestId: auditRequestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to start OAuth authorization.',
+                    cause: error,
+                });
+            }
+        },
+        async confirmAuthorization({ requestId, userId, approved, auditRequestId, }) {
+            const now = nowUnix();
+            try {
+                const pendingRequest = await input.pendingAuthRequestAdapter.consume(requestId, now);
+                if (!pendingRequest) {
+                    throw new AuthServiceError({
+                        code: 'invalid_request',
+                        message: 'Authorization request was not found.',
+                    });
+                }
+                if (pendingRequest.consumedAtUnix !== now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_request',
+                        message: 'Authorization request was already consumed.',
+                    });
+                }
+                if (pendingRequest.expiresAtUnix <= now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_request',
+                        message: 'Authorization request has expired.',
+                    });
+                }
+                if (!approved) {
+                    await input.pendingAuthRequestAdapter.delete(requestId);
+                    return {
+                        approved: false,
+                        redirectUri: pendingRequest.payload.redirectUri,
+                        ...(pendingRequest.payload.state === undefined
+                            ? {}
+                            : { state: pendingRequest.payload.state }),
+                    };
+                }
+                const authorizationCode = input.generateToken();
+                const authorizationCodeHash = input.hashToken(authorizationCode);
+                const expiresAtUnix = now + input.authorizationCodeTtlSeconds;
+                await input.authorizationCodeAdapter.create({
+                    userId,
+                    codeHash: authorizationCodeHash,
+                    clientId: pendingRequest.payload.clientId,
+                    redirectUri: pendingRequest.payload.redirectUri,
+                    codeChallenge: pendingRequest.payload.codeChallenge,
+                    codeMethod: pendingRequest.payload.codeMethod,
+                    expiresAtUnix,
+                });
+                await input.pendingAuthRequestAdapter.delete(requestId);
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId: auditRequestId,
+                    event: {
+                        name: 'oauth_code_issued',
+                        atUnix: now,
+                        clientId: pendingRequest.payload.clientId,
+                    },
+                });
+                return {
+                    approved: true,
+                    authorizationCode,
+                    redirectUri: pendingRequest.payload.redirectUri,
+                    ...(pendingRequest.payload.state === undefined
+                        ? {}
+                        : { state: pendingRequest.payload.state }),
+                    expiresAtUnix,
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'oauth-service.confirmAuthorization',
+                    error,
+                    requestId: auditRequestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to confirm OAuth authorization.',
+                    cause: error,
+                });
+            }
+        },
+        async exchangeAuthorizationCode({ clientId, clientSecret, authorizationCode, redirectUri, codeVerifier, sessionTtlSeconds, issueRefreshToken, auditRequestId, }) {
+            const now = nowUnix();
+            assertPositiveSafeInteger(sessionTtlSeconds, 'sessionTtlSeconds');
+            try {
+                if (input.oauthPolicy.isAllowedGrantType &&
+                    !input.oauthPolicy.isAllowedGrantType('authorization_code', clientId)) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Grant type is not allowed for this client.',
+                    });
+                }
+                const client = await input.oauthClientAdapter.validateClient({
+                    clientId,
+                    clientSecret,
+                    grantType: 'authorization_code',
+                });
+                if (!client) {
+                    throw new AuthServiceError({
+                        code: 'invalid_client',
+                        message: 'OAuth client credentials are invalid.',
+                    });
+                }
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId: auditRequestId,
+                    event: {
+                        name: 'oauth_client_authenticated',
+                        atUnix: now,
+                        actor: client.actor,
+                        clientId: client.clientId,
+                    },
+                });
+                if (!input.oauthPolicy.isAllowedActor(client.actor)) {
+                    throw new AuthServiceError({
+                        code: 'forbidden',
+                        message: 'OAuth actor is not allowed.',
+                    });
+                }
+                const code = await input.authorizationCodeAdapter.consume(input.hashToken(authorizationCode), now);
+                if (!code) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Authorization code is invalid.',
+                    });
+                }
+                if (code.consumedAtUnix !== now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Authorization code was already consumed.',
+                    });
+                }
+                if (code.expiresAtUnix <= now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Authorization code has expired.',
+                    });
+                }
+                if (code.clientId !== client.clientId) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Authorization code client mismatch.',
+                    });
+                }
+                if (code.redirectUri !== redirectUri) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Authorization code redirect URI mismatch.',
+                    });
+                }
+                if (!verifyPkce({
+                    codeVerifier,
+                    codeChallenge: code.codeChallenge,
+                    codeMethod: code.codeMethod,
+                })) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'PKCE verification failed.',
+                    });
+                }
+                const session = await input.sessionAdapter.create({
+                    userId: code.userId,
+                    actor: client.actor,
+                    clientId: client.clientId,
+                    ttlSeconds: sessionTtlSeconds,
+                });
+                const issued = await input.accessTokenService.issueAccessToken({
+                    session,
+                    ...(auditRequestId === undefined
+                        ? {}
+                        : { requestId: auditRequestId }),
+                });
+                const shouldIssueRefreshToken = issueRefreshToken ?? input.refreshTokenAdapter !== undefined;
+                let refreshToken;
+                if (shouldIssueRefreshToken) {
+                    if (!input.refreshTokenAdapter ||
+                        input.refreshTokenTtlSeconds === undefined) {
+                        throw new AuthServiceError({
+                            code: 'invalid_request',
+                            message: 'Refresh-token exchange is not configured for this OAuth service.',
+                        });
+                    }
+                    refreshToken = input.generateToken();
+                    await input.refreshTokenAdapter.create({
+                        sessionId: session.sessionId,
+                        tokenHash: input.hashToken(refreshToken),
+                        expiresAtUnix: now + input.refreshTokenTtlSeconds,
+                        familyId: input.generateToken(),
+                    });
+                }
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId: auditRequestId,
+                    event: {
+                        name: 'oauth_token_exchanged',
+                        atUnix: now,
+                        actor: client.actor,
+                        clientId: client.clientId,
+                        sessionId: issued.claims.sub,
+                    },
+                });
+                return {
+                    accessToken: issued.accessToken,
+                    accessClaims: issued.claims,
+                    ...(refreshToken === undefined ? {} : { refreshToken }),
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'oauth-service.exchangeAuthorizationCode',
+                    error,
+                    requestId: auditRequestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to exchange authorization code.',
+                    cause: error,
+                });
+            }
+        },
+        async exchangeClientCredentials({ clientId, clientSecret, sessionTtlSeconds, auditRequestId, }) {
+            const now = nowUnix();
+            assertPositiveSafeInteger(sessionTtlSeconds, 'sessionTtlSeconds');
+            try {
+                if (input.oauthPolicy.isAllowedGrantType &&
+                    !input.oauthPolicy.isAllowedGrantType('client_credentials', clientId)) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Grant type is not allowed for this client.',
+                    });
+                }
+                const client = await input.oauthClientAdapter.validateClient({
+                    clientId,
+                    clientSecret,
+                    grantType: 'client_credentials',
+                });
+                if (!client) {
+                    throw new AuthServiceError({
+                        code: 'invalid_client',
+                        message: 'OAuth client credentials are invalid.',
+                    });
+                }
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId: auditRequestId,
+                    event: {
+                        name: 'oauth_client_authenticated',
+                        atUnix: now,
+                        actor: client.actor,
+                        clientId: client.clientId,
+                    },
+                });
+                if (!input.oauthPolicy.isAllowedActor(client.actor)) {
+                    throw new AuthServiceError({
+                        code: 'forbidden',
+                        message: 'OAuth actor is not allowed.',
+                    });
+                }
+                const session = await input.sessionAdapter.create({
+                    userId: client.userId,
+                    actor: client.actor,
+                    clientId: client.clientId,
+                    ttlSeconds: sessionTtlSeconds,
+                });
+                const issued = await input.accessTokenService.issueAccessToken({
+                    session,
+                    ...(auditRequestId === undefined
+                        ? {}
+                        : { requestId: auditRequestId }),
+                });
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId: auditRequestId,
+                    event: {
+                        name: 'oauth_token_exchanged',
+                        atUnix: now,
+                        actor: client.actor,
+                        clientId: client.clientId,
+                        sessionId: issued.claims.sub,
+                    },
+                });
+                return {
+                    accessToken: issued.accessToken,
+                    accessClaims: issued.claims,
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'oauth-service.exchangeClientCredentials',
+                    error,
+                    requestId: auditRequestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to exchange client credentials.',
+                    cause: error,
+                });
+            }
+        },
+        async exchangeRefreshToken({ clientId, clientSecret, refreshToken, auditRequestId, }) {
+            const now = nowUnix();
+            if (!input.refreshTokenAdapter ||
+                input.refreshTokenTtlSeconds === undefined) {
+                throw new AuthServiceError({
+                    code: 'invalid_request',
+                    message: 'Refresh token support is not configured.',
+                });
+            }
+            try {
+                if (input.oauthPolicy.isAllowedGrantType &&
+                    !input.oauthPolicy.isAllowedGrantType('refresh_token', clientId)) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Grant type is not allowed for this client.',
+                    });
+                }
+                const client = await input.oauthClientAdapter.validateClient({
+                    clientId,
+                    clientSecret,
+                    grantType: 'refresh_token',
+                });
+                if (!client) {
+                    throw new AuthServiceError({
+                        code: 'invalid_client',
+                        message: 'OAuth client credentials are invalid.',
+                    });
+                }
+                if (!input.oauthPolicy.isAllowedActor(client.actor)) {
+                    throw new AuthServiceError({
+                        code: 'forbidden',
+                        message: 'OAuth actor is not allowed.',
+                    });
+                }
+                const providedRefreshTokenHash = input.hashToken(refreshToken);
+                const token = await input.refreshTokenAdapter.consume(providedRefreshTokenHash, now);
+                if (!token) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Refresh token is invalid.',
+                    });
+                }
+                if (token.consumedAtUnix !== now) {
+                    await input.refreshTokenAdapter.revokeFamily(token.familyId, now);
+                    await emitAuditEvent({
+                        observability: input.observability,
+                        requestId: auditRequestId,
+                        event: {
+                            name: 'refresh_token_reuse_detected',
+                            atUnix: now,
+                            actor: client.actor,
+                            clientId: client.clientId,
+                        },
+                    });
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Refresh token has already been consumed.',
+                    });
+                }
+                if (token.revokedAtUnix !== undefined &&
+                    token.revokedAtUnix !== null &&
+                    token.revokedAtUnix <= now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Refresh token has been revoked.',
+                    });
+                }
+                if (token.expiresAtUnix <= now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Refresh token has expired.',
+                    });
+                }
+                const session = await input.sessionAdapter.findById(token.sessionId);
+                if (!session) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Session for refresh token was not found.',
+                    });
+                }
+                if (session.userId !== client.userId ||
+                    session.actor !== client.actor ||
+                    session.clientId !== client.clientId) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Refresh token does not belong to this client identity.',
+                    });
+                }
+                if (session.revokedAt !== undefined &&
+                    session.revokedAt !== null &&
+                    session.revokedAt <= now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Session has been revoked.',
+                    });
+                }
+                if (session.expiresAt <= now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Session has expired.',
+                    });
+                }
+                const issued = await input.accessTokenService.issueAccessToken({
+                    session,
+                    ...(auditRequestId === undefined
+                        ? {}
+                        : { requestId: auditRequestId }),
+                });
+                const rotatedRefreshToken = input.generateToken();
+                await input.refreshTokenAdapter.create({
+                    sessionId: session.sessionId,
+                    tokenHash: input.hashToken(rotatedRefreshToken),
+                    expiresAtUnix: now + input.refreshTokenTtlSeconds,
+                    familyId: token.familyId,
+                    parentTokenHash: providedRefreshTokenHash,
+                });
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId: auditRequestId,
+                    event: {
+                        name: 'refresh_token_rotated',
+                        atUnix: now,
+                        actor: client.actor,
+                        clientId: client.clientId,
+                    },
+                });
+                await emitAuditEvent({
+                    observability: input.observability,
+                    requestId: auditRequestId,
+                    event: {
+                        name: 'oauth_token_exchanged',
+                        atUnix: now,
+                        actor: client.actor,
+                        clientId: client.clientId,
+                        sessionId: issued.claims.sub,
+                    },
+                });
+                return {
+                    accessToken: issued.accessToken,
+                    accessClaims: issued.claims,
+                    refreshToken: rotatedRefreshToken,
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'oauth-service.exchangeRefreshToken',
+                    error,
+                    requestId: auditRequestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to exchange refresh token.',
+                    cause: error,
+                });
+            }
+        },
+    };
+}

package/src/core/services/observability.d.ts

@@ -0,0 +1,22 @@
+import type { AuthAuditEvent, ObservabilityConfig } from '../adapters/observability-hooks';
+import type { AuthActor } from '../types/auth-contract';
+export declare function emitAuditEvent<TActor extends AuthActor>(input: {
+    observability: ObservabilityConfig<TActor> | undefined;
+    event: AuthAuditEvent<TActor>;
+    requestId: string | undefined;
+}): Promise<void>;
+export declare function emitMetric<TActor extends AuthActor>(input: {
+    observability: ObservabilityConfig<TActor> | undefined;
+    metric: {
+        name: string;
+        value?: number;
+        tags?: Record<string, string>;
+    };
+    requestId: string | undefined;
+}): Promise<void>;
+export declare function reportServiceError<TActor extends AuthActor>(input: {
+    observability: ObservabilityConfig<TActor> | undefined;
+    where: string;
+    error: unknown;
+    requestId: string | undefined;
+}): Promise<void>;

package/src/core/services/observability.js

@@ -0,0 +1,71 @@
+async function invokeHook(input) {
+    if (!input.hook) {
+        return;
+    }
+    try {
+        await input.hook();
+    }
+    catch (hookError) {
+        const onError = input.observability?.hooks?.onError;
+        if (onError) {
+            try {
+                await onError({
+                    where: input.where,
+                    error: hookError,
+                    ...(input.requestId === undefined
+                        ? {}
+                        : { requestId: input.requestId }),
+                });
+            }
+            catch {
+                return;
+            }
+        }
+    }
+}
+export async function emitAuditEvent(input) {
+    const onAuditEvent = input.observability?.hooks?.onAuditEvent;
+    await invokeHook({
+        observability: input.observability,
+        where: 'observability.onAuditEvent',
+        requestId: input.requestId,
+        ...(onAuditEvent
+            ? {
+                hook: async () => {
+                    await onAuditEvent(input.event);
+                },
+            }
+            : {}),
+    });
+}
+export async function emitMetric(input) {
+    const onMetric = input.observability?.hooks?.onMetric;
+    await invokeHook({
+        observability: input.observability,
+        where: 'observability.onMetric',
+        requestId: input.requestId,
+        ...(onMetric
+            ? {
+                hook: async () => {
+                    await onMetric(input.metric);
+                },
+            }
+            : {}),
+    });
+}
+export async function reportServiceError(input) {
+    const onError = input.observability?.hooks?.onError;
+    if (!onError) {
+        return;
+    }
+    try {
+        await onError({
+            where: input.where,
+            error: input.error,
+            ...(input.requestId === undefined ? {} : { requestId: input.requestId }),
+        });
+    }
+    catch {
+        // Observability failures are intentionally non-blocking.
+    }
+}

package/src/core/services/revocation-policy.d.ts

@@ -0,0 +1,21 @@
+import type { AccessTokenRevocationAdapter } from '../adapters/access-token-revocation-adapter';
+export type SessionMode = 'stateful' | 'stateless' | 'hybrid';
+export type RevocationGuarantee = 'strict' | 'bounded' | 'ttl_only';
+export declare function shouldValidateSession(input: {
+    sessionMode: SessionMode;
+    hasSessionAdapter: boolean;
+}): boolean;
+export declare function shouldCheckAccessTokenRevocation(input: {
+    revocationGuarantee: RevocationGuarantee;
+    hasRevocationAdapter: boolean;
+}): boolean;
+export type RevocationDecisionEngine = {
+    isAccessTokenRevoked(input: {
+        jti: string;
+        nowUnix: number;
+        revocationGuarantee: RevocationGuarantee;
+        boundedRevocationCacheSeconds: number;
+        accessTokenRevocationAdapter?: AccessTokenRevocationAdapter;
+    }): Promise<boolean>;
+};
+export declare function createRevocationDecisionEngine(): RevocationDecisionEngine;