@absolutejs/auth 0.56.4 → 0.56.5

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/registrationClient.d.ts

@@ -0,0 +1,50 @@
+type JsonObject = Record<string, unknown>;
+export type DiscoveredAgentRegistration = {
+    agentAuth: {
+        claimEndpoint: string;
+        identityAssertionTypes: string[];
+        identityEndpoint: string;
+        identityTypes: string[];
+        skill: string;
+    };
+    authorizationServer: string;
+    resource: string;
+    resourceMetadataUrl: string;
+    scopes: string[];
+    tokenEndpoint: string;
+};
+export type AgentRegistrationClientOptions = {
+    allowInsecureLocalhost?: boolean;
+    maxResponseBytes?: number;
+    request?: typeof fetch;
+};
+/** Discovers agent registration using RFC 9728 followed by RFC 8414. Network
+ * policy is injected through `request`; redirects are rejected by default. */
+export declare const createAgentRegistrationClient: (discovery: DiscoveredAgentRegistration, options?: AgentRegistrationClientOptions) => {
+    beginAnonymous: () => Promise<{
+        body: JsonObject;
+        response: Response;
+    }>;
+    beginServiceAuth: (loginHint: string) => Promise<{
+        body: JsonObject;
+        response: Response;
+    }>;
+    beginVerified: (assertion: string) => Promise<{
+        body: JsonObject;
+        response: Response;
+    }>;
+    claim: (claimToken: string, email: string) => Promise<{
+        body: JsonObject;
+        response: Response;
+    }>;
+    exchangeAssertion: (assertion: string) => Promise<{
+        body: JsonObject;
+        response: Response;
+    }>;
+    pollClaim: (claimToken: string) => Promise<{
+        body: JsonObject;
+        response: Response;
+    }>;
+};
+export declare const discoverAgentRegistration: (resource: string, options?: AgentRegistrationClientOptions) => Promise<DiscoveredAgentRegistration>;
+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: {};
+}>;

package/dist/agents/types.d.ts

@@ -0,0 +1,129 @@
+export type AgentRegistrationStatus = 'active' | 'revoked';
+export type AgentDelegationStatus = 'active' | 'revoked';
+/** A durable identity for an agent client. This is deliberately protocol-neutral:
+ * `clientId` can refer to an OAuth client, while adapters for other protocols can
+ * use `agentId` without manufacturing OAuth metadata. */
+export type AgentRegistration = {
+    agentId: string;
+    allowedScopes: string[];
+    clientId?: string;
+    createdAt: number;
+    metadata?: Record<string, unknown>;
+    name: string;
+    status: AgentRegistrationStatus;
+    updatedAt: number;
+};
+export type AgentRegistrationStore = {
+    findByAgentId: (agentId: string) => Promise<AgentRegistration | undefined>;
+    findByClientId: (clientId: string) => Promise<AgentRegistration | undefined>;
+    listRegistrations: () => Promise<AgentRegistration[]>;
+    saveRegistration: (registration: AgentRegistration) => Promise<void>;
+};
+/** A user's explicit grant to an agent. Authorization details use RFC 9396's
+ * open object shape so applications can express transaction constraints without
+ * forcing them into coarse OAuth scope strings. */
+export type AgentDelegation = {
+    agentId: string;
+    authorizationDetails?: Record<string, unknown>[];
+    createdAt: number;
+    delegationId: string;
+    expiresAt?: number;
+    organizationId?: string;
+    scopes: string[];
+    status: AgentDelegationStatus;
+    updatedAt: number;
+    userId: string;
+};
+export type AgentDelegationStore = {
+    findActiveDelegation: (query: {
+        agentId: string;
+        now?: number;
+        organizationId?: string;
+        userId: string;
+    }) => Promise<AgentDelegation | undefined>;
+    findByDelegationId: (delegationId: string) => Promise<AgentDelegation | undefined>;
+    listDelegations: (agentId?: string) => Promise<AgentDelegation[]>;
+    saveDelegation: (delegation: AgentDelegation) => Promise<void>;
+};
+/** The normalized result produced by a wire-protocol adapter. The core never
+ * handles raw provider assertions; it authorizes only this verified shape. */
+export type VerifiedAgentCredential = {
+    agentId: string;
+    claims?: Record<string, unknown>;
+    expiresAt?: number;
+    organizationId?: string;
+    resource?: string;
+    scopes: string[];
+    userId?: string;
+};
+export type AgentCredentialVerifier = (request: Request) => Promise<VerifiedAgentCredential | undefined>;
+export type AgentPrincipal = {
+    agentId: string;
+    authorizationDetails?: Record<string, unknown>[];
+    delegationId?: string;
+    kind: 'agent';
+    name: string;
+    organizationId?: string;
+    scopes: string[];
+    trust: 'delegated' | 'registered';
+    userId?: string;
+};
+export type AgentIdentityRegistrationKind = 'anonymous' | 'identity_assertion' | 'service_auth';
+export type AgentIdentityRegistrationStatus = 'claimed' | 'pending' | 'revoked';
+export type AgentClaimAttempt = {
+    attempts: number;
+    email: string;
+    expiresAt: number;
+    tokenHash: string;
+    userCodeHash: string;
+};
+/** Durable state for the open auth.md registration profile. Secrets are
+ * represented only by hashes; plaintext claim and attempt tokens are returned
+ * once to the agent and never persisted. `version` is used for compare-and-swap
+ * updates so claim completion is safe across multiple application instances. */
+export type AgentIdentityRegistration = {
+    agentId: string;
+    claimAttempt?: AgentClaimAttempt;
+    claimExpiresAt: number;
+    claimTokenHash: string;
+    createdAt: number;
+    expiresAt: number;
+    kind: AgentIdentityRegistrationKind;
+    loginHint?: string;
+    lastPolledAt?: number;
+    registrationId: string;
+    status: AgentIdentityRegistrationStatus;
+    updatedAt: number;
+    upstream?: {
+        clientId: string;
+        issuer: string;
+        subject: string;
+    };
+    userId?: string;
+    version: number;
+};
+export type AgentIdentityRegistrationStore = {
+    create: (registration: AgentIdentityRegistration) => Promise<boolean>;
+    findByClaimTokenHash: (claimTokenHash: string) => Promise<AgentIdentityRegistration | undefined>;
+    findByAgentId: (agentId: string) => Promise<AgentIdentityRegistration | undefined>;
+    findByRegistrationId: (registrationId: string) => Promise<AgentIdentityRegistration | undefined>;
+    findByUpstreamIdentity: (query: {
+        clientId: string;
+        issuer: string;
+        subject: string;
+    }) => Promise<AgentIdentityRegistration | undefined>;
+    findByAttemptTokenHash: (attemptTokenHash: string) => Promise<AgentIdentityRegistration | undefined>;
+    /** Replaces a record only when its current version equals expectedVersion. */
+    replace: (registration: AgentIdentityRegistration, expectedVersion: number) => Promise<boolean>;
+};
+export type VerifiedAgentIdentityAssertion = {
+    authenticatedAt: number;
+    clientId: string;
+    email?: string;
+    emailVerified?: boolean;
+    issuer: string;
+    name?: string;
+    phoneNumber?: string;
+    phoneNumberVerified?: boolean;
+    subject: string;
+};