@c1m-public/platform-auth 0.2.0 → 0.4.0

package/README.md

@@ -1,28 +1,105 @@
 # @c1m-public/platform-auth
 
-Framework-neutral session helpers for C1M platform surfaces (Platform Admin
-Center, Knowledge Library, SaaSDash BFFs):
-
-- `token` — decode access-token payloads (audience, expiry, default session).
-  Decoding is routing, not verification; the backend stays the boundary.
-- `safeInternalPath` — strict same-origin return-path sanitiser.
-- `forwardedRequestHeaders` — copy the browser's client identity onto a
-  backend call (`X-Client-*` / `X-Forwarded-*`).
-- `createDeviceIdentity` — the `X-Client-Device-ID` cookie the backend needs to
-  create a session.
-- `createHandoffTarget` / `createHandoffSource` — the browser halves of the
-  first-party session handoff (`/api/v1/platform/auth/handoffs/{app}`):
-  PKCE S256 + state, one-time code, host-local cookies, no tokens in URLs.
-- `HANDOFF_ERROR_MESSAGES` — the one error vocabulary for handoff failures.
-
-Import from `@c1m-public/platform-auth/next` inside Next.js server code.
+Server-side **session** and **authorization** helpers for C1M platform surfaces
+(Platform Admin Center, Knowledge Library, SaaSDash BFFs, and starter BFFs).
+
+Two halves, one package. The root and `./next` entry points carry session
+protocol behaviour and stay framework-neutral; everything under `./access`
+carries the resolved authorization snapshot. Import only the entry point you
+need — the boundary is the subpath.
+
+```
+.               session: token reads, handoff, proxy gate, refresh   (Web Request/Response)
+./next          session, server-only guard                            (Next route handlers)
+./access        authorization: snapshot, keys, predicates             (framework-neutral)
+./access/next   access loader: require / forbidden / invalidate       (Next, server-only)
+./access/react  <Can>, useCan, AccessProvider                         (client)
+```
+
+`next` and `react` are **optional** peer dependencies: a BFF that only reads
+sessions never needs them.
+
+## `.` — session
+
+| Export | Purpose |
+|---|---|
+| `decodeTokenPayload`, `decodeDefaultSession`, `hasTokenAudience`, `isTokenExpired`, `isTokenExpiringSoon`, `tokenMaxAgeSeconds` | Read an access token for routing. Decoding is **not** verification — the backend re-verifies every call. `decodeDefaultSession` prefers `effective_user_id`, so a support session resolves as the impersonated user. |
+| `parseAuthResponse`, `AuthResponse` | Validate a backend auth envelope before trusting it. |
+| `readCookie`, `serializeCookie`, `setCookie`, `deleteCookie` | Cookie helpers over Web `Request`/`Response`. `__Host-` names get `Secure` automatically. |
+| `createDeviceIdentity` | The `X-Client-Device-ID` cookie the backend requires to create a session. |
+| `applyForwardedClientHeaders`, `forwardedRequestHeaders` | Copy client identity (IP, geo, UA) onto a backend call. Never used for auth. |
+| `safeInternalPath` | Strict same-origin return-path sanitiser (rejects `//`, `://`, encoded slashes, control chars, anything that does not round-trip). |
+| `createSessionRefresher` | Coalesced refresh-token exchange: one backend call per token per window. |
+| `evaluateSessionGate`, `hasSessionShape` | Pure proxy decision — `pass` / `redirect_home` / `anonymous_public` / `unauthorized_api` / `redirect_login`. The proxy owns response construction. |
+| `createHandoffTarget`, `createHandoffSource`, `brokerPaths`, `sourceStartPath` | Browser halves of the first-party session handoff (`/api/v1/platform/auth/handoffs/{app}`): PKCE S256 + state, one-time code, host-local cookies, no tokens in URLs. |
+| `HANDOFF_ERROR_MESSAGES`, `handoffErrorMessage`, `isHandoffErrorCode` | One error vocabulary shared by backend and BFF codes. |
 
 ```ts
-// target: app/api/auth/platform-sso/[action]/route.ts
-const target = createHandoffTarget({ app: "docs", apiUrl: API_URL, audience: "platform_docs", ... });
-export const GET = (req: Request, ctx) => ctx.params.action === "callback" ? target.callback(req) : target.start(req);
+// proxy.ts
+const refresher = createSessionRefresher({ apiUrl: API_URL, refreshPath, clientType, audience });
+const decision = await evaluateSessionGate({
+  accessToken: request.cookies.get(SESSION)?.value,
+  refreshToken: request.cookies.get(REFRESH)?.value,
+  audience, refresher,
+  isPublic, isLoginPath, isApiPath: pathname.startsWith("/api/"),
+});
+```
+
+```ts
+// target: app/api/auth/platform-sso/{start,callback}
+const target = createHandoffTarget({ app: "docs", apiUrl, audience: "platform_docs", clientType,
+  sources: { admin: ADMIN_URL, saasdash: SAASDASH_URL }, defaultSource: "admin",
+  cookiePrefix: "docs", loginPath: "/login", defaultReturnPath: "/docs", device, establishSession });
+
+// source: app/api/auth/handoffs/[app]/start
+const source = createHandoffSource({ apiUrl, clientType, targets: { docs: { origin: DOCS_URL } },
+  getAccessToken, loginPath: "/login" });
+```
+
+## `./access` — authorization
+
+The resolved snapshot from `GET /api/v1/platform/access`.
 
