@absolutejs/auth 0.56.3 → 0.56.5

package/dist/abuse/captcha.d.ts

@@ -0,0 +1,11 @@
+import type { AbuseContext } from './config';
+export declare const verifyHcaptcha: ({ secret }: {
+    secret: string;
+}) => (token: string | undefined, context: AbuseContext) => Promise<boolean>;
+export declare const verifyRecaptcha: ({ minScore, secret }: {
+    minScore?: number;
+    secret: string;
+}) => (token: string | undefined, context: AbuseContext) => Promise<boolean>;
+export declare const verifyTurnstile: ({ secret }: {
+    secret: string;
+}) => (token: string | undefined, context: AbuseContext) => Promise<boolean>;

package/dist/abuse/config.d.ts

@@ -0,0 +1,29 @@
+export type AbuseAction = 'allow' | 'challenge' | 'deny';
+export type AbuseSignal = 'blocked_ip' | 'bot' | 'captcha_failed' | 'not_allowlisted';
+export type BotClass = 'agent' | 'bot' | 'crawler' | 'human';
+export type AbuseContext = {
+    captchaToken?: string;
+    ip?: string;
+    userAgent?: string;
+};
+export type AbuseReason = {
+    action: AbuseAction;
+    signal: AbuseSignal;
+};
+export type AbuseAssessment = {
+    action: AbuseAction;
+    reasons: AbuseReason[];
+};
+export type AbuseConfig = {
+    botAction?: AbuseAction;
+    captchaAction?: AbuseAction;
+    classifyBot?: (context: AbuseContext) => BotClass | Promise<BotClass>;
+    ipAllow?: string[];
+    ipDeny?: string[];
+    verifyCaptcha?: (token: string | undefined, context: AbuseContext) => boolean | Promise<boolean>;
+};
+export declare const assessAbuse: (config: AbuseConfig, context: AbuseContext) => Promise<AbuseAssessment>;
+export declare const createAbuseGuard: (config: AbuseConfig) => {
+    assess: (context: AbuseContext) => Promise<AbuseAssessment>;
+};
+export declare const defaultBotClassifier: (context: AbuseContext) => "bot" | "crawler" | "human";

package/dist/actions.d.ts

@@ -0,0 +1,27 @@
+export type AuthEventName = 'postLogin' | 'postLogout' | 'postMfa' | 'postOauthCallback' | 'postRegister' | 'preLogin' | 'preRegister';
+export type AuthActionContext<UserType> = {
+    email?: string;
+    event: AuthEventName;
+    ip?: string;
+    metadata?: Record<string, unknown>;
+    user?: UserType;
+    userAgent?: string;
+};
+export type AuthActionResult = {
+    kind: 'deny';
+    reason: string;
+} | {
+    kind: 'pass';
+} | {
+    kind: 'redirect';
+    url: string;
+};
+export type AuthAction<UserType> = {
+    event: AuthEventName | AuthEventName[];
+    handler: (context: AuthActionContext<UserType>) => AuthActionResult | Promise<AuthActionResult>;
+    name: string;
+};
+export type AuthPipeline<UserType> = {
+    run: (event: AuthEventName, context: Omit<AuthActionContext<UserType>, 'event'>) => Promise<AuthActionResult>;
+};
+export declare const createActionPipeline: <UserType>(actions: AuthAction<UserType>[]) => AuthPipeline<UserType>;

package/dist/agents/config.d.ts

@@ -0,0 +1,44 @@
+import type { RouteString } from '../types';
+import type { AgentCredentialVerifier, AgentDelegationStore, AgentRegistrationStore } from './types';
+import type { AgentRegistrationProtocolConfig } from './registration';
+export declare const DEFAULT_AGENT_RESOURCE_METADATA_ROUTE: RouteString;
+export type AgentRegistrationDiscoveryMetadata = {
+    claim_endpoint: string;
+    identity_assertion: {
+        assertion_types_supported: string[];
+    };
+    identity_endpoint: string;
+    identity_types_supported: string[];
+    skill: string;
+};
+export type AgentAuthConfig = {
+    /** Permit registered agents to authenticate without a user delegation. Secure
+     * default is false; enable for machine-only resources. */
+    allowUndelegated?: boolean;
+    /** Open auth.md agent-registration support. Implemented natively by Absolute
+     * Auth and projected through OAuth discovery; no WorkOS service is required. */
+    agentRegistration?: AgentRegistrationProtocolConfig;
+    authorizationServer: string;
+    delegationStore: AgentDelegationStore;
+    logoUri?: string;
+    metadataRoute?: RouteString;
+    /** Authorization-server route prefix. Defaults to `/oauth2`; used to derive
+     * the authoritative token endpoint advertised by the generated guide. */
+    oidcRoute?: RouteString;
+    registrationStore: AgentRegistrationStore;
+    /** Treat clients created through RFC 7591 DCR as agent registrations. Explicitly
+     * opt-in because a deployment may also use DCR for ordinary relying parties. */
+    registerDynamicClients?: boolean;
+    resource: string;
+    resourceName?: string;
+    scopes: string[];
+    verifyCredential: AgentCredentialVerifier;
+};
+export declare const agentProtectedResourceMetadata: (config: Pick<AgentAuthConfig, "authorizationServer" | "logoUri" | "resource" | "resourceName" | "scopes">) => {
+    resource: string;
+    scopes_supported: string[];
+    resource_name?: string | undefined;
+    resource_logo_uri?: string | undefined;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+};

