actor-gate 0.1.0

package/src/core/services/direct-auth-service.d.ts

@@ -0,0 +1,50 @@
+import type { AccessTokenRevocationAdapter } from '../adapters/access-token-revocation-adapter';
+import type { ObservabilityConfig } from '../adapters/observability-hooks';
+import type { RefreshTokenAdapter } from '../adapters/refresh-token-adapter';
+import type { SessionAdapter } from '../adapters/session-adapter';
+import type { AuthActor } from '../types/auth-contract';
+import type { AccessTokenService, CreateAccessTokenServiceInput } from './access-token-service';
+import type { RefreshTokenMode, RefreshTokenReuseRevokeScope, ValidatedAccessTokenResult } from './contracts';
+export type CreateDirectAuthServiceInput<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>> = {
+    accessTokenService: AccessTokenService<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;
+    sessionAdapter: SessionAdapter<TSessionId, TUserId, TActor, TServerSessionData>;
+    refreshTokenAdapter: RefreshTokenAdapter<TSessionId>;
+    accessTokenRevocationAdapter?: AccessTokenRevocationAdapter;
+    hashToken: (token: string) => string;
+    generateToken: () => string;
+    refreshTokenTtlSeconds: number;
+    refreshTokenMode?: RefreshTokenMode;
+    revokeScopeOnReuse?: RefreshTokenReuseRevokeScope;
+    nowUnix?: () => number;
+    buildClientSessionData?: CreateAccessTokenServiceInput<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>['buildClientSessionData'];
+    observability?: ObservabilityConfig<TActor>;
+};
+export type DirectAuthService<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>> = {
+    validateAccessToken(input: {
+        accessToken: string;
+        requestId?: string;
+        expectedAudience?: string;
+        allowedActors?: readonly TActor[] | ReadonlySet<TActor>;
+    }): Promise<ValidatedAccessTokenResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>>;
+    refresh(input: {
+        refreshToken: string;
+        requestId?: string;
+    }): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+        accessClaims: ValidatedAccessTokenResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>['claims'];
+        clientSession: ValidatedAccessTokenResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>['clientSession'];
+    }>;
+    logout(input: {
+        requestId?: string;
+        sessionId?: TSessionId;
+        refreshToken?: string;
+        accessTokenJti?: string;
+        accessTokenExpiresAtUnix?: number;
+    }): Promise<{
+        sessionRevoked: boolean;
+        refreshTokenRevoked: boolean;
+        accessTokenRevoked: boolean;
+    }>;
+};
+export declare function createDirectAuthService<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>>(input: CreateDirectAuthServiceInput<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>): DirectAuthService<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;

package/src/core/services/direct-auth-service.js