-// source: app/api/auth/handoffs/[app]/start/route.ts
-const source = createHandoffSource({ apiUrl: API_URL, clientType: "nextjs-platform-admin", targets: { docs: { origin: DOCS_URL } }, getAccessToken, loginPath: "/login" });
-export const GET = (req: Request, ctx) => source.start(req, ctx.params.app);
+| Export | Purpose |
+|---|---|
+| `PLATFORM_PERMISSIONS`, `LEADBROKER_PERMISSIONS`, `WORKSPACE_PERMISSIONS`, `WORKSPACE_ROLES` + key types | Generated from the backend catalog — see the drift guard below. |
+| `parseAccessSnapshot`, `emptySnapshot`, `AccessSnapshot`, `AccessEntry` | Validate and shape the snapshot. |
+| `hasPermission`, `hasAnyPermission`, `hasAllPermissions`, `hasWorkspacePermission`, `isPlatformOwner`, `appScopes`, `permissionsFor` | Scope-aware predicates. |
+| `fetchAccessSnapshot` | Framework-neutral fetch. Pass `request` and it forwards client identity for you. |
+| `AccessSnapshotError`, `isAccessSnapshotError` | `unauthenticated` / `forbidden` / `unavailable` / `invalid_snapshot`. |
+
+`./access/next` adds `createAccessLoader` (request-scoped via React `cache`),
+`requireAccess`, `requireWorkspaceAccess`, `invalidateAccess`, `accessCacheTag`.
+`./access/react` adds `AccessProvider`, `useCan`, `useCanWorkspace`,
+`useIsPlatformOwner`, `<Can>`.
+
+```ts
+// lib/access.server.ts
+export const access = createAccessLoader({
+  apiUrl: getApiUrl,
+  getAccessToken: async () => (await cookies()).get(SESSION)?.value ?? null,
+  // Cross-request caching is the APP's job: the "use cache" directive does not
+  // apply inside node_modules, so wrap the fetch here and tag it yourself.
+  fetchSnapshot: cachedSnapshot,
+});
+await access.requireAccess("platform.tenants.manage");
 ```
+
+Omit `getSubjectId` and the loader derives the cache-tag subject from the access
+token, so per-user tagging cannot silently collapse to one shared tag.
+
+## Keys drift guard
+
+`src/access/generated/keys.ts` is generated from the backend authz catalog
+(`c1m-server/schemas/api/authz-keys.json`, produced by `make authzgen`) and
+vendored to `contracts/authz-keys.json`. Never hand-edit it. Regenerate with
+`node scripts/generate-access-types.mjs`; `pnpm contract:check` runs
+`--check` and fails on drift, so a backend rename cannot silently diverge from
+the frontend key unions.
+
+## Notes
+
+- Import from `@c1m-public/platform-auth/next` (or `/access/next`) inside
+  Next.js server code — those entries carry the `server-only` guard.
+- Session cookies stay host-local per surface; this package never shares a
+  session across origins. Crossing hosts is always a fresh handoff.

