authhero 9.9.1 → 9.10.0

package/dist/types/authentication-flows/authorization-code.d.ts

@@ -3,6 +3,7 @@ import { z } from "@hono/zod-openapi";
 import { Bindings, Variables } from "../types";
 import { TokenResponse } from "@authhero/adapter-interfaces";
 import { GrantFlowUserResult } from "src/types/GrantFlowResult";
+import { EnrichedClient } from "../helpers/client";
 export declare const authorizationCodeGrantParamsSchema: z.ZodObject<{
     grant_type: z.ZodLiteral<"authorization_code">;
     client_id: z.ZodString;
@@ -16,7 +17,7 @@ export type AuthorizationCodeGrantTypeParams = z.infer<typeof authorizationCodeG
 export declare function authorizationCodeGrantUser(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: AuthorizationCodeGrantTypeParams): Promise<GrantFlowUserResult>;
+}>, params: AuthorizationCodeGrantTypeParams, preloadedClient?: EnrichedClient): Promise<GrantFlowUserResult>;
 export declare function authorizationCodeGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;

package/dist/types/authentication-flows/client-credentials.d.ts

@@ -2,6 +2,7 @@ import { Context } from "hono";
 import { z } from "@hono/zod-openapi";
 import { Bindings, Variables } from "../types";
 import { GrantFlowResult } from "../types/GrantFlowResult";
+import { EnrichedClient } from "../helpers/client";
 export declare const clientCredentialGrantParamsSchema: z.ZodObject<{
     grant_type: z.ZodLiteral<"client_credentials">;
     scope: z.ZodOptional<z.ZodString>;
@@ -13,4 +14,4 @@ export declare const clientCredentialGrantParamsSchema: z.ZodObject<{
 export declare function clientCredentialsGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: z.infer<typeof clientCredentialGrantParamsSchema>): Promise<GrantFlowResult>;
+}>, params: z.infer<typeof clientCredentialGrantParamsSchema>, preloadedClient?: EnrichedClient): Promise<GrantFlowResult>;

package/dist/types/authentication-flows/passwordless.d.ts

@@ -1,6 +1,7 @@
 import { Context } from "hono";
 import { z } from "@hono/zod-openapi";
 import { Bindings, Variables } from "../types";
+import { EnrichedClient } from "../helpers/client";
 import { GrantFlowUserResult } from "../types/GrantFlowResult";
 export declare const passwordlessGrantParamsSchema: z.ZodObject<{
     client_id: z.ZodString;
@@ -45,7 +46,7 @@ export declare const passwordlessGrantParamsSchema: z.ZodObject<{
 export declare function passwordlessGrantUser(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, { client_id, username, otp, scope, audience, authParams, enforceIpCheck, }: z.input<typeof passwordlessGrantParamsSchema>): Promise<{
+}>, { client_id, username, otp, scope, audience, authParams, enforceIpCheck, }: z.input<typeof passwordlessGrantParamsSchema>, preloadedClient?: EnrichedClient): Promise<{
     user: {
         connection: string;
         email_verified: boolean;
@@ -474,7 +475,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
         custom_login_page_preview?: string | undefined;
         form_template?: string | undefined;
         addons?: Record<string, any> | undefined;
-        token_endpoint_auth_method?: "none" | "client_secret_post" | "client_secret_basic" | "client_secret_jwt" | "private_key_jwt" | undefined;
+        token_endpoint_auth_method?: "client_secret_post" | "client_secret_basic" | "none" | "client_secret_jwt" | "private_key_jwt" | undefined;
         client_metadata?: Record<string, string> | undefined;
         hide_sign_up_disabled_error?: boolean | undefined;
         mobile?: Record<string, any> | undefined;
@@ -557,8 +558,8 @@ export declare function passwordlessGrantUser(ctx: Context<{
         } | undefined;
         authenticated_at?: string | undefined;
     };
-    connectionType: "username" | "email" | "sms";
-    authConnection: "username" | "email" | "sms";
+    connectionType: "email" | "username" | "sms";
+    authConnection: "email" | "username" | "sms";
     session_id: string | undefined;
     authParams: {
         audience?: string | undefined;
@@ -612,7 +613,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
 export declare function passwordlessOtpGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: z.input<typeof passwordlessGrantParamsSchema>): Promise<GrantFlowUserResult>;
+}>, params: z.input<typeof passwordlessGrantParamsSchema>, preloadedClient?: EnrichedClient): Promise<GrantFlowUserResult>;
 export declare function passwordlessGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;

package/dist/types/authentication-flows/refresh-token.d.ts

@@ -1,6 +1,7 @@
 import { Context } from "hono";
 import { Bindings, Variables, GrantFlowUserResult } from "../types";
 import { z } from "@hono/zod-openapi";
+import { EnrichedClient } from "../helpers/client";
 export declare const refreshTokenParamsSchema: z.ZodObject<{
     grant_type: z.ZodLiteral<"refresh_token">;
     client_id: z.ZodString;
@@ -12,4 +13,4 @@ export declare const refreshTokenParamsSchema: z.ZodObject<{
 export declare function refreshTokenGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: z.infer<typeof refreshTokenParamsSchema>): Promise<GrantFlowUserResult>;
+}>, params: z.infer<typeof refreshTokenParamsSchema>, preloadedClient?: EnrichedClient): Promise<GrantFlowUserResult>;

