@fabrika/auth 0.8.2 → 0.9.0-cloudflare.1

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

@@ -0,0 +1,628 @@
+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;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        in?: string | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }, {
+        type: string;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        in?: string | 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[];
+        external?: true | undefined;
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        description?: string | undefined;
+    }, {
+        name: string;
+        permissions: string[];
+        external?: true | undefined;
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | 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: "members" | "creates";
+    }, {
+        action: string;
+        dimension: string;
+        purpose: "members" | "creates";
+    }>>>;
+    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">>;
+    terminal: z.ZodOptional<z.ZodObject<{
+        identify: z.ZodEffects<z.ZodString, string, string>;
+    }, "strict", z.ZodTypeAny, {
+        identify: string;
+    }, {
+        identify: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    actions: {
+        action: string;
+        description?: string | undefined;
+    }[];
+    roles: Record<string, {
+        name: string;
+        permissions: string[];
+        external?: true | undefined;
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    scopes: {
+        type: string;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        in?: string | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }[];
+    displayName?: string | undefined;
+    terminal?: {
+        identify: string;
+    } | undefined;
+    members?: {
+        manage: string;
+        list: 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;
+    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: "members" | "creates";
+    }> | 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[];
+        external?: true | undefined;
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    scopes: {
+        type: string;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        in?: string | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }[];
+    displayName?: string | undefined;
+    terminal?: {
+        identify: string;
+    } | undefined;
+    members?: {
+        manage: string;
+        list: 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;
+    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: "members" | "creates";
+    }> | 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[];
+        external?: true | undefined;
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    scopes: {
+        type: string;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        in?: string | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }[];
+    displayName?: string | undefined;
+    terminal?: {
+        identify: string;
+    } | undefined;
+    members?: {
+        manage: string;
+        list: 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;
+    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: "members" | "creates";
+    }> | 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[];
+        external?: true | undefined;
+        member?: {
+            scope: string;
+            assignableBy?: string[] | undefined;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    scopes: {
+        type: string;
+        members?: {
+            manage: string;
+            list: string;
+        } | undefined;
+        directory?: "labels" | undefined;
+        in?: string | undefined;
+        label?: string | undefined;
+        creator?: string | undefined;
+        lookups?: string[] | undefined;
+    }[];
+    displayName?: string | undefined;
+    terminal?: {
+        identify: string;
+    } | undefined;
+    members?: {
+        manage: string;
+        list: 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;
+    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: "members" | "creates";
+    }> | 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;