package/dist/access/errors.d.ts

@@ -0,0 +1,13 @@
+export type AccessErrorCode = "unauthenticated" | "forbidden" | "unavailable" | "invalid_snapshot";
+/**
+ * Typed failure for loading or validating an access snapshot. `unauthenticated`
+ * = no/expired session (401); `forbidden` = the backend refused the snapshot
+ * (403; e.g. wrong audience); `unavailable` = transport/5xx; `invalid_snapshot`
+ * = the payload did not match the contract.
+ */
+export declare class AccessSnapshotError extends Error {
+    readonly code: AccessErrorCode;
+    readonly status: number | undefined;
+    constructor(code: AccessErrorCode, message: string, status?: number);
+}
+export declare function isAccessSnapshotError(error: unknown, code?: AccessErrorCode): error is AccessSnapshotError;

package/dist/access/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Typed failure for loading or validating an access snapshot. `unauthenticated`
+ * = no/expired session (401); `forbidden` = the backend refused the snapshot
+ * (403; e.g. wrong audience); `unavailable` = transport/5xx; `invalid_snapshot`
+ * = the payload did not match the contract.
+ */
+export class AccessSnapshotError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = "AccessSnapshotError";
+        this.code = code;
+        this.status = status;
+    }
+}
+export function isAccessSnapshotError(error, code) {
+    return error instanceof AccessSnapshotError && (code === undefined || error.code === code);
+}

package/dist/access/fetch.d.ts

@@ -0,0 +1,23 @@
+import { type Resolvable } from "../internal.js";
+import { type AccessSnapshot } from "./snapshot.js";
+export declare const DEFAULT_ACCESS_ENDPOINT_PATH = "/api/v1/platform/access";
+export interface FetchAccessSnapshotOptions {
+    /** Backend origin, e.g. https://api.example.com (no trailing slash needed). */
+    apiUrl: Resolvable;
+    /** Bearer access token for the platform surface. */
+    accessToken: string;
+    /** Defaults to /api/v1/platform/access. */
+    endpointPath?: string;
+    fetchTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Extra headers. Authorization and Accept are always set here. */
+    headers?: HeadersInit;
+    /** Incoming BFF request; its client identity (IP, geo, UA) is forwarded to the backend. */
+    request?: Request;
+}
+/**
+ * Framework-neutral fetch of the resolved access snapshot. Throws
+ * AccessSnapshotError: 401 → unauthenticated, 403 → forbidden, other non-2xx or
+ * network failure → unavailable, malformed body → invalid_snapshot.
+ */
+export declare function fetchAccessSnapshot(opts: FetchAccessSnapshotOptions): Promise<AccessSnapshot>;

package/dist/access/fetch.js

@@ -0,0 +1,43 @@
+import { forwardedRequestHeaders } from "../forwarding.js";
+import { resolveValue, timedFetch } from "../internal.js";
+import { AccessSnapshotError } from "./errors.js";
+import { parseAccessSnapshot } from "./snapshot.js";
+export const DEFAULT_ACCESS_ENDPOINT_PATH = "/api/v1/platform/access";
+/**
+ * Framework-neutral fetch of the resolved access snapshot. Throws
+ * AccessSnapshotError: 401 → unauthenticated, 403 → forbidden, other non-2xx or
+ * network failure → unavailable, malformed body → invalid_snapshot.
+ */
+export async function fetchAccessSnapshot(opts) {
+    const url = `${resolveValue(opts.apiUrl).replace(/\/$/, "")}${opts.endpointPath ?? DEFAULT_ACCESS_ENDPOINT_PATH}`;
+    const headers = opts.request
+        ? forwardedRequestHeaders(opts.request, opts.headers)
+        : new Headers(opts.headers);
+    headers.set("Authorization", `Bearer ${opts.accessToken}`);
+    headers.set("Accept", "application/json");
+    let response;
+    try {
+        response = await timedFetch(url, {
+            init: { method: "GET", headers },
+            timeoutMs: opts.fetchTimeoutMs,
+            fetchImpl: opts.fetchImpl,
+        });
+    }
+    catch (error) {
+        throw new AccessSnapshotError("unavailable", `access snapshot request failed: ${error.message}`);
+    }
+    if (response.status === 401)
+        throw new AccessSnapshotError("unauthenticated", "session expired", 401);
+    if (response.status === 403)
+        throw new AccessSnapshotError("forbidden", "access snapshot refused", 403);
+    if (!response.ok)
+        throw new AccessSnapshotError("unavailable", `access snapshot returned ${response.status}`, response.status);
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        throw new AccessSnapshotError("invalid_snapshot", "access snapshot body is not JSON", response.status);
+    }
+    return parseAccessSnapshot(body);
+}