package/dist/agents/context.d.ts

@@ -0,0 +1,46 @@
+import { Elysia } from 'elysia';
+import { type AgentAuthConfig } from './config';
+import type { AgentPrincipal } from './types';
+type AgentAuthFailure = {
+    code: 'Forbidden' | 'Unauthorized';
+    message: 'Agent is not authenticated' | 'Insufficient agent scopes';
+};
+export declare const agentAuthChallenge: ({ config, error, requiredScopes }: {
+    config: AgentAuthConfig;
+    error?: "invalid_token" | "insufficient_scope";
+    requiredScopes?: string[];
+}) => string;
+export declare const agentResourceMetadataUrl: (config: AgentAuthConfig) => string;
+export declare const agentAuthContextPlugin: (config?: AgentAuthConfig) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {
+        readonly protectAgent: <AuthReturn, AuthFailReturn>(requiredScopes: string[], handleAuth: (principal: AgentPrincipal) => AuthReturn | Promise<AuthReturn>, handleAuthFail?: (error: AgentAuthFailure) => AuthFailReturn | Promise<AuthFailReturn>) => Promise<Response | AuthReturn | NonNullable<Awaited<AuthFailReturn>>>;
+    };
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: import("elysia").ExtractErrorFromHandle<{
+        readonly protectAgent: <AuthReturn, AuthFailReturn>(requiredScopes: string[], handleAuth: (principal: AgentPrincipal) => AuthReturn | Promise<AuthReturn>, handleAuthFail?: (error: AgentAuthFailure) => AuthFailReturn | Promise<AuthFailReturn>) => Promise<Response | AuthReturn | NonNullable<Awaited<AuthFailReturn>>>;
+    }>;
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;
+export {};

package/dist/agents/principal.d.ts

@@ -0,0 +1,4 @@
+import type { AgentAuthConfig } from './config';
+import type { AgentPrincipal } from './types';
+export declare const agentHasScopes: (principal: AgentPrincipal | undefined, requiredScopes: string[]) => boolean;
+export declare const resolveAgentPrincipal: (request: Request, config: AgentAuthConfig) => Promise<AgentPrincipal | undefined>;

package/dist/agents/registration.d.ts

