@fabrika/auth 0.9.0-dev.1 → 0.9.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/auth",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,12 +12,13 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		}
 	},
@@ -27,8 +28,8 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "0.9.0-dev.1",
-		"@fabrika/jwks": "0.9.0-dev.1",
+		"@fabrika/auth-core": "0.9.0-dev.2",
+		"@fabrika/jwks": "0.9.0-dev.2",
 		"jose": "^5.9.0"
 	}
 }

package/types/src/app-schema.d.ts

@@ -0,0 +1,609 @@
+import { z } from 'zod';
+/**
+ * An app's authz vocabulary, as an app declares it and IAM reconciles it. Every role permission must
+ * name an action the same body declares — IAM's own rule, checked wherever the vocabulary is read. A
+ * contract application's roles list exact actions, and a membership role names a declared scope. The
+ * membership and link declarations name only scopes, roles and exact actions of the same body.
+ */
+export declare const appSchemaSchema: z.ZodEffects<z.ZodObject<{
+    scopes: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        in: z.ZodOptional<z.ZodString>;
+        creator: z.ZodOptional<z.ZodString>;
+        members: z.ZodOptional<z.ZodObject<{
+            manage: z.ZodString;
+            list: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            manage: string;
+            list: string;
+        }, {
+            manage: string;
+            list: string;
+        }>>;
+        directory: z.ZodOptional<z.ZodLiteral<"labels">>;
+        lookups: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        in?: string | undefined;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }, {
+        type: string;
+        in?: string | undefined;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }>, "many">;
+    actions: z.ZodArray<z.ZodObject<{
+        action: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        action: string;
+        description?: string | undefined;
+    }, {
+        action: string;
+        description?: string | undefined;
+    }>, "many">;
+    roles: z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        permissions: z.ZodArray<z.ZodString, "many">;
+        member: z.ZodOptional<z.ZodObject<{
+            scope: z.ZodString;
+            assignableBy: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        }, {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        }>>;
+        external: z.ZodOptional<z.ZodLiteral<true>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        permissions: string[];
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        external?: true | undefined;
+        description?: string | undefined;
+    }, {
+        name: string;
+        permissions: string[];
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        external?: true | undefined;
+        description?: string | undefined;
+    }>>;
+    contract: z.ZodOptional<z.ZodBoolean>;
+    links: z.ZodOptional<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodObject<{
+        dimension: z.ZodString;
+        grants: z.ZodArray<z.ZodString, "many">;
+        issuedBy: z.ZodString;
+        maxDays: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        dimension: string;
+        grants: string[];
+        issuedBy: string;
+        maxDays: number;
+    }, {
+        dimension: string;
+        grants: string[];
+        issuedBy: string;
+        maxDays: number;
+    }>>>;
+    delegations: z.ZodOptional<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodObject<{
+        action: z.ZodString;
+        dimension: z.ZodString;
+        purpose: z.ZodEnum<["members", "creates"]>;
+    }, "strip", z.ZodTypeAny, {
+        action: string;
+        dimension: string;
+        purpose: "creates" | "members";
+    }, {
+        action: string;
+        dimension: string;
+        purpose: "creates" | "members";
+    }>>>;
+    workloads: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"job">;
+        name: z.ZodString;
+        actions: z.ZodArray<z.ZodString, "many">;
+        issues: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        actions: string[];
+        kind: "job";
+        issues?: string | undefined;
+    }, {
+        name: string;
+        actions: string[];
+        kind: "job";
+        issues?: string | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"webhook">;
+        name: z.ZodString;
+        actions: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        actions: string[];
+        kind: "webhook";
+    }, {
+        name: string;
+        actions: string[];
+        kind: "webhook";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"public">;
+        name: z.ZodEffects<z.ZodString, string, string>;
+        actions: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        actions: string[];
+        kind: "public";
+    }, {
+        name: string;
+        actions: string[];
+        kind: "public";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"app">;
+        name: z.ZodString;
+        actions: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        actions: string[];
+        kind: "app";
+    }, {
+        name: string;
+        actions: string[];
+        kind: "app";
+    }>]>, "many">>;
+    locale: z.ZodOptional<z.ZodEnum<["en", "cs"]>>;
+    displayName: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    mail: z.ZodOptional<z.ZodObject<{
+        invitation: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodEnum<["en", "cs"]>, z.ZodObject<{
+            subject: z.ZodString;
+            text: z.ZodString;
+            html: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }, {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>>, Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>>, Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>>>>;
+        enrollment: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodEnum<["en", "cs"]>, z.ZodObject<{
+            subject: z.ZodString;
+            text: z.ZodString;
+            html: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }, {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>>, Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>>, Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>>>>;
+        reset: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodEnum<["en", "cs"]>, z.ZodObject<{
+            subject: z.ZodString;
+            text: z.ZodString;
+            html: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }, {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>>, Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>>, Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>>>>;
+    }, "strict", z.ZodTypeAny, {
+        invitation?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        enrollment?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        reset?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+    }, {
+        invitation?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        enrollment?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        reset?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+    }>>;
+    members: z.ZodOptional<z.ZodObject<{
+        manage: z.ZodString;
+        list: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        manage: string;
+        list: string;
+    }, {
+        manage: string;
+        list: string;
+    }>>;
+    directory: z.ZodOptional<z.ZodLiteral<"labels">>;
+}, "strip", z.ZodTypeAny, {
+    actions: {
+        action: string;
+        description?: string | undefined;
+    }[];
+    roles: Record<string, {
+        name: string;
+        permissions: string[];
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        external?: true | undefined;
+        description?: string | undefined;
+    }>;
+    scopes: {
+        type: string;
+        in?: string | undefined;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }[];
+    displayName?: string | undefined;
+    locale?: "en" | "cs" | undefined;
+    mail?: {
+        invitation?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        enrollment?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        reset?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+    } | undefined;
+    members?: {
+        manage: string;
+        list: string;
+    } | undefined;
+    directory?: "labels" | undefined;
+    contract?: boolean | undefined;
+    links?: Record<string, {
+        dimension: string;
+        grants: string[];
+        issuedBy: string;
+        maxDays: number;
+    }> | undefined;
+    delegations?: Record<string, {
+        action: string;
+        dimension: string;
+        purpose: "creates" | "members";
+    }> | undefined;
+    workloads?: ({
+        name: string;
+        actions: string[];
+        kind: "job";
+        issues?: string | undefined;
+    } | {
+        name: string;
+        actions: string[];
+        kind: "webhook";
+    } | {
+        name: string;
+        actions: string[];
+        kind: "public";
+    } | {
+        name: string;
+        actions: string[];
+        kind: "app";
+    })[] | undefined;
+}, {
+    actions: {
+        action: string;
+        description?: string | undefined;
+    }[];
+    roles: Record<string, {
+        name: string;
+        permissions: string[];
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        external?: true | undefined;
+        description?: string | undefined;
+    }>;
+    scopes: {
+        type: string;
+        in?: string | undefined;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }[];
+    displayName?: string | undefined;
+    locale?: "en" | "cs" | undefined;
+    mail?: {
+        invitation?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        enrollment?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        reset?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+    } | undefined;
+    members?: {
+        manage: string;
+        list: string;
+    } | undefined;
+    directory?: "labels" | undefined;
+    contract?: boolean | undefined;
+    links?: Record<string, {
+        dimension: string;
+        grants: string[];
+        issuedBy: string;
+        maxDays: number;
+    }> | undefined;
+    delegations?: Record<string, {
+        action: string;
+        dimension: string;
+        purpose: "creates" | "members";
+    }> | undefined;
+    workloads?: ({
+        name: string;
+        actions: string[];
+        kind: "job";
+        issues?: string | undefined;
+    } | {
+        name: string;
+        actions: string[];
+        kind: "webhook";
+    } | {
+        name: string;
+        actions: string[];
+        kind: "public";
+    } | {
+        name: string;
+        actions: string[];
+        kind: "app";
+    })[] | undefined;
+}>, {
+    actions: {
+        action: string;
+        description?: string | undefined;
+    }[];
+    roles: Record<string, {
+        name: string;
+        permissions: string[];
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        external?: true | undefined;
+        description?: string | undefined;
+    }>;
+    scopes: {
+        type: string;
+        in?: string | undefined;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }[];
+    displayName?: string | undefined;
+    locale?: "en" | "cs" | undefined;
+    mail?: {
+        invitation?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        enrollment?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        reset?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+    } | undefined;
+    members?: {
+        manage: string;
+        list: string;
+    } | undefined;
+    directory?: "labels" | undefined;
+    contract?: boolean | undefined;
+    links?: Record<string, {
+        dimension: string;
+        grants: string[];
+        issuedBy: string;
+        maxDays: number;
+    }> | undefined;
+    delegations?: Record<string, {
+        action: string;
+        dimension: string;
+        purpose: "creates" | "members";
+    }> | undefined;
+    workloads?: ({
+        name: string;
+        actions: string[];
+        kind: "job";
+        issues?: string | undefined;
+    } | {
+        name: string;
+        actions: string[];
+        kind: "webhook";
+    } | {
+        name: string;
+        actions: string[];
+        kind: "public";
+    } | {
+        name: string;
+        actions: string[];
+        kind: "app";
+    })[] | undefined;
+}, {
+    actions: {
+        action: string;
+        description?: string | undefined;
+    }[];
+    roles: Record<string, {
+        name: string;
+        permissions: string[];
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        external?: true | undefined;
+        description?: string | undefined;
+    }>;
+    scopes: {
+        type: string;
+        in?: string | undefined;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }[];
+    displayName?: string | undefined;
+    locale?: "en" | "cs" | undefined;
+    mail?: {
+        invitation?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        enrollment?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+        reset?: Partial<Record<"en" | "cs", {
+            subject: string;
+            text: string;
+            html?: string | undefined;
+        }>> | undefined;
+    } | undefined;
+    members?: {
+        manage: string;
+        list: string;
+    } | undefined;
+    directory?: "labels" | undefined;
+    contract?: boolean | undefined;
+    links?: Record<string, {
+        dimension: string;
+        grants: string[];
+        issuedBy: string;
+        maxDays: number;
+    }> | undefined;
+    delegations?: Record<string, {
+        action: string;
+        dimension: string;
+        purpose: "creates" | "members";
+    }> | undefined;
+    workloads?: ({
+        name: string;
+        actions: string[];
+        kind: "job";
+        issues?: string | undefined;
+    } | {
+        name: string;
+        actions: string[];
+        kind: "webhook";
+    } | {
+        name: string;
+        actions: string[];
+        kind: "public";
+    } | {
+        name: string;
+        actions: string[];
+        kind: "app";
+    })[] | undefined;
+}>;

package/types/src/client.d.ts

@@ -0,0 +1,28 @@
+import type { AccessTokenClaims } from '@fabrika/auth-core';
+import type { AuthContext, IamBinding, ListPrincipalsFailure, PrincipalList } from './types';
+/**
+ * Build an `AuthContext` from a verified access token and its claims — the seam every authentication
+ * path uses (the proxy-injected token). The SDK has verified the token LOCALLY; this wraps its claims in the
+ * same `permits`-backed context the RPC path returns,
+ * so `can()` / `scopedTo()` / `audit()` behave identically. A token with no `ptype` is anonymous
+ * (`principal: null`).
+ */
+export declare function buildAuthContext(binding: IamBinding, token: string, claims: AccessTokenClaims, requestId: string): AuthContext;
+/**
+ * Thin, app-facing wrapper over the IAM Worker service binding. Bakes the caller `app` id
+ * into the constructor so app code can never forget or mistype it. Depends ONLY on the
+ * `IamRpc` contract from `@fabrika/auth-core` — never on the Worker — which is what keeps the
+ * SDK worker-independent (the binding is the deployed Worker, reached at runtime).
+ */
+export declare class IamClient {
+    private readonly binding;
+    private readonly appId;
+    constructor(binding: IamBinding, appId: string);
+    /**
+     * List the app's people directory — the USER principals who can access this app. Forwards the
+     * CALLER's credential; the IAM Worker resolves the caller and scopes the roster to the
+     * verified app (you only ever see your own app's people). For an assignee picker / actor
+     * label list. Authorized for any member with a permission on the app; a zero-grant user → 403.
+     */
+    listPrincipals(req: Request): Promise<PrincipalList | ListPrincipalsFailure>;
+}

package/types/src/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed request-time errors + a small authorization helper.
+ *
+ * These are the shared structural HTTP-error contract `@fabrika/app` maps without any
+ * cross-package `instanceof`: each error exposes `{ httpStatus, type, message }` plus an optional
+ * `issues` (validation detail). A mapper reads those fields structurally — it never imports these
+ * classes — so these shapes and the framework reader are the single contract. They live in
+ * `@fabrika/auth` because `requirePermission` consumes an `AuthContext` (a client type).
+ *
+ * There is deliberately no login-bounce error here: since ADR-0022 the proxy 302s an unauthenticated
+ * browser, so an app never has to produce a login URL of its own.
+ */
+import type { Scope } from '@fabrika/auth-core';
+import type { AuthContext } from './types';
+/**
+ * The structural HTTP-error shape. Anything thrown through a request pipeline that satisfies this can be
+ * mapped to a Response without an `instanceof` check: `httpStatus` → the status, `type` → the error
+ * envelope's `type`, `message` → its `message`, `issues` → optional detail.
+ */
+export interface HttpError {
+    readonly httpStatus: number;
+    readonly type: string;
+    readonly message: string;
+    readonly issues?: unknown;
+}
+/** A caller is unauthenticated. `type: 'auth'`, status 401. */
+export declare class UnauthenticatedError extends Error implements HttpError {
+    readonly httpStatus = 401;
+    readonly type = "auth";
+    constructor(message?: string);
+}
+/** A resolved caller lacks the required permission. `type: 'forbidden'`, status 403. */
+export declare class ForbiddenError extends Error implements HttpError {
+    readonly httpStatus = 403;
+    readonly type = "forbidden";
+    constructor(message?: string);
+}
+/**
+ * Assert the caller may perform `action` (optionally within `scope`). Throws `ForbiddenError` when
+ * `auth.can(action, scope)` is false; otherwise returns. The thrown error satisfies the structural
+ * `HttpError` contract, so a pipeline maps it to a 403 without importing this module.
+ */
+export declare function requirePermission(auth: AuthContext, action: string, scope?: Scope): void;

package/types/src/iam.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `createIam` — the single request-time entry point apps use instead of hand-rolling auth.
+ *
+ * Since [ADR-0022](../../../docs/decisions/0022-the-proxy-is-the-only-enforcement-point.md) the PROXY is the only
+ * thing that enforces: it selects the endpoint, resolves the credential, and injects a verified
+ * access token as `PROXY_TOKEN_HEADER`. What is left for an app is small and fixed:
+ *   - `authenticate(request)` — read that header and verify it LOCALLY against IAM's published JWKS
+ *     (signature, `iss`, `aud`, `exp`), then build an `AuthContext`. The header is never trusted blindly.
+ *   - `listPrincipals` — the app's people directory.
+ *
+ * There is NO access decision here, no session→token exchange, and no cookie is ever written.
+ *
+ * There is also NO local mode. The SDK verifies IAM-issued tokens and nothing else, everywhere. Local
+ * development runs the real stack (`bun run local:up`), where the proxy fronts each service and IAM
+ * authenticates through its own `LOCAL_DEV_LOGIN` bypass — one dev bypass in the system, owned by the
+ * service that owns identity.
+ */
+import { type TokenAudienceProfile } from '@fabrika/auth-core';
+import { IamClient } from './client';
+import type { AuthContext, IamBinding, ListPrincipalsFailure, PrincipalList } from './types';
+import { TokenVerifier } from './verify';
+/** The env `createIam` reads. An app's Worker `Env` satisfies it structurally (extra fields are fine). */
+export interface IamEnv {
+    /** The IAM service binding, or `HttpIamRpc` off Cloudflare. Typed by the contract — never the IAM Worker. */
+    IAM?: IamBinding;
+    /** IAM origin — the token `iss` this SDK verifies against. Canonicalized once in `createIam`. */
+    FABRIKA_IAM_ISSUER?: string;
+    /** The IAM app id `<app>@<env>` every deploy writes (`FABRIKA_IAM_APP_ID`); the fallback for `opts.appId`. */
+    FABRIKA_IAM_APP_ID?: string;
+}
+/** Options for `createIam`. `appId` falls back to `env.FABRIKA_IAM_APP_ID`. */
+export interface CreateIamOptions {
+    /** The IAM app id: a platform service bakes its own in; an application reads `env.FABRIKA_IAM_APP_ID`. */
+    appId?: string;
+    /**
+     * Which tokens `authenticate` accepts. Defaults to the app's native tokens; a resource server
+     * passes `{ kind: 'resource', app, resource }` to accept OAuth tokens minted for that resource.
+     */
+    tokenAudience?: TokenAudienceProfile;
+}
+/** Why an authentication attempt produced no `AuthContext`. */
+export type AuthFailureReason = 
+/** No proxy-injected token on the request — an anonymous endpoint, or nothing is in front of the app. */
+'no_token'
+/** A token was presented and did not verify: signature, `iss`, `aud`, `exp` or claim shape. */
+ | 'invalid_token'
+/** The credential resolved to nobody — IAM says the principal is gone or disabled. */
+ | 'unknown_principal'
+/** IAM could not be consulted at all. NOT a decided negative — an incident, and never a 401. */
+ | 'unavailable';
+/**
+ * The outcome of `authenticate`. A DECIDED NEGATIVE (`invalid_token`, `unknown_principal`) is not the
+ * same as "could not consult IAM" (`unavailable`, 503) — the same three-state rule `@fabrika/proxy`
+ * implements. `authenticate` throws for neither case.
+ */
+export type AuthResult = {
+    ok: true;
+    context: AuthContext;
+} | {
+    ok: false;
+    reason: AuthFailureReason;
+    status: 401 | 403 | 503;
+};
+/** Failure half of `AuthResult` — what a caller maps to its own error envelope. */
+export type AuthFailure = Extract<AuthResult, {
+    ok: false;
+}>;
+/**
+ * The ANONYMOUS context — no principal, NO permissions (`can` → false, `scopedTo` → [] = none),
+ * `audit` a no-op. What an app sets on a request the proxy admitted through an anonymous endpoint: there is
+ * no token to verify, and nothing about the caller is known. An RPC procedure's `.require` on such a
+ * request would (correctly) 403.
+ */
+export declare function anonymousContext(): AuthContext;
+/** Internal construction config — `createIam` assembles this; apps never build it directly. */
+interface IamConfig {
+    management: IamClient;
+    binding: IamBinding;
+    verifier: TokenVerifier;
+    appId: string;
+    tokenAudience: TokenAudienceProfile;
+}
+/**
+ * The request-time IAM surface. Build it with `createIam` (the only intended entry point — the
+ * constructor takes an internal config). Bundles token verification and `listPrincipals`, both bound
+ * to the env + app id resolved at construction.
+ */
+export declare class Iam {
+    private readonly management;
+    private readonly binding;
+    private readonly verifier;
+    private readonly appId;
+    private readonly tokenAudience;
+    /** @internal — use `createIam`. */
+    constructor(config: IamConfig);
+    listPrincipals(req: Request): Promise<PrincipalList | ListPrincipalsFailure>;
+    /**
+     * Resolve the caller from the token the PROXY injected, verifying it locally against the JWKS.
+     * Never throws: an absent token, a token that does not verify, and an unreachable IAM are three
+     * distinct `ok: false` results.
+     */
+    authenticate(request: Request): Promise<AuthResult>;
+    /** Verify one token and wrap its claims in the `permits`-backed `AuthContext`. */
+    private contextFor;
+}
+/**
+ * The single request-time entry point. Reads `env.IAM` and the IAM environment names, and returns an
+ * `Iam` bound to them. Throws if the app id, the binding or the issuer is missing or unusable —
+ * there is no mode in which any of the three is optional.
+ */
+export declare function createIam(env: IamEnv, opts?: CreateIamOptions): Iam;
+export {};

package/types/src/index.d.ts

@@ -0,0 +1,20 @@
+export { IamClient } from './client';
+export { applyScope } from './scope';
+export { ForbiddenError, requirePermission, UnauthenticatedError } from './errors';
+export type { HttpError } from './errors';
+export { anonymousContext, createIam, Iam } from './iam';
+export type { AuthFailure, AuthFailureReason, AuthResult, CreateIamOptions, IamEnv } from './iam';
+export type { AuthCarrier } from './types';
+export { DecodedIamMembership, HttpIamMembership, HttpIamRpc, IamTransportError } from './rpc-http';
+export type { IamMembershipMethod } from './rpc-http';
+export { createIamMembership, IamMembership } from './membership';
+export type { IamMembershipEnv, MembershipRequestCaller } from './membership';
+export type { FetchLike, HttpIamRpcOptions } from './rpc-http';
+export { TokenVerifier } from './verify';
+export type { VerifyResult } from './verify';
+export { reconcileSchema, ReconcileSchemaError } from './provision';
+export { appSchemaSchema } from './app-schema';
+export type { ReconcileSchemaOptions } from './provision';
+export type { AuthContext, IamBinding, ListPrincipalsFailure, PrincipalIdentity, PrincipalList } from './types';
+export { PROXY_TOKEN_HEADER } from '@fabrika/auth-core';
+export type { AppActionDef, AppSchema, AppScopeDef, DomainEvent, IamMembershipRpc, IamRpc, LinkTokenClaims, MembershipFailure, OAuthTokenClaims, PrincipalListItem, RoleDef, Scope, TokenAudienceProfile, } from '@fabrika/auth-core';

package/types/src/membership.d.ts

@@ -0,0 +1,46 @@
+import type { AssignMemberResult, CreateScopeResult, FindMemberResult, IamMembershipRpc, InvitationOptions, IssueLinkResult, ListAppMembersResult, ListMembersResult, MemberTarget, RequestDelegationResult, RevokeLinkResult, RevokeMemberInput, RevokeMemberResult, Scope } from '@fabrika/auth-core';
+/**
+ * The caller a membership request is made for: the verified token the proxy injected on THIS request, and
+ * the request's correlation id. IAM resolves the caller from the token and checks its live permissions; a
+ * delegation grant is bound to the request id, so both calls of one request carry the same one.
+ */
+export interface MembershipRequestCaller {
+    readonly credential: string;
+    readonly requestId: string;
+}
+/** The env `createIamMembership` reads; an application's `env` satisfies it structurally. */
+export interface IamMembershipEnv {
+    /** IAM's application entrypoint on Cloudflare, or `HttpIamRpc` off it. */
+    IAM?: IamMembershipRpc;
+    FABRIKA_IAM_APP_ID?: string;
+}
+/**
+ * The SDK half of the membership operations. It REQUESTS, on the caller's behalf: IAM decides, generates
+ * every value, writes every grant and issues every key. Nothing here mints, signs or names an actor, and
+ * every result is IAM's answer as it came.
+ */
+export declare class IamMembership {
+    private readonly binding;
+    private readonly appId;
+    constructor(binding: IamMembershipRpc, appId: string);
+    /** A single-use grant for one request to `endpoint`, which the app's schema lists as a membership endpoint. */
+    requestDelegation(caller: MembershipRequestCaller, endpoint: string): Promise<RequestDelegationResult>;
+    /** A new value of `dimension`, with the caller granted the dimension's creator role in it. */
+    createScope(caller: MembershipRequestCaller, delegation: string, dimension: string): Promise<CreateScopeResult>;
+    /** `invitation` goes with an address only: its label, message and resend (`InvitationOptions`). */
+    assignMember(caller: MembershipRequestCaller, delegation: string, scope: Scope, role: string, member: MemberTarget, invitation?: InvitationOptions): Promise<AssignMemberResult>;
+    revokeMember(caller: MembershipRequestCaller, delegation: string, scope: Scope, member: RevokeMemberInput['member']): Promise<RevokeMemberResult>;
+    listMembers(caller: MembershipRequestCaller, scope: Scope): Promise<ListMembersResult>;
+    /** One page of the application's own people; `after` is the previous page's `next`. */
+    listAppMembers(caller: MembershipRequestCaller, after?: string): Promise<ListAppMembersResult>;
+    /** One principal among the members of `scope`, for an endpoint of `action` on, in or below its dimension. */
+    findMember(caller: MembershipRequestCaller, scope: Scope, principalId: string, action: string): Promise<FindMemberResult>;
+    /** A share link of `mount` for `chain[0]`; `chain` is the object and every value containing it, outward. */
+    issueLink(caller: MembershipRequestCaller, mount: string, chain: Scope[], days: number): Promise<IssueLinkResult>;
+    revokeLink(caller: MembershipRequestCaller, id: string): Promise<RevokeLinkResult>;
+    private caller;
+}
+/** Build the membership client from the env. Throws when the app id or the binding is missing. */
+export declare function createIamMembership(env: IamMembershipEnv, opts?: {
+    appId?: string;
+}): IamMembership;

package/types/src/provision.d.ts

@@ -0,0 +1,37 @@
+import type { AppSchema } from '@fabrika/auth-core';
+export interface ReconcileSchemaOptions {
+    /** The IAM Worker's admin origin, e.g. `https://iam.example.com` (trailing slash ok). */
+    url: string;
+    /** The app id; its FIRST reconcile registers it in IAM's app registry. */
+    app: string;
+    /** The app's declared vocabulary. */
+    schema: AppSchema;
+    /**
+     * Every origin IAM may hand this app a session at (ADR-0022), as known by the CONTROL PLANE.
+     *
+     * Omit to leave the registry alone; a supplied set REPLACES it, so it must be the complete set for
+     * the app and not just the environment being deployed. It is NEVER read off the `AppSchema`: an app
+     * that could name its own return origin could name any origin, which is the thing the registry
+     * exists to prevent. An empty array is a caller error: an app is never un-registered by having
+     * nothing to send.
+     */
+    returnOrigins?: readonly string[];
+    /**
+     * An IAM-issued `px_` ADMIN key, sent as `Authorization: Bearer`. Effectively required: IAM's
+     * `/admin/*` accepts only a bearer and refuses a credential-less call in every environment.
+     */
+    adminKey?: string;
+    /** Cancels the in-flight request when schema reconciliation belongs to a deploy lifecycle. */
+    signal?: AbortSignal;
+}
+/** Thrown when the admin endpoint rejects the reconcile; `status` is the HTTP status. */
+export declare class ReconcileSchemaError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Reconcile one app's declared `AppSchema` into IAM (idempotent), then — when `returnOrigins` is
+ * supplied — project that set into IAM's return-origin registry. Resolves on success; throws
+ * `ReconcileSchemaError` on a non-2xx response, or `Error` on a half-set service token.
+ */
+export declare function reconcileSchema(options: ReconcileSchemaOptions): Promise<void>;

package/types/src/request.d.ts

@@ -0,0 +1,10 @@
+export interface ForwardedCredentials {
+    /** The native credential (a `px_` key / `px_token`), or null when absent. */
+    credential: string | null;
+    /** cf-ray, or a fresh UUID when absent (e.g. local dev). */
+    requestId: string;
+}
+/** The correlation id for this request: cf-ray when the platform supplies one, else a fresh UUID. */
+export declare function readRequestId(req: Request): string;
+/** Pull the native credential and a correlation id off the request. `credential` may be null. */
+export declare function readCredentials(req: Request): ForwardedCredentials;

package/types/src/rpc-http.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `IamRpc` over HTTP — the transport an app needs when it has no Cloudflare service binding.
+ *
+ * WHAT THIS IS NOT: it is not a second IAM. `IamRpc` (@fabrika/auth-core) is unchanged and this class
+ * holds no policy — it POSTs the method's input as JSON, reads the result back, and hands it to the
+ * same callers (`Iam`, `IamClient`) the binding serves. Everything downstream of the
+ * contract — local token verification, `can()`/`scopedTo()`, delegation checks inside the IAM
+ * service — is byte-for-byte the same code on both transports. The ONLY difference is how the
+ * call travels.
+ *
+ * THE WIRE IS `@fabrika/iam`'s `src/rpc-http.ts`, and that file is the contract:
+ *
+ *   POST {origin}/rpc/<method>   Authorization: Bearer <key>   body = the method's input
+ *     → 200 with the method's result (INCLUDING a decided `{ ok: false, reason }`)
+ *     → 204 for `audit` (it returns void over the binding, so there is nothing to encode)
+ *     → 401 bad/absent key · 404 no such method OR the surface is disabled (an unset key 404s) ·
+ *       400 undecodable body · 405 not a POST
+ *
+ * A DECIDED NEGATIVE IS A 200, and that distinction is the whole point: `{ ok: false, reason }` means
+ * "IAM answered: no", while a non-200 means "IAM could not be consulted". Only the second is an
+ * incident, and only the second throws here.
+ *
+ * ── Why a transport failure THROWS ────────────────────────────────────────────────────────────────
+ *
+ * Over a service binding an unreachable IAM is not a case a caller has to model: the binding either
+ * resolves or the whole invocation fails. Over HTTP it is a real state, and mapping it onto the
+ * contract's `reason` union would be a lie — `invalid_session` says "we checked, and no", which is not
+ * what happened. So it raises `IamTransportError`, callers see a 5xx, and nothing is ever admitted on
+ * the strength of an answer that never arrived. This is the same split `@fabrika/proxy`'s
+ * `HttpIamGateway` makes with `IamUnavailableError`.
+ *
+ * ── One instance per process, deliberately ────────────────────────────────────────────────────────
+ *
+ * The SDK caches the fetched JWKS and the tokens minted from `px_` share credentials in `WeakMap`s
+ * keyed by THE BINDING OBJECT. A fresh `HttpIamRpc` per request would therefore miss both caches every
+ * time and re-fetch the JWKS on every request. Build one for the process's lifetime and put it in the
+ * env, the way a binding lives for the isolate's lifetime.
+ *
+ * The key is a TRANSPORT credential, never a caller identity: it says "this request came from inside
+ * the deployment", exactly as a binding's unreachability does. Per-caller authorization still happens
+ * inside IAM, from the credential carried in the method's own input. It is never logged.
+ */
+import type { ApproveDeviceAuthorizationInput, ApproveDeviceAuthorizationResult, AssignMemberInput, AssignMemberResult, AuditInput, CreateScopeInput, CreateScopeResult, DenyDeviceAuthorizationResult, FindMemberInput, FindMemberResult, IamMembershipRpc, IamRpc, InspectDeviceAuthorizationInput, InspectDeviceAuthorizationResult, IssueKeyInput, IssueKeyResult, IssueLinkInput, IssueLinkResult, Jwks, ListAppMembersInput, ListAppMembersResult, ListMembersInput, ListMembersResult, ListOwnDeviceAuthorizationsInput, ListOwnDeviceAuthorizationsResult, ListPrincipalsInput, ListPrincipalsResult, MintFromKeyInput, MintFromKeyResult, MintTokenInput, MintTokenResult, RequestDelegationInput, RequestDelegationResult, RevokeKeyInput, RevokeKeyResult, RevokeLinkInput, RevokeLinkResult, RevokeMemberInput, RevokeMemberResult } from '@fabrika/auth-core';
+/**
+ * Just the call shape this client uses. Narrower than `typeof fetch` on purpose: the global carries
+ * runtime-specific extras (Bun's `preconnect`) that a test double has no business implementing.
+ */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export interface HttpIamRpcOptions {
+    /** The IAM service origin, e.g. `http://iam:3000` on a private network (trailing slash tolerated). */
+    origin: string;
+    /**
+     * The bearer: the installation's shared secret gating `/rpc/*` for `HttpIamRpc`, or an application's own
+     * membership transport key for `HttpIamMembership` (`FABRIKA_IAM_RPC_KEY` in each). NEVER logged.
+     */
+    key: string;
+    /** Per-call timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Injectable for tests; defaults to the global `fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * IAM could not be consulted — network failure, timeout, a non-2xx status, or a body that does not
+ * match the contract. Distinct from a decided denial, which is a normal result.
+ *
+ * Carries NO cause and no response body: a `fetch` error stringifies the request URL, and a body can
+ * quote a credential that was on the way in.
+ */
+export declare class IamTransportError extends Error {
+    readonly method: string;
+    constructor(method: string);
+}
+export declare class HttpIamRpc implements IamRpc, IamMembershipRpc {
+    #private;
+    inspectDeviceAuthorization(input: InspectDeviceAuthorizationInput): Promise<InspectDeviceAuthorizationResult>;
+    approveDeviceAuthorization(input: ApproveDeviceAuthorizationInput): Promise<ApproveDeviceAuthorizationResult>;
+    denyDeviceAuthorization(input: InspectDeviceAuthorizationInput): Promise<DenyDeviceAuthorizationResult>;
+    listOwnDeviceAuthorizations(input: ListOwnDeviceAuthorizationsInput): Promise<ListOwnDeviceAuthorizationsResult>;
+    private readonly endpoint;
+    constructor(options: HttpIamRpcOptions);
+    mintToken(input: MintTokenInput): Promise<MintTokenResult>;
+    mintFromKey(input: MintFromKeyInput): Promise<MintFromKeyResult>;
+    issueKey(input: IssueKeyInput): Promise<IssueKeyResult>;
+    revokeKey(input: RevokeKeyInput): Promise<RevokeKeyResult>;
+    listPrincipals(input: ListPrincipalsInput): Promise<ListPrincipalsResult>;
+    requestDelegation(input: RequestDelegationInput): Promise<RequestDelegationResult>;
+    createScope(input: CreateScopeInput): Promise<CreateScopeResult>;
+    assignMember(input: AssignMemberInput): Promise<AssignMemberResult>;
+    revokeMember(input: RevokeMemberInput): Promise<RevokeMemberResult>;
+    listMembers(input: ListMembersInput): Promise<ListMembersResult>;
+    listAppMembers(input: ListAppMembersInput): Promise<ListAppMembersResult>;
+    findMember(input: FindMemberInput): Promise<FindMemberResult>;
+    issueLink(input: IssueLinkInput): Promise<IssueLinkResult>;
+    revokeLink(input: RevokeLinkInput): Promise<RevokeLinkResult>;
+    getJwks(): Promise<Jwks>;
+    audit(event: AuditInput): Promise<void>;
+    private call;
+    private send;
+}
+/** The membership operations, by name, as a transport carries them. */
+export type IamMembershipMethod = keyof IamMembershipRpc;
+/**
+ * `IamMembershipRpc` over any transport that answers each call with a JSON-shaped body: `HttpIamRpc`, or a Workers
+ * binding to IAM's application entrypoint. Every answer is decoded here, so a body that breaks the contract is
+ * `IamTransportError`, never a value of the declared type.
+ */
+export declare class DecodedIamMembership implements IamMembershipRpc {
+    #private;
+    constructor(call: (method: IamMembershipMethod, input: unknown) => Promise<unknown>);
+    requestDelegation(input: RequestDelegationInput): Promise<RequestDelegationResult>;
+    createScope(input: CreateScopeInput): Promise<CreateScopeResult>;
+    assignMember(input: AssignMemberInput): Promise<AssignMemberResult>;
+    revokeMember(input: RevokeMemberInput): Promise<RevokeMemberResult>;
+    listMembers(input: ListMembersInput): Promise<ListMembersResult>;
+    listAppMembers(input: ListAppMembersInput): Promise<ListAppMembersResult>;
+    findMember(input: FindMemberInput): Promise<FindMemberResult>;
+    issueLink(input: IssueLinkInput): Promise<IssueLinkResult>;
+    revokeLink(input: RevokeLinkInput): Promise<RevokeLinkResult>;
+}
+/**
+ * `IamMembershipRpc` over IAM's membership transport, `POST {origin}/membership/<method>` (`@fabrika/iam`'s
+ * `src/membership-http.ts`): what an application without an IAM binding calls, with its own membership transport key.
+ * IAM serves no `requestDelegation` there, because only the proxy obtains a grant; calling it is `IamTransportError`.
+ */
+export declare class HttpIamMembership extends DecodedIamMembership {
+    constructor(options: HttpIamRpcOptions);
+}

package/types/src/scope.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Resolve the three-state result from `scopedTo(action, dimension)` into a single value the
+ * app controls. This is the SINGLE place the empty-`IN ()` SQL trap is handled: `none`
+ * short-circuits without ever emitting `WHERE col IN ()`.
+ *
+ *   - `null`      → `all()`           — unrestricted (admin / global grant): no filter
+ *   - `[]`        → `none()`          — no access: empty result, DO NOT query
+ *   - non-empty   → `some(values)`    — filter to these scope values (`WHERE col IN (...)`)
+ *
+ * The `values` are the opaque, app-owned scope values for that dimension (the app keys its
+ * rows by them). The app supplies what all/some/none mean for its own query; filtering must
+ * happen at the data layer, never by loading everything and filtering in memory.
+ */
+export declare function applyScope<T>(scope: string[] | null, branches: {
+    all: () => T;
+    some: (values: string[]) => T;
+    none: () => T;
+}): T;

package/types/src/types.d.ts

@@ -0,0 +1,78 @@
+import type { DomainEvent, IamRpc, LinkTokenClaims, OAuthTokenClaims, PrincipalListItem, PrincipalType, Scope } from '@fabrika/auth-core';
+/**
+ * The `IamRpc` members the SDK calls. A Cloudflare application's `IAM` binding is IAM's
+ * `PropustkaApplication` entrypoint, which serves these and has no `issueKey` or `revokeKey`.
+ */
+export type IamBinding = Pick<IamRpc, 'getJwks' | 'listPrincipals' | 'audit'>;
+/**
+ * The resolved caller's identity — who Access says you are, as the IAM Worker recorded
+ * the principal. Exposed on `AuthContext` so apps can stamp domain rows (created_by,
+ * activity actor, assignee) and render "signed in as …" without a second lookup. It is
+ * NOT a permission surface — authorization is still `can()` / `scopedTo()`.
+ *  - `id`    — the IAM principal id (UUIDv7); stable, safe to store on domain rows.
+ *  - `type`  — 'user' (a human identity) or 'service' (a machine principal / API key).
+ *  - `label` — human-readable: the user's email, or the service principal's name.
+ */
+export interface PrincipalIdentity {
+    readonly id: string;
+    readonly type: PrincipalType;
+    readonly label: string;
+}
+/**
+ * The authenticated, ok:true result. `can`/`scopedTo` are local & pure (no binding call);
+ * only `audit` reaches the IAM Worker.
+ */
+export interface AuthContext {
+    readonly ok: true;
+    /**
+     * The resolved caller identity (id / type / label), or `null` for an ANONYMOUS credential — a
+     * standalone (no-principal) share link. For stamping domain rows and
+     * display — NOT a permission surface (authorization stays `can` / `scopedTo`, which work the same
+     * either way). Stamp `created_by` with `principal?.id ?? null`.
+     */
+    readonly principal: PrincipalIdentity | null;
+    /**
+     * The OAuth client, consented scopes and grant behind an OAuth resource token; absent for every
+     * native credential. `perms` are already narrowed by the scopes, so `can()` stays the authority.
+     */
+    readonly oauth?: OAuthTokenClaims;
+    /**
+     * The share link behind a link key's token — its mount and the containment chain it is bound to —
+     * absent for every other credential. `principal` is then null.
+     */
+    readonly link?: LinkTokenClaims;
+    /**
+     * Point check: may this principal do `action` (optionally within `scope`, an opaque
+     * `{ type, value }` coordinate)? Scope-less → satisfied by GLOBAL permissions only; a
+     * scoped grant never widens into a scope-less allow.
+     */
+    can(action: string, scope?: Scope): boolean;
+    /**
+     * Scoping: which scope values may this principal perform `action` on within `dimension`
+     * (a scope type, e.g. `'organization'`)? Scopes are flat & independent — a list is always
+     * relative to one dimension.
+     *  - `null`      → unrestricted (holds the action globally — e.g. an admin)
+     *  - `[]`        → no access within this dimension at all
+     *  - non-empty   → exactly those (opaque, app-owned) scope values
+     * Consume via `applyScope` so the empty-`IN ()` trap is handled once. `dimension` is
+     * REQUIRED — multiple scope types may coexist, so the caller must say which one.
+     */
+    scopedTo(action: string, dimension: string): string[] | null;
+    /** Emit a domain audit event; app/principal/requestId are auto-attached. Fire-and-forget. */
+    audit(event: DomainEvent): Promise<void>;
+}
+/** Successful `listPrincipals` — the app's people directory (user principals). */
+export interface PrincipalList {
+    readonly ok: true;
+    principals: PrincipalListItem[];
+}
+/** `listPrincipals` failure. missing/invalid → 401; unknown_principal/disabled/not_allowed → 403. */
+export interface ListPrincipalsFailure {
+    readonly ok: false;
+    reason: 'missing_token' | 'invalid_token' | 'unknown_principal' | 'disabled' | 'not_allowed';
+    status: 401 | 403;
+}
+/** A request context with a writable `auth` slot, set to the resolved `AuthContext` (or null for an anonymous caller). */
+export interface AuthCarrier {
+    auth?: AuthContext | null;
+}

package/types/src/verify.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Local access-token verification — the only thing this SDK still does with a credential.
+ *
+ * Since [ADR-0022](../../../docs/decisions/0022-the-proxy-is-the-only-enforcement-point.md) the PROXY is the only
+ * enforcement point: it selects the endpoint, resolves the credential, and injects the verified
+ * token as `PROXY_TOKEN_HEADER`. The app must NOT trust that header blindly, so every token is
+ * re-verified here against IAM's published JWKS — signature, `iss`, `aud`, `exp` — before it can
+ * become an `AuthContext`.
+ *
+ * The verification itself is `@fabrika/jwks`, shared byte-for-byte with the proxy's enforcement path.
+ * What this file owns is the SDK's construction shape: the audience is fixed at construction, and the
+ * key set plus the unknown-`kid` cooldown are cached PER BINDING in a module-level WeakMap rather than
+ * per instance — a service may build one on every request, so an SDK object
+ * built there is per-request while the binding lives for the isolate/process.
+ */
+import type { TokenAudienceProfile } from '@fabrika/auth-core';
+import { type VerifyResult } from '@fabrika/jwks';
+import type { IamBinding } from './types';
+export type { VerifyResult };
+/**
+ * Verifies tokens for ONE (binding, issuer, audience) triple. A bare string audience is an app id. Cheap to
+ * construct; the cache is shared.
+ */
+export declare class TokenVerifier {
+    private readonly audience;
+    private readonly inner;
+    constructor(binding: IamBinding, issuer: string, audience: string | TokenAudienceProfile, now?: () => number);
+    verify(token: string, audience?: string | TokenAudienceProfile): Promise<VerifyResult>;
+}