package/dist/access/generated/keys.d.ts

@@ -0,0 +1,14 @@
+/** Platform-operator permission keys. */
+export declare const PLATFORM_PERMISSIONS: readonly ["platform.admin.view", "platform.audit.view", "platform.auth.manage", "platform.billing.manage", "platform.channels.manage", "platform.channels.view", "platform.config.manage", "platform.docs.manage", "platform.docs.view", "platform.observability.manage", "platform.observability.view", "platform.ops.manage", "platform.support.impersonate", "platform.support.sessions", "platform.tenants.archive", "platform.tenants.manage", "platform.tenants.restore", "platform.users.deactivate", "platform.users.delete", "platform.users.invite", "platform.users.manage_access", "platform.users.reactivate", "platform.users.view"];
+export type PlatformPermissionKey = (typeof PLATFORM_PERMISSIONS)[number];
+/** Lead-broker workload permission keys. */
+export declare const LEADBROKER_PERMISSIONS: readonly ["leadbroker.finance.manage", "leadbroker.leads.dispatch", "leadbroker.leads.review", "leadbroker.leads.view", "leadbroker.policy.manage"];
+export type LeadBrokerPermissionKey = (typeof LEADBROKER_PERMISSIONS)[number];
+/** Workspace-staff permission keys. */
+export declare const WORKSPACE_PERMISSIONS: readonly ["workspace.channels.manage", "workspace.channels.secrets", "workspace.channels.view", "workspace.crm.manage", "workspace.crm.view", "workspace.customers.manage", "workspace.customers.view", "workspace.orders.manage", "workspace.orders.view", "workspace.payments.record", "workspace.site.edit", "workspace.site.view", "workspace.staff.manage"];
+export type WorkspacePermissionKey = (typeof WORKSPACE_PERMISSIONS)[number];
+/** Assignable workspace-staff role bundles (grant keys at workspace scope). */
+export declare const WORKSPACE_ROLES: readonly ["workspace.editor", "workspace.frontdesk", "workspace.manager"];
+export type WorkspaceRole = (typeof WORKSPACE_ROLES)[number];
+/** Every permission key the backend can grant, across all scopes. */
+export type PermissionKey = PlatformPermissionKey | LeadBrokerPermissionKey | WorkspacePermissionKey;

package/dist/access/generated/keys.js

@@ -0,0 +1,58 @@
+// GENERATED by `node scripts/generate-access-types.mjs` from contracts/authz-keys.json
+// (vendored from c1m-server/schemas/api/authz-keys.json). Do not edit by hand.
+/** Platform-operator permission keys. */
+export const PLATFORM_PERMISSIONS = [
+    "platform.admin.view",
+    "platform.audit.view",
+    "platform.auth.manage",
+    "platform.billing.manage",
+    "platform.channels.manage",
+    "platform.channels.view",
+    "platform.config.manage",
+    "platform.docs.manage",
+    "platform.docs.view",
+    "platform.observability.manage",
+    "platform.observability.view",
+    "platform.ops.manage",
+    "platform.support.impersonate",
+    "platform.support.sessions",
+    "platform.tenants.archive",
+    "platform.tenants.manage",
+    "platform.tenants.restore",
+    "platform.users.deactivate",
+    "platform.users.delete",
+    "platform.users.invite",
+    "platform.users.manage_access",
+    "platform.users.reactivate",
+    "platform.users.view",
+];
+/** Lead-broker workload permission keys. */
+export const LEADBROKER_PERMISSIONS = [
+    "leadbroker.finance.manage",
+    "leadbroker.leads.dispatch",
+    "leadbroker.leads.review",
+    "leadbroker.leads.view",
+    "leadbroker.policy.manage",
+];
+/** Workspace-staff permission keys. */
+export const WORKSPACE_PERMISSIONS = [
+    "workspace.channels.manage",
+    "workspace.channels.secrets",
+    "workspace.channels.view",
+    "workspace.crm.manage",
+    "workspace.crm.view",
+    "workspace.customers.manage",
+    "workspace.customers.view",
+    "workspace.orders.manage",
+    "workspace.orders.view",
+    "workspace.payments.record",
+    "workspace.site.edit",
+    "workspace.site.view",
+    "workspace.staff.manage",
+];
+/** Assignable workspace-staff role bundles (grant keys at workspace scope). */
+export const WORKSPACE_ROLES = [
+    "workspace.editor",
+    "workspace.frontdesk",
+    "workspace.manager",
+];