@@ -0,0 +1,162 @@
+import type { AccessTokenStore } from '../apikeys/types';
+import { type SigningKey } from '../oidc/keys';
+import type { RouteString } from '../types';
+import type { AgentAuthConfig, AgentRegistrationDiscoveryMetadata } from './config';
+import type { AgentIdentityRegistration, AgentIdentityRegistrationKind, AgentIdentityRegistrationStore, VerifiedAgentIdentityAssertion } from './types';
+export declare const AGENT_CLAIM_GRANT_TYPE: "urn:workos:agent-auth:grant-type:claim";
+export declare const AGENT_IDENTITY_ASSERTION_GRANT_TYPE: "urn:ietf:params:oauth:grant-type:jwt-bearer";
+export declare const AGENT_IDENTITY_ASSERTION_TYPE: "urn:ietf:params:oauth:token-type:id-jag";
+export type AgentRegistrationAuthenticatedUser = {
+    email?: string;
+    userId: string;
+};
+export type AgentRegistrationProtocolConfig = {
+    accessTokenStore: AccessTokenStore;
+    allowAnonymous?: boolean;
+    allowServiceAuth?: boolean;
+    assertionTtlMs?: number;
+    attemptTtlMs?: number;
+    claimRoute?: RouteString;
+    claimTtlMs?: number;
+    completeRoute?: RouteString;
+    guideRoute?: RouteString;
+    identityRoute?: RouteString;
+    identityStore: AgentIdentityRegistrationStore;
+    maxAuthenticationAgeMs?: number;
+    maxCodeAttempts?: number;
+    pollIntervalSeconds?: number;
+    postClaimScopes: string[];
+    preClaimScopes?: string[];
+    resolveAuthenticatedUser: (request: Request) => Promise<AgentRegistrationAuthenticatedUser | undefined>;
+    /** Match a cryptographically verified upstream identity to local state. A
+     * userId permits immediate registration; omitting it requires a user claim. */
+    resolveVerifiedIdentity?: (identity: VerifiedAgentIdentityAssertion) => Promise<{
+        userId?: string;
+    } | undefined>;
+    /** Bulk-revokes access tokens for an agent. Required for anonymous
+     * registration and recommended for immediate cleanup on any revocation. It
+     * must be idempotent because atomic state updates may be retried. */
+    revokeAccessTokens?: (agentId: string) => Promise<void>;
+    signingKey: SigningKey;
+    tokenTtlMs?: number;
+    verifyIdentityAssertion?: (assertion: string) => Promise<VerifiedAgentIdentityAssertion | undefined>;
+};
+export type AgentRegistrationEndpoints = {
+    claimEndpoint: string;
+    completeEndpoint: string;
+    guide: string;
+    identityEndpoint: string;
+    tokenEndpoint: string;
+};
+export declare const agentRegistrationDiscoveryMetadata: (config: AgentAuthConfig) => AgentRegistrationDiscoveryMetadata;
+export declare const agentRegistrationEndpoints: (config: AgentAuthConfig) => AgentRegistrationEndpoints;
+/** Generates the agent-readable companion document. Endpoint URLs and support
+ * flags come from the same structured configuration used for discovery, so the
+ * prose cannot silently drift from the authorization server metadata. */
+export declare const generateAgentRegistrationGuide: (config: AgentAuthConfig) => string;
+declare const createFlow: ({ agentId, kind, loginHint, now, registration, status, upstream, userId, withAttempt }: {
+    agentId: string;
+    kind: AgentIdentityRegistrationKind;
+    loginHint?: string;
+    now: number;
+    registration: AgentRegistrationProtocolConfig;
+    status: AgentIdentityRegistration["status"];
+    upstream?: AgentIdentityRegistration["upstream"];
+    userId?: string;
+    withAttempt?: string;
+}) => Promise<{
+    attempt: {
+        attempt: {
+            attempts: number;
+            email: string;
+            expiresAt: number;
+            tokenHash: string;
+            userCodeHash: string;
+        };
+        attemptToken: string;
+        expiresAt: number;
+        userCode: string;
+    } | undefined;
+    claimToken: string;
+    flow: AgentIdentityRegistration;
+}>;
+export declare const issueAgentServiceAssertion: (config: AgentAuthConfig, flow: AgentIdentityRegistration, now?: number) => Promise<{
+    assertion: string;
+    expiresAt: number;
+}>;
+declare const ceremony: (config: AgentAuthConfig, flow: AgentIdentityRegistration, attempt: NonNullable<Awaited<ReturnType<typeof createFlow>>["attempt"]>) => {
+    expires_in: number;
+    interval: number;
+    user_code: string;
+    verification_uri: string;
+};
+export type StartAgentRegistrationInput = {
+    type: 'anonymous';
+} | {
+    loginHint: string;
+    type: 'service_auth';
+} | {
+    assertion: string;
+    assertionType: typeof AGENT_IDENTITY_ASSERTION_TYPE;
+    type: 'identity_assertion';
+};
+export type StartAgentRegistrationResult = {
+    error: string;
+    message?: string;
+    status: 400 | 401 | 403;
+} | {
+    assertionExpires: number;
+    claim?: ReturnType<typeof ceremony>;
+    claimToken?: string;
+    claimTokenExpires?: number;
+    identityAssertion?: string;
+    preClaimScopes?: string[];
+    postClaimScopes: string[];
+    registrationId: string;
+    registrationType: AgentIdentityRegistrationKind;
+    status: 200;
+};
+export declare const startAgentRegistration: (config: AgentAuthConfig, input: StartAgentRegistrationInput, now?: number) => Promise<StartAgentRegistrationResult>;
+export type BeginAgentClaimResult = {
+    error: 'claim_expired' | 'invalid_claim_token';
+    status: 400;
+} | {
+    error: 'concurrent_update';
+    status: 409;
+} | {
+    claimAttempt: ReturnType<typeof ceremony>;
+    status: 200;
+};
+export declare const beginAgentClaim: (config: AgentAuthConfig, input: {
+    claimToken: string;
+    email: string;
+}, now?: number) => Promise<BeginAgentClaimResult>;
+export type CompleteAgentClaimResult = {
+    error: 'claim_expired' | 'concurrent_update' | 'invalid_claim_attempt' | 'user_code_invalid' | 'wrong_user';
+    status: 400 | 403 | 409 | 429;
+} | {
+    status: 204;
+};
+export declare const completeAgentClaim: (config: AgentAuthConfig, input: {
+    attemptToken: string;
+    request: Request;
+    userCode: string;
+}, now?: number) => Promise<CompleteAgentClaimResult>;
+export type AgentTokenGrantResult = {
+    body: Record<string, unknown>;
+    status: 200;
+} | {
+    body: {
+        error: string;
+    };
+    status: 400;
+};
+export declare const createAgentRegistrationCredentialVerifier: (accessTokenStore: AccessTokenStore, identityStore?: AgentIdentityRegistrationStore) => (request: Request) => Promise<{
+    agentId: string;
+    expiresAt: number;
+    scopes: string[];
+    userId: string | undefined;
+} | undefined>;
+export declare const handleAgentTokenGrant: (config: AgentAuthConfig, body: Record<string, string | undefined>, now?: number) => Promise<AgentTokenGrantResult | undefined>;
+export declare const revokeAgentIdentityRegistration: (config: AgentAuthConfig, registrationId: string, now?: number) => Promise<boolean>;
+export {};