package/dist/types/authentication-flows/token-exchange.d.ts

@@ -1,6 +1,7 @@
 import { Context } from "hono";
 import { z } from "@hono/zod-openapi";
 import { Bindings, Variables, GrantFlowUserResult } from "../types";
+import { EnrichedClient } from "../helpers/client";
 export declare const TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
 export declare const tokenExchangeParamsSchema: z.ZodObject<{
     grant_type: z.ZodLiteral<"urn:ietf:params:oauth:grant-type:token-exchange">;
@@ -16,4 +17,4 @@ export type TokenExchangeParams = z.infer<typeof tokenExchangeParamsSchema>;
 export declare function tokenExchangeGrant(ctx: Context<{
     Bindings: Bindings;
     Variables: Variables;
-}>, params: TokenExchangeParams): Promise<GrantFlowUserResult>;
+}>, params: TokenExchangeParams, preloadedClient?: EnrichedClient): Promise<GrantFlowUserResult>;

package/dist/types/helpers/client-assertion-replay.d.ts

@@ -0,0 +1,21 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+export interface ConsumeClientAssertionJtiParams {
+    clientId: string;
+    /** The assertion's `jti`. When absent there is nothing to spend. */
+    jti?: string;
+    /** The assertion's `exp`, in seconds — when the marker becomes collectable. */
+    exp: number;
+}
+/**
+ * Spend a client assertion's `jti`.
+ *
+ * @returns false when this assertion has already been presented (the caller
+ *   must reject it as `invalid_client`), true otherwise. An assertion carrying
+ *   no `jti` cannot be tracked, so it returns true — its replay window is
+ *   bounded only by the assertion lifetime cap.
+ */
+export declare function consumeClientAssertionJti(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, params: ConsumeClientAssertionJtiParams): Promise<boolean>;

package/dist/types/helpers/client-assertion.d.ts