@@ -0,0 +1,267 @@
+import { buildClientSession } from '../sessions/client-session';
+import { AuthServiceError, isAuthServiceError } from './auth-error';
+import { emitAuditEvent, emitMetric, 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.`,
+        });
+    }
+}
+async function revokeOnRefreshTokenReuse(input) {
+    switch (input.scope) {
+        case 'token':
+            await input.refreshTokenAdapter.revoke(input.tokenHash, input.nowUnix);
+            return;
+        case 'family':
+            await input.refreshTokenAdapter.revokeFamily(input.familyId, input.nowUnix);
+            return;
+        case 'session':
+            await input.refreshTokenAdapter.revokeFamily(input.familyId, input.nowUnix);
+            await input.sessionAdapter.revoke(input.sessionId, input.nowUnix);
+            return;
+    }
+}
+export function createDirectAuthService(input) {
+    const nowUnix = input.nowUnix ?? (() => Math.floor(Date.now() / 1000));
+    const refreshTokenMode = input.refreshTokenMode ?? 'rotate_with_reuse_detection';
+    const revokeScopeOnReuse = input.revokeScopeOnReuse ?? 'family';
+    assertPositiveSafeInteger(input.refreshTokenTtlSeconds, 'refreshTokenTtlSeconds');
+    return {
+        validateAccessToken(validationInput) {
+            return input.accessTokenService.validateAccessToken(validationInput);
+        },
+        async refresh({ refreshToken, requestId }) {
+            const now = nowUnix();
+            const tokenHash = input.hashToken(refreshToken);
+            try {
+                let refreshRecord;
+                if (refreshTokenMode === 'reuse') {
+                    const found = await input.refreshTokenAdapter.find(tokenHash);
+                    if (!found) {
+                        throw new AuthServiceError({
+                            code: 'invalid_grant',
+                            message: 'Refresh token is invalid.',
+                        });
+                    }
+                    refreshRecord = found;
+                }
+                else {
+                    const consumed = await input.refreshTokenAdapter.consume(tokenHash, now);
+                    if (!consumed) {
+                        throw new AuthServiceError({
+                            code: 'invalid_grant',
+                            message: 'Refresh token is invalid.',
+                        });
+                    }
+                    if (consumed.consumedAtUnix !== now) {
+                        if (refreshTokenMode === 'rotate_with_reuse_detection') {
+                            await revokeOnRefreshTokenReuse({
+                                scope: revokeScopeOnReuse,
+                                refreshTokenAdapter: input.refreshTokenAdapter,
+                                sessionAdapter: input.sessionAdapter,
+                                tokenHash,
+                                familyId: consumed.familyId,
+                                sessionId: consumed.sessionId,
+                                nowUnix: now,
+                            });
+                            await emitAuditEvent({
+                                observability: input.observability,
+                                requestId,
+                                event: {
+                                    name: 'refresh_token_reuse_detected',
+                                    atUnix: now,
+                                    reason: 'refresh_token_reused',
+                                    metadata: { revokeScopeOnReuse },
+                                },
+                            });
+                        }
+                        throw new AuthServiceError({
+                            code: 'invalid_grant',
+                            message: 'Refresh token has already been used.',
+                        });
+                    }
+                    refreshRecord = consumed;
+                }
+                if (refreshRecord.revokedAtUnix !== undefined &&
+                    refreshRecord.revokedAtUnix !== null &&
+                    refreshRecord.revokedAtUnix <= now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Refresh token has been revoked.',
+                    });
+                }
+                if (refreshRecord.expiresAtUnix <= now) {
+                    throw new AuthServiceError({
+                        code: 'invalid_grant',
+                        message: 'Refresh token has expired.',
+                    });
+                }
+                const session = await input.sessionAdapter.findById(refreshRecord.sessionId);
+                if (!session) {
+                    throw new AuthServiceError({
+                        code: 'session_not_found',
+                        message: 'Session was not found.',
+                    });
+                }
+                if (session.revokedAt !== undefined &&
+                    session.revokedAt !== null &&
+                    session.revokedAt <= now) {
+                    throw new AuthServiceError({
+                        code: 'session_revoked',
+                        message: 'Session was revoked.',
+                    });
+                }
+                if (session.expiresAt <= now) {
+                    throw new AuthServiceError({
+                        code: 'session_expired',
+                        message: 'Session has expired.',
+                    });
+                }
+                const issued = await input.accessTokenService.issueAccessToken({
+                    session,
+                    ...(requestId === undefined ? {} : { requestId }),
+                });
+                const clientSession = buildClientSession({
+                    session,
+                    ...(input.buildClientSessionData === undefined
+                        ? {}
+                        : { buildClientSessionData: input.buildClientSessionData }),
+                });
+                let nextRefreshToken;
+                if (refreshTokenMode !== 'reuse') {
+                    nextRefreshToken = input.generateToken();
+                    await input.refreshTokenAdapter.create({
+                        sessionId: session.sessionId,
+                        tokenHash: input.hashToken(nextRefreshToken),
+                        expiresAtUnix: now + input.refreshTokenTtlSeconds,
+                        familyId: refreshRecord.familyId,
+                        parentTokenHash: tokenHash,
+                    });
+                    await emitAuditEvent({
+                        observability: input.observability,
+                        requestId,
+                        event: {
+                            name: 'refresh_token_rotated',
+                            atUnix: now,
+                            actor: session.actor,
+                        },
+                    });
+                    await emitMetric({
+                        observability: input.observability,
+                        requestId,
+                        metric: {
+                            name: 'auth.refresh.rotated',
+                            value: 1,
+                            tags: { mode: refreshTokenMode },
+                        },
+                    });
+                }
+                return {
+                    accessToken: issued.accessToken,
+                    accessClaims: issued.claims,
+                    ...(nextRefreshToken === undefined
+                        ? {}
+                        : { refreshToken: nextRefreshToken }),
+                    clientSession,
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'direct-auth-service.refresh',
+                    error,
+                    requestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to refresh direct-auth session.',
+                    cause: error,
+                });
+            }
+        },
+        async logout({ requestId, sessionId, refreshToken, accessTokenJti, accessTokenExpiresAtUnix, }) {
+            const now = nowUnix();
+            if (sessionId === undefined &&
+                refreshToken === undefined &&
+                accessTokenJti === undefined) {
+                throw new AuthServiceError({
+                    code: 'invalid_request',
+                    message: 'At least one of sessionId, refreshToken, or accessTokenJti must be provided.',
+                });
+            }
+            try {
+                let sessionRevoked = false;
+                let refreshTokenRevoked = false;
+                let accessTokenRevoked = false;
+                if (sessionId !== undefined) {
+                    await input.sessionAdapter.revoke(sessionId, now);
+                    sessionRevoked = true;
+                    await emitAuditEvent({
+                        observability: input.observability,
+                        requestId,
+                        event: {
+                            name: 'session_revoked',
+                            atUnix: now,
+                        },
+                    });
+                }
+                if (refreshToken !== undefined) {
+                    const refreshTokenHash = input.hashToken(refreshToken);
+                    const token = await input.refreshTokenAdapter.find(refreshTokenHash);
+                    await input.refreshTokenAdapter.revoke(refreshTokenHash, now);
+                    if (token) {
+                        await input.refreshTokenAdapter.revokeFamily(token.familyId, now);
+                        refreshTokenRevoked = true;
+                    }
+                }
+                if (accessTokenJti !== undefined) {
+                    if (accessTokenExpiresAtUnix === undefined) {
+                        throw new AuthServiceError({
+                            code: 'invalid_request',
+                            message: 'accessTokenExpiresAtUnix is required when accessTokenJti is provided.',
+                        });
+                    }
+                    assertPositiveSafeInteger(accessTokenExpiresAtUnix, 'accessTokenExpiresAtUnix');
+                    if (!input.accessTokenRevocationAdapter) {
+                        throw new AuthServiceError({
+                            code: 'invalid_request',
+                            message: 'accessTokenRevocationAdapter is required to revoke access token jti.',
+                        });
+                    }
+                    await input.accessTokenRevocationAdapter.revokeJti({
+                        jti: accessTokenJti,
+                        expiresAtUnix: accessTokenExpiresAtUnix,
+                        reason: 'logout',
+                    });
+                    accessTokenRevoked = true;
+                }
+                return {
+                    sessionRevoked,
+                    refreshTokenRevoked,
+                    accessTokenRevoked,
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'direct-auth-service.logout',
+                    error,
+                    requestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to process logout.',
+                    cause: error,
+                });
+            }
+        },
+    };
+}

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

@@ -0,0 +1,7 @@
+export { AuthServiceError, authErrorToHttpStatus, isAuthServiceError, type AuthServiceErrorCode, } from './auth-error';
+export { createAccessTokenService, type AccessTokenService, type CreateAccessTokenServiceInput, } from './access-token-service';
+export type { RevocationGuarantee, SessionMode } from './revocation-policy';
+export { createDirectAuthService, type CreateDirectAuthServiceInput, type DirectAuthService, } from './direct-auth-service';
+export { createOAuthService, type CreateOAuthServiceInput, type OAuthService, } from './oauth-service';
+export { createMcpAuthService, type CreateMcpAuthServiceInput, type McpAuthService, type McpAuthenticationResult, } from './mcp-auth-service';
+export type { IssuedAccessToken, OAuthPendingRequest, RefreshTokenMode, RefreshTokenReuseRevokeScope, ValidatedAccessTokenResult, } from './contracts';

package/src/core/services/index.js

@@ -0,0 +1,5 @@
+export { AuthServiceError, authErrorToHttpStatus, isAuthServiceError, } from './auth-error';
+export { createAccessTokenService, } from './access-token-service';
+export { createDirectAuthService, } from './direct-auth-service';
+export { createOAuthService, } from './oauth-service';
+export { createMcpAuthService, } from './mcp-auth-service';

package/src/core/services/mcp-auth-service.d.ts

@@ -0,0 +1,39 @@
+import type { AccessTokenSource, AccessTokenTransportAdapter, AccessTokenTransportInput } from '../adapters/access-token-transport-adapter';
+import type { AuthorizationHooks } from '../adapters/authorization-hooks';
+import type { ObservabilityConfig } from '../adapters/observability-hooks';
+import type { AccessClaims, AuthActor } from '../types/auth-contract';
+import type { AccessTokenService } from './access-token-service';
+import type { ValidatedAccessTokenResult } from './contracts';
+export type CreateMcpAuthServiceInput<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>> = {
+    accessTokenService: AccessTokenService<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;
+    accessTokenTransportAdapter: AccessTokenTransportAdapter<TActor>;
+    authorizationHooks?: AuthorizationHooks<TActor, TUserId>;
+    observability?: ObservabilityConfig<TActor>;
+    unauthenticatedMethods?: ReadonlySet<string>;
+    denyUserActorForTools?: boolean;
+    extractScopes?: (claims: AccessClaims<TActor, TExtClaims>) => string[];
+    nowUnix?: () => number;
+};
+export type McpAuthenticationResult<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>> = {
+    rpcMethods: string[];
+    requiresAuthentication: boolean;
+    authenticated: boolean;
+    tokenSource?: AccessTokenSource;
+    auth?: ValidatedAccessTokenResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;
+};
+export type McpAuthService<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>> = {
+    authenticateRequest(input: {
+        body: unknown;
+        transport: AccessTokenTransportInput;
+        requestId?: string;
+        expectedAudience?: string;
+        allowedActors?: readonly TActor[] | ReadonlySet<TActor>;
+    }): Promise<McpAuthenticationResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>>;
+    attachContext<TContext extends Record<string, unknown>>(input: {
+        context: TContext;
+        authentication: McpAuthenticationResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;
+    }): TContext & {
+        auth?: ValidatedAccessTokenResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;
+    };
+};
+export declare function createMcpAuthService<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>>(input: CreateMcpAuthServiceInput<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>): McpAuthService<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;

package/src/core/services/mcp-auth-service.js

@@ -0,0 +1,170 @@
+import { DEFAULT_UNAUTHENTICATED_RPC_METHODS, getRpcMethodsFromBody, requiresAuth, } from '../../mcp/json-rpc-auth';
+import { AuthServiceError, isAuthServiceError } from './auth-error';
+import { emitAuditEvent, reportServiceError } from './observability';
+function extractToolNameFromPayload(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        return null;
+    }
+    const method = payload.method;
+    if (method !== 'tools/call') {
+        return null;
+    }
+    const params = payload.params;
+    if (!params || typeof params !== 'object' || Array.isArray(params)) {
+        return null;
+    }
+    const toolName = params.name;
+    return typeof toolName === 'string' && toolName.length > 0 ? toolName : null;
+}
+function extractToolNamesFromBody(body) {
+    if (Array.isArray(body)) {
+        return body
+            .map(message => extractToolNameFromPayload(message))
+            .filter((toolName) => toolName !== null);
+    }
+    const toolName = extractToolNameFromPayload(body);
+    return toolName ? [toolName] : [];
+}
+function defaultExtractScopes(claims) {
+    const scopeValue = claims.ext
+        ? claims.ext.scopes
+        : undefined;
+    if (!Array.isArray(scopeValue)) {
+        return [];
+    }
+    if (!scopeValue.every(item => typeof item === 'string')) {
+        return [];
+    }
+    return [...scopeValue];
+}
+export function createMcpAuthService(input) {
+    const nowUnix = input.nowUnix ?? (() => Math.floor(Date.now() / 1000));
+    const unauthenticatedMethods = input.unauthenticatedMethods ??
+        new Set(DEFAULT_UNAUTHENTICATED_RPC_METHODS);
+    const denyUserActorForTools = input.denyUserActorForTools ?? true;
+    const extractScopes = input.extractScopes ?? defaultExtractScopes;
+    return {
+        async authenticateRequest({ body, transport, requestId, expectedAudience, allowedActors, }) {
+            const rpcMethods = getRpcMethodsFromBody(body);
+            const requiresAuthentication = rpcMethods.some(method => requiresAuth(method, unauthenticatedMethods));
+            if (!requiresAuthentication) {
+                return {
+                    rpcMethods,
+                    requiresAuthentication: false,
+                    authenticated: false,
+                };
+            }
+            const now = nowUnix();
+            try {
+                const extractedToken = input.accessTokenTransportAdapter.extractAccessToken({
+                    transport,
+                });
+                if (!extractedToken.token) {
+                    throw new AuthServiceError({
+                        code: 'unauthorized',
+                        message: 'Access token is required for authenticated MCP methods.',
+                    });
+                }
+                const validated = await input.accessTokenService.validateAccessToken({
+                    accessToken: extractedToken.token,
+                    ...(requestId === undefined ? {} : { requestId }),
+                    ...(expectedAudience === undefined ? {} : { expectedAudience }),
+                    ...(allowedActors === undefined ? {} : { allowedActors }),
+                });
+                const toolNames = extractToolNamesFromBody(body);
+                if (toolNames.length > 0 &&
+                    denyUserActorForTools &&
+                    validated.claims.actor === 'USER') {
+                    await emitAuditEvent({
+                        observability: input.observability,
+                        requestId,
+                        event: {
+                            name: 'mcp_tool_call_denied',
+                            atUnix: now,
+                            actor: validated.claims.actor,
+                            userId: validated.claims.uid,
+                            ...(validated.claims.cid === undefined
+                                ? {}
+                                : { clientId: validated.claims.cid }),
+                            reason: 'user_actor_not_allowed',
+                        },
+                    });
+                    throw new AuthServiceError({
+                        code: 'forbidden',
+                        message: 'Actor USER is not allowed to call MCP tools.',
+                    });
+                }
+                if (toolNames.length > 0 && input.authorizationHooks?.canCallMcpTool) {
+                    const scopes = extractScopes(validated.claims);
+                    for (const toolName of toolNames) {
+                        const decision = await input.authorizationHooks.canCallMcpTool({
+                            actor: validated.claims.actor,
+                            userId: validated.authContext.userId,
+                            ...(validated.claims.cid === undefined
+                                ? {}
+                                : { clientId: validated.claims.cid }),
+                            toolName,
+                            scopes,
+                        });
+                        if (!decision.allowed) {
+                            await emitAuditEvent({
+                                observability: input.observability,
+                                requestId,
+                                event: {
+                                    name: 'mcp_tool_call_denied',
+                                    atUnix: now,
+                                    actor: validated.claims.actor,
+                                    userId: validated.claims.uid,
+                                    ...(validated.claims.cid === undefined
+                                        ? {}
+                                        : { clientId: validated.claims.cid }),
+                                    reason: decision.reason ?? 'authorization_hook_denied',
+                                    metadata: { toolName },
+                                },
+                            });
+                            throw new AuthServiceError({
+                                code: 'forbidden',
+                                message: decision.reason ??
+                                    'Tool access denied by authorization hook.',
+                            });
+                        }
+                    }
+                }
+                return {
+                    rpcMethods,
+                    requiresAuthentication: true,
+                    authenticated: true,
+                    ...(extractedToken.source === undefined
+                        ? {}
+                        : { tokenSource: extractedToken.source }),
+                    auth: validated,
+                };
+            }
+            catch (error) {
+                if (isAuthServiceError(error)) {
+                    throw error;
+                }
+                await reportServiceError({
+                    observability: input.observability,
+                    where: 'mcp-auth-service.authenticateRequest',
+                    error,
+                    requestId,
+                });
+                throw new AuthServiceError({
+                    code: 'system_error',
+                    message: 'Failed to authenticate MCP request.',
+                    cause: error,
+                });
+            }
+        },
+        attachContext({ context, authentication }) {
+            if (!authentication.authenticated || authentication.auth === undefined) {
+                return context;
+            }
+            return {
+                ...context,
+                auth: authentication.auth,
+            };
+        },
+    };
+}

package/src/core/services/oauth-service.d.ts

@@ -0,0 +1,91 @@
+import type { AuthorizationCodeAdapter } from '../adapters/authorization-code-adapter';
+import type { OAuthClientAdapter } from '../adapters/oauth-client-adapter';
+import type { OAuthPolicy } from '../adapters/oauth-policy';
+import type { ObservabilityConfig } from '../adapters/observability-hooks';
+import type { PendingAuthRequestAdapter } from '../adapters/pending-auth-request-adapter';
+import type { RefreshTokenAdapter } from '../adapters/refresh-token-adapter';
+import type { SessionAdapter } from '../adapters/session-adapter';
+import type { AccessClaims, AuthActor } from '../types/auth-contract';
+import type { AccessTokenService } from './access-token-service';
+import type { OAuthPendingRequest } from './contracts';
+export type CreateOAuthServiceInput<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>> = {
+    accessTokenService: AccessTokenService<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>;
+    sessionAdapter: SessionAdapter<TSessionId, TUserId, TActor, TServerSessionData>;
+    authorizationCodeAdapter: AuthorizationCodeAdapter<TUserId>;
+    pendingAuthRequestAdapter: PendingAuthRequestAdapter<OAuthPendingRequest>;
+    oauthClientAdapter: OAuthClientAdapter<TActor, TUserId>;
+    oauthPolicy: OAuthPolicy<TActor>;
+    refreshTokenAdapter?: RefreshTokenAdapter<TSessionId>;
+    hashToken: (token: string) => string;
+    generateToken: () => string;
+    authorizationCodeTtlSeconds: number;
+    pendingAuthRequestTtlSeconds: number;
+    refreshTokenTtlSeconds?: number;
+    nowUnix?: () => number;
+    observability?: ObservabilityConfig<TActor>;
+};
+export type OAuthService<TUserId, TActor extends AuthActor = AuthActor, TExtClaims extends Record<string, unknown> = Record<string, never>> = {
+    startAuthorization(input: {
+        requestId: string;
+        clientId: string;
+        redirectUri: string;
+        codeChallenge: string;
+        codeMethod: OAuthPendingRequest['codeMethod'];
+        scopes: string[];
+        state?: string;
+        auditRequestId?: string;
+    }): Promise<{
+        requestId: string;
+        expiresAtUnix: number;
+    }>;
+    confirmAuthorization(input: {
+        requestId: string;
+        userId: TUserId;
+        approved: boolean;
+        auditRequestId?: string;
+    }): Promise<{
+        approved: false;
+        redirectUri: string;
+        state?: string;
+    } | {
+        approved: true;
+        authorizationCode: string;
+        redirectUri: string;
+        state?: string;
+        expiresAtUnix: number;
+    }>;
+    exchangeAuthorizationCode(input: {
+        clientId: string;
+        clientSecret: string | null;
+        authorizationCode: string;
+        redirectUri: string;
+        codeVerifier: string;
+        sessionTtlSeconds: number;
+        issueRefreshToken?: boolean;
+        auditRequestId?: string;
+    }): Promise<{
+        accessToken: string;
+        accessClaims: AccessClaims<TActor, TExtClaims>;
+        refreshToken?: string;
+    }>;
+    exchangeRefreshToken(input: {
+        clientId: string;
+        clientSecret: string | null;
+        refreshToken: string;
+        auditRequestId?: string;
+    }): Promise<{
+        accessToken: string;
+        accessClaims: AccessClaims<TActor, TExtClaims>;
+        refreshToken: string;
+    }>;
+    exchangeClientCredentials(input: {
+        clientId: string;
+        clientSecret: string | null;
+        sessionTtlSeconds: number;
+        auditRequestId?: string;
+    }): Promise<{
+        accessToken: string;
+        accessClaims: AccessClaims<TActor, TExtClaims>;
+    }>;
+};
+export declare function createOAuthService<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>>(input: CreateOAuthServiceInput<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>): OAuthService<TUserId, TActor, TExtClaims>;