package/dist/access/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./generated/keys.js";
+export * from "./errors.js";
+export * from "./snapshot.js";
+export * from "./predicates.js";
+export * from "./fetch.js";

package/dist/access/index.js

@@ -0,0 +1,5 @@
+export * from "./generated/keys.js";
+export * from "./errors.js";
+export * from "./snapshot.js";
+export * from "./predicates.js";
+export * from "./fetch.js";

package/dist/access/next.d.ts

@@ -0,0 +1,51 @@
+import "server-only";
+import { type Resolvable } from "../internal.js";
+import { type PermissionCheckOptions } from "./predicates.js";
+import type { AccessSnapshot } from "./snapshot.js";
+export * from "./index.js";
+/** Default cache tag for one subject's snapshot: `access:<subjectId>`. */
+export declare function accessCacheTag(subjectId: string): string;
+export interface CreateAccessLoaderOptions {
+    apiUrl: Resolvable;
+    endpointPath?: string;
+    /** Resolve the current request's bearer token (usually from the httpOnly session cookie). null = no session. */
+    getAccessToken: () => Promise<string | null>;
+    /**
+     * Subject id for the cache tag when `fetchSnapshot` is supplied. Defaults to
+     * decoding the access token, so a consumer that forgets this still tags
+     * per-subject rather than sharing one tag across users.
+     */
+    getSubjectId?: () => Promise<string | null>;
+    fetchTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    headers?: () => Promise<HeadersInit | undefined> | HeadersInit | undefined;
+    /**
+     * Optional cross-request cache seam. When provided, the loader calls this
+     * instead of fetching directly; the consumer wraps `fetchAccessSnapshot` in
+     * a `"use cache: private"` function (see README "Pilot recipe") tagged with
+     * `accessCacheTag(subjectId)`. When omitted, the snapshot is deduped per
+     * request only (React `cache`).
+     */
+    fetchSnapshot?: (args: {
+        accessToken: string;
+        subjectId: string | null;
+    }) => Promise<AccessSnapshot>;
+    cacheTag?: (subjectId: string) => string;
+}
+export interface RequireAccessOptions extends PermissionCheckOptions {
+    /** "all" (default) requires every key; "any" requires at least one. */
+    mode?: "all" | "any";
+}
+export interface AccessLoader {
+    /** Snapshot for the current request. Throws AccessSnapshotError (never interrupts). */
+    getAccess(): Promise<AccessSnapshot>;
+    /** Snapshot or null when unauthenticated. Other failures still throw. */
+    getAccessOrNull(): Promise<AccessSnapshot | null>;
+    /** unauthenticated → unauthorized(); missing permission → forbidden(). */
+    requireAccess(key: string | readonly string[], opts?: RequireAccessOptions): Promise<AccessSnapshot>;
+    requireWorkspaceAccess(workspaceId: string, key: string): Promise<AccessSnapshot>;
+    /** Bust the cross-request cache for one subject (updateTag). No-op without cacheComponents. */
+    invalidateAccess(subjectId: string): void;
+    cacheTag(subjectId: string): string;
+}
+export declare function createAccessLoader(options: CreateAccessLoaderOptions): AccessLoader;