@@ -1,5 +1,12 @@
 import { LoadClientKeysOptions, ClientWithKeys } from "./client-keys";
 declare const ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/**
+ * Default upper bound on a client assertion's lifetime. RFC 7523 gives no
+ * limit, so without one a client can mint an assertion valid for a year and a
+ * captured assertion stays usable for that whole window. 300s matches the
+ * usual guidance for a single-use token presented directly to the endpoint.
+ */
+declare const DEFAULT_MAX_LIFETIME_SECONDS = 300;
 export type ClientAssertionMethod = "private_key_jwt" | "client_secret_jwt";
 export declare class ClientAssertionError extends Error {
     code: "invalid_client" | "invalid_request" | "unsupported_alg" | "missing_keys";
@@ -18,6 +25,14 @@ export interface VerifyClientAssertionOptions extends LoadClientKeysOptions {
     acceptedAudiences: string[];
     /** Clock-skew leeway in seconds. Defaults to 30. */
     leewaySeconds?: number;
+    /**
+     * Maximum accepted assertion lifetime in seconds. Rejects an assertion whose
+     * `exp - iat` exceeds this, and caps the absolute `exp` at `now + max` so an
+     * assertion that omits `iat` cannot sidestep the bound. Defaults to
+     * DEFAULT_MAX_LIFETIME_SECONDS (300) — the window a captured assertion stays
+     * replayable in is bounded by this, so keep it short.
+     */
+    maxLifetimeSeconds?: number;
     /** Override Date.now() for tests. */
     now?: () => number;
 }
@@ -26,8 +41,15 @@ export interface VerifiedClientAssertion {
     clientId: string;
     /** Which authentication method was actually used. */
     method: ClientAssertionMethod;
-    /** Optional jti claim — useful if callers want to enforce replay protection. */
+    /**
+     * The `jti` claim, when present. `consumeClientAssertionJti`
+     * (helpers/client-assertion-replay.ts) spends it so an assertion cannot be
+     * presented twice; the token endpoint calls that after this verifier
+     * returns.
+     */
     jti?: string;
+    /** The `exp` claim, in seconds. Bounds how long the `jti` must be remembered. */
+    exp: number;
     /** The full verified payload, in case callers need other claims. */
     payload: Record<string, unknown>;
 }
@@ -46,4 +68,4 @@ export interface VerifiedClientAssertion {
  *   any of the iss/sub/aud/exp checks.
  */
 export declare function verifyClientAssertion(assertion: string, client: ClientAssertionClient, opts: VerifyClientAssertionOptions): Promise<VerifiedClientAssertion>;
-export { ASSERTION_TYPE as CLIENT_ASSERTION_TYPE };
+export { ASSERTION_TYPE as CLIENT_ASSERTION_TYPE, DEFAULT_MAX_LIFETIME_SECONDS as CLIENT_ASSERTION_DEFAULT_MAX_LIFETIME_SECONDS, };

package/dist/types/helpers/default-destinations.d.ts

@@ -1,7 +1,7 @@
 import { CodeExecutor, DataAdapters } from "@authhero/adapter-interfaces";
 import { EventDestination } from "./outbox-relay";
 import { type GetServiceToken } from "./outbox-destinations/webhooks";
-import type { WebhookInvoker } from "../types/AuthHeroConfig";
+import type { OutboxPipelineConfig, WebhookInvoker } from "../types/AuthHeroConfig";
 export interface CreateDefaultDestinationsConfig {
     /**
      * Data adapter — the `logs`, `hooks`, `users`, and `logStreams` adapters are
@@ -47,6 +47,12 @@ export interface CreateDefaultDestinationsConfig {
      * failed per-request delivery would be silently skipped on retry.
      */
     codeExecutor?: CodeExecutor;
+    /**
+     * Same shape as `init({ outbox: { pipeline } })`. When set, cron-drained
+     * events are also archived to the Cloudflare Pipelines stream, matching the
+     * per-request destination list. Omit to leave the archive out entirely.
+     */
+    pipeline?: OutboxPipelineConfig;
 }
 /**
  * Build the same array of outbox destinations that authhero's per-request

package/dist/types/helpers/outbox-destinations/index.d.ts

@@ -1,2 +1,3 @@
 export { LogsDestination } from "./logs";
 export { LogStreamDestination } from "./log-streams";
+export { PipelineDestination } from "./pipeline";

package/dist/types/helpers/outbox-destinations/pipeline.d.ts

@@ -0,0 +1,63 @@
+import { AuditEvent, AuditCategory } from "@authhero/adapter-interfaces";
+import { EventDestination } from "../outbox-relay";
+/**
+ * One row of the archive table. The promoted columns are the query and
+ * erasure keys (`actor_id` / `target_id`); `event` carries the untouched
+ * `AuditEvent` so nothing is lost and the promoted set can grow later
+ * without a backfill.
+ *
+ * `actor_id` is emitted as `null` rather than omitted when the actor is
+ * anonymous, so every record has the same key set — Pipelines stream
+ * schemas are fixed once created.
+ */
+export interface PipelineRecord {
+    id: string;
+    timestamp: string;
+    tenant_id: string;
+    event_type: string;
+    log_type: string;
+    category: AuditCategory;
+    actor_id: string | null;
+    target_type: string;
+    target_id: string;
+    event: AuditEvent;
+}
+export interface PipelineDestinationOptions {
+    /** Stream HTTP ingest endpoint, e.g. `https://<stream-id>.ingest.cloudflare.com`. */
+    endpoint: string;
+    /** Stream ingest token, sent as `Authorization: Bearer`. */
+    token: string;
+    /** Per-request timeout (default: 10s). */
+    timeoutMs?: number;
+    /** Override for tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Archives audit events to a Cloudflare Pipelines stream, which lands them in
+ * R2 as an Iceberg table. See `apps/docs/architecture/audit-archive.md`.
+ *
+ * HTTP ingest is used rather than the Worker binding so the destination works
+ * in every deployment (Node included) and stays symmetric with the
+ * log-streams destination.
+ *
+ * Duplicates are expected and by design: the relay retries per event, not per
+ * destination, so a failure in a later destination re-delivers this one, and
+ * the Iceberg sink is append-only. Consumers dedup on `id` at query time.
+ */
+export declare class PipelineDestination implements EventDestination {
+    name: string;
+    private endpoint;
+    private token;
+    private timeoutMs;
+    private fetchImpl;
+    constructor(options: PipelineDestinationOptions);
+    /**
+     * Archives the audit trail, not the delivery plumbing: `hook.*` and
+     * `controlplane.sync.*` are instructions to other destinations rather than
+     * records of something a tenant did. Same filter as the log-streams
+     * destination.
+     */
+    accepts(event: AuditEvent): boolean;
+    transform(event: AuditEvent): PipelineRecord;
+    deliver(records: PipelineRecord[]): Promise<void>;
+}

package/dist/types/helpers/outbox-relay.d.ts

@@ -1,4 +1,5 @@
 import { OutboxAdapter, AuditEvent } from "@authhero/adapter-interfaces";
+import type { OutboxMetricsSink } from "../types/OutboxMetrics";
 /**
  * Interface for outbox event destinations.
  * Each destination transforms audit events into its own format and delivers them.
@@ -21,6 +22,7 @@ export interface EventDestination {
  */
 export declare function processOutboxEvents(outbox: OutboxAdapter, ids: string[], destinations: EventDestination[], options?: {
     maxRetries?: number;
+    metrics?: OutboxMetricsSink;
 }): Promise<void>;
 /**
  * Drain unprocessed events from the outbox and deliver to all destinations.
@@ -31,4 +33,5 @@ export declare function drainOutbox(outbox: OutboxAdapter, destinations: EventDe
     batchSize?: number;
     maxRetries?: number;
     retentionDays?: number;
+    metrics?: OutboxMetricsSink;
 }): Promise<void>;

package/dist/types/helpers/reserved-claims.d.ts

@@ -0,0 +1,64 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+/** RFC 9068 §2.2 + AuthHero-owned access-token claims. */
+export declare const ACCESS_TOKEN_RESERVED_CLAIMS: readonly ["iss", "sub", "aud", "exp", "nbf", "iat", "jti", "client_id", "azp", "scope", "auth_time", "acr", "amr", "act", "sid", "permissions", "tenant_id", "org_id", "org_name", "requested_userinfo_claims", "gty"];
+/** OIDC Core ID-token claims: the access-token set plus the ID-token-only ones. */
+export declare const ID_TOKEN_RESERVED_CLAIMS: readonly ["iss", "sub", "aud", "exp", "nbf", "iat", "jti", "client_id", "azp", "scope", "auth_time", "acr", "amr", "act", "sid", "permissions", "tenant_id", "org_id", "org_name", "requested_userinfo_claims", "gty", "nonce", "at_hash", "c_hash", "s_hash"];
+/**
+ * /userinfo response. The identity set only — the response body is otherwise
+ * made up of user profile claims, which hooks are expected to extend.
+ */
+export declare const USERINFO_RESERVED_CLAIMS: readonly ["iss", "sub", "aud", "exp", "nbf", "iat", "jti"];
+/**
+ * Internal `auth-service` mints. Same set as an access token except `azp`:
+ * trusted internal hook code overrides it to attribute the call to a
+ * vendor/tenant for downstream APIs while `sub` stays `auth-service`.
+ * Client-bound mints keep `azp` locked (see below).
+ */
+export declare const SERVICE_TOKEN_RESERVED_CLAIMS: ("client_id" | "scope" | "sid" | "tenant_id" | "org_id" | "org_name" | "sub" | "permissions" | "iat" | "exp" | "iss" | "aud" | "auth_time" | "acr" | "amr" | "nbf" | "jti" | "act" | "requested_userinfo_claims" | "gty")[];
+/** Client-bound mints: `azp` must stay the registered client id. */
+export declare const CLIENT_SERVICE_TOKEN_RESERVED_CLAIMS: ("client_id" | "scope" | "sid" | "tenant_id" | "org_id" | "org_name" | "sub" | "permissions" | "iat" | "exp" | "iss" | "aud" | "auth_time" | "acr" | "amr" | "azp" | "nbf" | "jti" | "act" | "requested_userinfo_claims" | "gty")[];
+export type AccessTokenReservedClaim = (typeof ACCESS_TOKEN_RESERVED_CLAIMS)[number];
+export type IdTokenReservedClaim = (typeof ID_TOKEN_RESERVED_CLAIMS)[number];
+/**
+ * The server-owned half of an access-token payload. Typing the payload literal
+ * as this makes TypeScript's excess-property check reject any claim name that
+ * isn't in `ACCESS_TOKEN_RESERVED_CLAIMS`, so a new server-owned claim cannot
+ * be added to the mint without also being reserved.
+ */
+export type ServerOwnedAccessTokenClaims = Partial<Record<AccessTokenReservedClaim, unknown>>;
+/** As `ServerOwnedAccessTokenClaims`, for the ID token. */
+export type ServerOwnedIdTokenClaims = Partial<Record<IdTokenReservedClaim, unknown>>;
+/** Which payload a custom claim is being written to. */
+export type ClaimPayloadKind = "access_token" | "id_token" | "userinfo" | "service_token" | "client_service_token";
+export declare function isReservedClaim(claim: string, kind: ClaimPayloadKind): boolean;
+export interface ApplyCustomClaimOptions {
+    /** Which payload is being written to — selects the reserved set. */
+    kind: ClaimPayloadKind;
+    /**
+     * Who is writing. Used in the warning so an operator can tell which hook
+     * dropped a claim (e.g. `onExecuteCredentialsExchange`,
+     * `template-hook:add-roles`, `createServiceToken`).
+     */
+    source: string;
+    /** Request context, when there is one — the warning goes to the tenant log. */
+    ctx?: Context<{
+        Bindings: Bindings;
+        Variables: Variables;
+    }>;
+    /** Tenant to log against. Defaults to `ctx.var.tenant_id`. */
+    tenantId?: string;
+}
+/**
+ * Write a caller-supplied claim onto a payload unless the authorization server
+ * owns that claim name.
+ *
+ * @returns true when the claim was written, false when it was dropped.
+ */
+export declare function applyCustomClaim(payload: Record<string, unknown>, claim: string, value: unknown, options: ApplyCustomClaimOptions): boolean;
+/**
+ * Bulk variant of `applyCustomClaim`. Returns a new object holding only the
+ * claims that are safe to merge, so callers can keep spreading them into a
+ * payload literal.
+ */
+export declare function applyCustomClaims(claims: Record<string, unknown> | undefined, options: ApplyCustomClaimOptions): Record<string, unknown> | undefined;

package/dist/types/helpers/run-outbox-relay.d.ts

@@ -1,5 +1,6 @@
 import { CodeExecutor, DataAdapters } from "@authhero/adapter-interfaces";
 import type { WebhookInvoker } from "../types/AuthHeroConfig";
+import type { OutboxMetricsSink } from "../types/OutboxMetrics";
 export interface RunOutboxRelayConfig {
     /** Same `DataAdapters` passed to `init()`. Must include `outbox` to drain. */
     dataAdapter: DataAdapters;
@@ -31,6 +32,13 @@ export interface RunOutboxRelayConfig {
      * silently skipped.
      */
     codeExecutor?: CodeExecutor;
+    /**
+     * Optional metrics sink — same shape as `init({ outbox: { metrics } })`.
+     * Receives `outbox_events_processed_total`,
+     * `outbox_events_dead_lettered_total` and `outbox_retry_delay_seconds` for
+     * the events this cron drain handles, tagged `source: "cron"`.
+     */
+    metrics?: OutboxMetricsSink;
 }
 /**
  * One-call outbox relay for cron / scheduled handlers.