package/dist/agents/routes.d.ts

@@ -0,0 +1,321 @@
+import { Elysia } from 'elysia';
+import { type AgentAuthConfig } from './config';
+import { agentAuthChallenge } from './context';
+import { agentRegistrationDiscoveryMetadata } from './registration';
+export { agentAuthChallenge, agentRegistrationDiscoveryMetadata };
+export declare const agentAuthPlugin: (config?: AgentAuthConfig) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {
+        readonly protectAgent: <AuthReturn, AuthFailReturn>(requiredScopes: string[], handleAuth: (principal: import("./types").AgentPrincipal) => AuthReturn | Promise<AuthReturn>, handleAuthFail?: (error: {
+            code: "Forbidden" | "Unauthorized";
+            message: "Agent is not authenticated" | "Insufficient agent scopes";
+        }) => AuthFailReturn | Promise<AuthFailReturn>) => Promise<Response | AuthReturn | NonNullable<Awaited<AuthFailReturn>>>;
+    };
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: import("elysia").ExtractErrorFromHandle<{
+        readonly protectAgent: <AuthReturn, AuthFailReturn>(requiredScopes: string[], handleAuth: (principal: import("./types").AgentPrincipal) => AuthReturn | Promise<AuthReturn>, handleAuthFail?: (error: {
+            code: "Forbidden" | "Unauthorized";
+            message: "Agent is not authenticated" | "Insufficient agent scopes";
+        }) => AuthFailReturn | Promise<AuthFailReturn>) => Promise<Response | AuthReturn | NonNullable<Awaited<AuthFailReturn>>>;
+    }>;
+}, {} | {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: {
+                    resource: string;
+                    scopes_supported: string[];
+                    resource_name?: string | undefined;
+                    resource_logo_uri?: string | undefined;
+                    authorization_servers: string[];
+                    bearer_methods_supported: string[];
+                };
+            };
+        };
+    };
+} | ({
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: {
+                    resource: string;
+                    scopes_supported: string[];
+                    resource_name?: string | undefined;
+                    resource_logo_uri?: string | undefined;
+                    authorization_servers: string[];
+                    bearer_methods_supported: string[];
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+}), {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;
+export declare const agentAuthRoutes: (config?: AgentAuthConfig) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}> | Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: {
+                    resource: string;
+                    scopes_supported: string[];
+                    resource_name?: string | undefined;
+                    resource_logo_uri?: string | undefined;
+                    authorization_servers: string[];
+                    bearer_methods_supported: string[];
+                };
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}> | Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: {
+                    resource: string;
+                    scopes_supported: string[];
+                    resource_name?: string | undefined;
+                    resource_logo_uri?: string | undefined;
+                    authorization_servers: string[];
+                    bearer_methods_supported: string[];
+                };
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+} & {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;