package/dist/access/next.js

@@ -0,0 +1,86 @@
+// Server-only entry for Next.js. The root entry is framework-neutral; this one
+// adds the request-scoped loader (React cache), auth interrupts
+// (forbidden/unauthorized) and tag invalidation (updateTag).
+import "server-only";
+import { cache } from "react";
+import { forbidden, unauthorized } from "next/navigation";
+import { updateTag } from "next/cache";
+import { resolveValue } from "../internal.js";
+import { decodeTokenPayload } from "../token.js";
+import { AccessSnapshotError, isAccessSnapshotError } from "./errors.js";
+import { fetchAccessSnapshot } from "./fetch.js";
+import { hasAllPermissions, hasAnyPermission, hasWorkspacePermission } from "./predicates.js";
+export * from "./index.js";
+/** Default cache tag for one subject's snapshot: `access:<subjectId>`. */
+export function accessCacheTag(subjectId) {
+    return `access:${subjectId}`;
+}
+export function createAccessLoader(options) {
+    const tag = options.cacheTag ?? accessCacheTag;
+    const subjectIdOf = (accessToken) => {
+        const claims = decodeTokenPayload(accessToken);
+        const subject = claims?.actor_id ?? claims?.user_id ?? claims?.customer_id ?? claims?.sub;
+        return typeof subject === "string" && subject.length > 0 ? subject : null;
+    };
+    const load = cache(async () => {
+        const accessToken = await options.getAccessToken();
+        if (!accessToken)
+            throw new AccessSnapshotError("unauthenticated", "no session", 401);
+        if (options.fetchSnapshot) {
+            const subjectId = options.getSubjectId ? await options.getSubjectId() : subjectIdOf(accessToken);
+            return options.fetchSnapshot({ accessToken, subjectId });
+        }
+        const headers = typeof options.headers === "function" ? await options.headers() : options.headers;
+        return fetchAccessSnapshot({
+            apiUrl: resolveValue(options.apiUrl),
+            accessToken,
+            endpointPath: options.endpointPath,
+            fetchTimeoutMs: options.fetchTimeoutMs,
+            fetchImpl: options.fetchImpl,
+            headers,
+        });
+    });
+    async function getAccess() {
+        return load();
+    }
+    async function getAccessOrNull() {
+        try {
+            return await load();
+        }
+        catch (error) {
+            if (isAccessSnapshotError(error, "unauthenticated"))
+                return null;
+            throw error;
+        }
+    }
+    async function loadOrInterrupt() {
+        try {
+            return await load();
+        }
+        catch (error) {
+            if (isAccessSnapshotError(error, "unauthenticated"))
+                unauthorized();
+            if (isAccessSnapshotError(error, "forbidden"))
+                forbidden();
+            throw error;
+        }
+    }
+    async function requireAccess(key, opts = {}) {
+        const snapshot = await loadOrInterrupt();
+        const keys = typeof key === "string" ? [key] : key;
+        const ok = opts.mode === "any" ? hasAnyPermission(snapshot, keys, opts) : hasAllPermissions(snapshot, keys, opts);
+        if (!ok)
+            forbidden();
+        return snapshot;
+    }
+    async function requireWorkspaceAccess(workspaceId, key) {
+        const snapshot = await loadOrInterrupt();
+        if (!hasWorkspacePermission(snapshot, workspaceId, key))
+            forbidden();
+        return snapshot;
+    }
+    function invalidateAccess(subjectId) {
+        updateTag(tag(subjectId));
+    }
+    return { getAccess, getAccessOrNull, requireAccess, requireWorkspaceAccess, invalidateAccess, cacheTag: tag };
+}

package/dist/access/predicates.d.ts

@@ -0,0 +1,36 @@
+import type { AccessEntry, AccessSnapshot } from "./snapshot.js";
+export interface PermissionCheckOptions {
+    /**
+     * SaaS app (dash) slug the check is about. Omit for "anywhere": platform
+     * entries and any saas_app entry satisfy the check.
+     */
+    saasApp?: string;
+}
+/**
+ * Mirrors c1m-server authz.entryCoversApp: platform scope covers every app;
+ * saas_app scope covers "*" or a case-insensitive slug match; workspace-scoped
+ * entries never satisfy an app-level check.
+ */
+export declare function entryCoversApp(entry: AccessEntry, saasApp: string | undefined): boolean;
+/** True when the subject is active and holds `key` for the given app (or anywhere). */
+export declare function hasPermission(snapshot: AccessSnapshot, key: string, opts?: PermissionCheckOptions): boolean;
+export declare function hasAnyPermission(snapshot: AccessSnapshot, keys: readonly string[], opts?: PermissionCheckOptions): boolean;
+export declare function hasAllPermissions(snapshot: AccessSnapshot, keys: readonly string[], opts?: PermissionCheckOptions): boolean;
+/**
+ * Workspace-staff check. Platform owners always pass (they own every
+ * workspace); otherwise the workspace's effective permission list decides.
+ * Platform/saas_app entries never confer workspace-staff permissions.
+ */
+export declare function hasWorkspacePermission(snapshot: AccessSnapshot, workspaceId: string, key: string): boolean;
+export declare function isPlatformOwner(snapshot: AccessSnapshot): boolean;
+/**
+ * The saas_app scopes under which `key` is held. Returns `{ all: true }` when a
+ * platform-scoped or "*" entry grants it everywhere; otherwise the explicit
+ * app slugs (empty = nowhere). Mirrors authz.AppPermissionScope.
+ */
+export declare function appScopes(snapshot: AccessSnapshot, key: string): {
+    all: boolean;
+    apps: string[];
+};
+/** Distinct permission keys held for `saasApp` (or anywhere). Handy for nav/badges. */
+export declare function permissionsFor(snapshot: AccessSnapshot, opts?: PermissionCheckOptions): string[];

package/dist/access/predicates.js

@@ -0,0 +1,76 @@
+/**
+ * Mirrors c1m-server authz.entryCoversApp: platform scope covers every app;
+ * saas_app scope covers "*" or a case-insensitive slug match; workspace-scoped
+ * entries never satisfy an app-level check.
+ */
+export function entryCoversApp(entry, saasApp) {
+    switch (entry.scope_type) {
+        case "platform":
+            return true;
+        case "saas_app":
+            if (saasApp === undefined)
+                return true;
+            return entry.scope_id === "*" || entry.scope_id.toLowerCase() === saasApp.toLowerCase();
+        default:
+            return false;
+    }
+}
+/** True when the subject is active and holds `key` for the given app (or anywhere). */
+export function hasPermission(snapshot, key, opts = {}) {
+    if (!snapshot.active)
+        return false;
+    return snapshot.permissions.some((entry) => entry.key === key && entryCoversApp(entry, opts.saasApp));
+}
+export function hasAnyPermission(snapshot, keys, opts = {}) {
+    return keys.some((key) => hasPermission(snapshot, key, opts));
+}
+export function hasAllPermissions(snapshot, keys, opts = {}) {
+    return keys.every((key) => hasPermission(snapshot, key, opts));
+}
+/**
+ * Workspace-staff check. Platform owners always pass (they own every
+ * workspace); otherwise the workspace's effective permission list decides.
+ * Platform/saas_app entries never confer workspace-staff permissions.
+ */
+export function hasWorkspacePermission(snapshot, workspaceId, key) {
+    if (!snapshot.active)
+        return false;
+    if (snapshot.is_owner)
+        return true;
+    return (snapshot.workspace_permissions[workspaceId] ?? []).includes(key);
+}
+export function isPlatformOwner(snapshot) {
+    return snapshot.active && snapshot.is_owner;
+}
+/**
+ * The saas_app scopes under which `key` is held. Returns `{ all: true }` when a
+ * platform-scoped or "*" entry grants it everywhere; otherwise the explicit
+ * app slugs (empty = nowhere). Mirrors authz.AppPermissionScope.
+ */
+export function appScopes(snapshot, key) {
+    if (!snapshot.active)
+        return { all: false, apps: [] };
+    const apps = new Set();
+    for (const entry of snapshot.permissions) {
+        if (entry.key !== key)
+            continue;
+        if (entry.scope_type === "platform")
+            return { all: true, apps: [] };
+        if (entry.scope_type === "saas_app") {
+            if (entry.scope_id === "*")
+                return { all: true, apps: [] };
+            apps.add(entry.scope_id.toLowerCase());
+        }
+    }
+    return { all: false, apps: [...apps].sort() };
+}
+/** Distinct permission keys held for `saasApp` (or anywhere). Handy for nav/badges. */
+export function permissionsFor(snapshot, opts = {}) {
+    if (!snapshot.active)
+        return [];
+    const keys = new Set();
+    for (const entry of snapshot.permissions)
+        if (entryCoversApp(entry, opts.saasApp))
+            keys.add(entry.key);
+    return [...keys].sort();
+}

package/dist/access/react.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from "react";
+import { type PermissionCheckOptions } from "./predicates.js";
+import { type AccessSnapshot } from "./snapshot.js";
+export interface AccessProviderProps {
+    snapshot: AccessSnapshot;
+    children: ReactNode;
+}
+/** Feed the server-loaded snapshot to client components once, at the app/area layout. */
+export declare function AccessProvider({ snapshot, children }: AccessProviderProps): import("react").JSX.Element;
+export declare function useAccess(): AccessSnapshot;
+/** Optional-provider variant: returns an inactive empty snapshot outside a provider. */
+export declare function useAccessOrEmpty(): AccessSnapshot;
+export declare function useCan(): (key: string, opts?: PermissionCheckOptions) => boolean;
+export declare function useCanWorkspace(workspaceId: string): (key: string) => boolean;
+export declare function useIsPlatformOwner(): boolean;
+export interface CanProps extends PermissionCheckOptions {
+    /** One key, or several — all must hold unless `mode="any"`. */
+    permission: string | readonly string[];
+    mode?: "all" | "any";
+    /** Workspace-staff check instead of platform/app check. */
+    workspaceId?: string;
+    /** Invert: render children when the check FAILS. */
+    not?: boolean;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+/** Render-gate. Presentation only — the backend remains the security boundary. */
+export declare function Can({ permission, mode, workspaceId, saasApp, not, fallback, children }: CanProps): import("react").JSX.Element;

package/dist/access/react.js

@@ -0,0 +1,40 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { hasPermission, hasWorkspacePermission, isPlatformOwner } from "./predicates.js";
+import { emptySnapshot } from "./snapshot.js";
+const AccessContext = createContext(null);
+/** Feed the server-loaded snapshot to client components once, at the app/area layout. */
+export function AccessProvider({ snapshot, children }) {
+    const value = useMemo(() => snapshot, [snapshot]);
+    return _jsx(AccessContext.Provider, { value: value, children: children });
+}
+export function useAccess() {
+    const snapshot = useContext(AccessContext);
+    if (!snapshot)
+        throw new Error("useAccess must be used inside <AccessProvider>");
+    return snapshot;
+}
+/** Optional-provider variant: returns an inactive empty snapshot outside a provider. */
+export function useAccessOrEmpty() {
+    return useContext(AccessContext) ?? emptySnapshot();
+}
+export function useCan() {
+    const snapshot = useAccess();
+    return useMemo(() => (key, opts) => hasPermission(snapshot, key, opts), [snapshot]);
+}
+export function useCanWorkspace(workspaceId) {
+    const snapshot = useAccess();
+    return useMemo(() => (key) => hasWorkspacePermission(snapshot, workspaceId, key), [snapshot, workspaceId]);
+}
+export function useIsPlatformOwner() {
+    return isPlatformOwner(useAccess());
+}
+/** Render-gate. Presentation only — the backend remains the security boundary. */
+export function Can({ permission, mode = "all", workspaceId, saasApp, not = false, fallback = null, children }) {
+    const snapshot = useAccess();
+    const keys = typeof permission === "string" ? [permission] : permission;
+    const check = (key) => workspaceId !== undefined ? hasWorkspacePermission(snapshot, workspaceId, key) : hasPermission(snapshot, key, { saasApp });
+    const allowed = mode === "any" ? keys.some(check) : keys.every(check);
+    return _jsx(_Fragment, { children: allowed !== not ? children : fallback });
+}