@c1m-public/platform-auth 0.3.1 → 0.5.0

package/README.md

@@ -1,28 +1,106 @@
 # @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`, `SSO_ERROR_MESSAGES`, `AUTH_ERROR_MESSAGES`, `authErrorMessage(code, overrides?)`, `isAuthErrorCode`, `handoffErrorMessage`, `isHandoffErrorCode` | One sign-in error vocabulary — handoff, admission and SSO codes. Surfaces pass their own copy as `overrides` instead of forking the map. |
 
 ```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. |
+| `managedDashes`, `dashRole` | The dashes a subject runs, from the mirrored `dash.owner` / `dash.admin` bundle grants (`snapshot.dash_roles`). Admission only — gate an action with `hasPermission(snapshot, "dash.publish", { saasApp })`. Platform managers are not listed; admit them on `platform.tenants.manage`. |
+| `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,20 @@
+/** 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];
+/** Dash-owner permission keys (granted at dash scope, mirrored from the membership role). */
+export declare const DASH_PERMISSIONS: readonly ["dash.apps.manage", "dash.billing.manage", "dash.channels.manage", "dash.customers.manage", "dash.domains.manage", "dash.members.manage", "dash.ownership.transfer", "dash.plans.manage", "dash.publish", "dash.settings.manage", "dash.workspaces.admin", "dash.workspaces.manage"];
+export type DashPermissionKey = (typeof DASH_PERMISSIONS)[number];
+/** Membership-mirrored dash role bundles (grant keys at dash scope). */
+export declare const DASH_ROLES: readonly ["dash.admin", "dash.owner"];
+export type DashRole = (typeof DASH_ROLES)[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 | DashPermissionKey | LeadBrokerPermissionKey | WorkspacePermissionKey;

package/dist/access/generated/keys.js

@@ -0,0 +1,78 @@
+// 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",
+];
+/** Dash-owner permission keys (granted at dash scope, mirrored from the membership role). */
+export const DASH_PERMISSIONS = [
+    "dash.apps.manage",
+    "dash.billing.manage",
+    "dash.channels.manage",
+    "dash.customers.manage",
+    "dash.domains.manage",
+    "dash.members.manage",
+    "dash.ownership.transfer",
+    "dash.plans.manage",
+    "dash.publish",
+    "dash.settings.manage",
+    "dash.workspaces.admin",
+    "dash.workspaces.manage",
+];
+/** Membership-mirrored dash role bundles (grant keys at dash scope). */
+export const DASH_ROLES = [
+    "dash.admin",
+    "dash.owner",
+];
+/** 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,48 @@
+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;
+/**
+ * The dashes this subject runs, from the mirrored dash bundle grants — the
+ * admission list for the Admin Center's dash area. Platform managers are not
+ * listed: their reach is platform-wide, so admit them with
+ * `hasPermission(snapshot, "platform.tenants.manage")` instead.
+ */
+export declare function managedDashes(snapshot: AccessSnapshot): Array<{
+    saasApp: string;
+    role: string;
+}>;
+/** The dash bundle held on one dash, or "" when the subject holds none there. */
+export declare function dashRole(snapshot: AccessSnapshot, saasApp: string): string;
+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,95 @@
+/**
+ * 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);
+}
+/**
+ * The dashes this subject runs, from the mirrored dash bundle grants — the
+ * admission list for the Admin Center's dash area. Platform managers are not
+ * listed: their reach is platform-wide, so admit them with
+ * `hasPermission(snapshot, "platform.tenants.manage")` instead.
+ */
+export function managedDashes(snapshot) {
+    if (!snapshot.active)
+        return [];
+    return Object.entries(snapshot.dash_roles)
+        .map(([saasApp, role]) => ({ saasApp, role }))
+        .sort((a, b) => a.saasApp.localeCompare(b.saasApp));
+}
+/** The dash bundle held on one dash, or "" when the subject holds none there. */
+export function dashRole(snapshot, saasApp) {
+    if (!snapshot.active)
+        return "";
+    return snapshot.dash_roles[saasApp] ?? "";
+}
+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 });
+}

package/dist/access/snapshot.d.ts

@@ -0,0 +1,39 @@
+/** Scope a permission entry applies to. Mirrors c1m-server authz.Scope*. */
+export type AccessScopeType = "platform" | "saas_app" | "workspace";
+export interface AccessEntry {
+    /** Permission key, e.g. "platform.users.manage_access". */
+    key: string;
+    scope_type: AccessScopeType;
+    /** "" for platform scope; saas_app slug or "*" for saas_app scope; workspace id for workspace scope. */
+    scope_id: string;
+}
+/**
+ * The resolved authorization snapshot for one subject, as returned by
+ * `GET /api/v1/platform/access`. This is the *output* of the backend resolver
+ * (base-role grant ∪ scoped grants), never the grant rows themselves.
+ */
+export interface AccessSnapshot {
+    subject_id: string;
+    /** Monotonic; bumps on any grant/role change. Use for optimistic concurrency and cache keys. */
+    access_version: number;
+    is_owner: boolean;
+    active: boolean;
+    /** Platform operator base role (derived; display only — never authorize on it). */
+    platform_role: string;
+    permissions: AccessEntry[];
+    /**
+     * Dash bundle (`dash.owner` / `dash.admin`) per saas_app id, mirrored from
+     * the subject's dash membership. This is the admission list for the dash
+     * area: the dashes this subject runs. What they may *do* on one is a normal
+     * `hasPermission(snapshot, key, { saasApp })` check — platform managers hold
+     * their authority platform-wide and so appear here not at all.
+     */
+    dash_roles: Record<string, string>;
+    /** Effective workspace-staff permission keys per workspace id. */
+    workspace_permissions: Record<string, string[]>;
+    /** Workspace-staff role bundle per workspace id (display only). */
+    workspace_roles: Record<string, string>;
+}
+export declare function emptySnapshot(subjectId?: string): AccessSnapshot;
+/** Runtime validator for the wire payload. Throws AccessSnapshotError("invalid_snapshot"). */
+export declare function parseAccessSnapshot(input: unknown): AccessSnapshot;

package/dist/access/snapshot.js

@@ -0,0 +1,92 @@
+import { AccessSnapshotError } from "./errors.js";
+const SCOPE_TYPES = new Set(["platform", "saas_app", "workspace"]);
+export function emptySnapshot(subjectId = "") {
+    return {
+        subject_id: subjectId,
+        access_version: 0,
+        is_owner: false,
+        active: false,
+        platform_role: "",
+        permissions: [],
+        dash_roles: {},
+        workspace_permissions: {},
+        workspace_roles: {},
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(field, why) {
+    throw new AccessSnapshotError("invalid_snapshot", `access snapshot: ${field} ${why}`);
+}
+/** Runtime validator for the wire payload. Throws AccessSnapshotError("invalid_snapshot"). */
+export function parseAccessSnapshot(input) {
+    if (!isRecord(input))
+        fail("payload", "is not an object");
+    const { subject_id, access_version, is_owner, active, platform_role, permissions, dash_roles, workspace_permissions, workspace_roles } = input;
+    if (typeof subject_id !== "string" || subject_id === "")
+        fail("subject_id", "must be a non-empty string");
+    if (typeof access_version !== "number" || !Number.isInteger(access_version) || access_version < 0)
+        fail("access_version", "must be a non-negative integer");
+    if (typeof is_owner !== "boolean")
+        fail("is_owner", "must be a boolean");
+    if (typeof active !== "boolean")
+        fail("active", "must be a boolean");
+    if (platform_role !== undefined && platform_role !== null && typeof platform_role !== "string")
+        fail("platform_role", "must be a string");
+    if (!Array.isArray(permissions))
+        fail("permissions", "must be an array");
+    const entries = permissions.map((raw, i) => {
+        if (!isRecord(raw))
+            fail(`permissions[${i}]`, "is not an object");
+        const { key, scope_type, scope_id } = raw;
+        if (typeof key !== "string" || key === "")
+            fail(`permissions[${i}].key`, "must be a non-empty string");
+        if (typeof scope_type !== "string" || !SCOPE_TYPES.has(scope_type))
+            fail(`permissions[${i}].scope_type`, "must be platform|saas_app|workspace");
+        if (scope_id !== undefined && scope_id !== null && typeof scope_id !== "string")
+            fail(`permissions[${i}].scope_id`, "must be a string");
+        return { key, scope_type: scope_type, scope_id: typeof scope_id === "string" ? scope_id : "" };
+    });
+    const dashRoles = {};
+    if (dash_roles !== undefined && dash_roles !== null) {
+        if (!isRecord(dash_roles))
+            fail("dash_roles", "must be an object");
+        for (const [dash, role] of Object.entries(dash_roles)) {
+            if (typeof role !== "string")
+                fail(`dash_roles[${dash}]`, "must be a string");
+            dashRoles[dash] = role;
+        }
+    }
+    const wsPerms = {};
+    if (workspace_permissions !== undefined && workspace_permissions !== null) {
+        if (!isRecord(workspace_permissions))
+            fail("workspace_permissions", "must be an object");
+        for (const [ws, keys] of Object.entries(workspace_permissions)) {
+            if (!Array.isArray(keys) || keys.some((k) => typeof k !== "string"))
+                fail(`workspace_permissions[${ws}]`, "must be a string array");
+            wsPerms[ws] = [...keys];
+        }
+    }
+    const wsRoles = {};
+    if (workspace_roles !== undefined && workspace_roles !== null) {
+        if (!isRecord(workspace_roles))
+            fail("workspace_roles", "must be an object");
+        for (const [ws, role] of Object.entries(workspace_roles)) {
+            if (typeof role !== "string")
+                fail(`workspace_roles[${ws}]`, "must be a string");
+            wsRoles[ws] = role;
+        }
+    }
+    return {
+        subject_id,
+        access_version,
+        is_owner,
+        active,
+        platform_role: typeof platform_role === "string" ? platform_role : "",
+        permissions: entries,
+        dash_roles: dashRoles,
+        workspace_permissions: wsPerms,
+        workspace_roles: wsRoles,
+    };
+}

package/dist/handoff-errors.d.ts

@@ -1,4 +1,13 @@
 export declare const HANDOFF_ERROR_MESSAGES: Record<string, string>;
 export declare const HANDOFF_ERROR_FALLBACK = "Sign-in failed \u2014 please try again.";
+export declare const SSO_ERROR_MESSAGES: Record<string, string>;
+/** Every sign-in failure code this package knows: handoff, admission, and SSO. */
+export declare const AUTH_ERROR_MESSAGES: Record<string, string>;
 export declare function handoffErrorMessage(code: string | null | undefined): string;
 export declare function isHandoffErrorCode(code: string | null | undefined): boolean;
+/**
+ * Resolve any sign-in failure code to copy. `overrides` wins, so a surface can
+ * reword a shared code or add its own without forking the whole map.
+ */
+export declare function authErrorMessage(code: string | null | undefined, overrides?: Record<string, string>): string;
+export declare function isAuthErrorCode(code: string | null | undefined, overrides?: Record<string, string>): boolean;

package/dist/handoff-errors.js

@@ -23,6 +23,23 @@ export const HANDOFF_ERROR_MESSAGES = {
     admin_surface: "Platform operators sign in here; SaaSDash sent you to the Admin Center.",
 };
 export const HANDOFF_ERROR_FALLBACK = "Sign-in failed — please try again.";
+// External sign-in (OIDC/social) codes every platform surface renders identically.
+// Surface-specific copy stays in the app and is passed as `overrides`.
+export const SSO_ERROR_MESSAGES = {
+    sso_cancelled: "Sign-in was cancelled.",
+    sso_denied: "Sign-in was refused by the provider.",
+    sso_state_invalid: "Sign-in attempt expired — please try again.",
+    sso_start_failed: "Could not start sign-in with that provider. Please try again.",
+    sso_complete_failed: "Sign-in could not be completed. Please try again.",
+    sso_unknown_operator: "No operator account matches that identity. Ask an admin for an invite.",
+    sso_provider_not_found: "That sign-in provider is not available.",
+    sso_not_configured: "That sign-in provider is not fully configured.",
+};
+/** Every sign-in failure code this package knows: handoff, admission, and SSO. */
+export const AUTH_ERROR_MESSAGES = {
+    ...HANDOFF_ERROR_MESSAGES,
+    ...SSO_ERROR_MESSAGES,
+};
 export function handoffErrorMessage(code) {
     if (!code)
         return HANDOFF_ERROR_FALLBACK;
@@ -31,3 +48,18 @@ export function handoffErrorMessage(code) {
 export function isHandoffErrorCode(code) {
     return !!code && Object.prototype.hasOwnProperty.call(HANDOFF_ERROR_MESSAGES, code);
 }
+/**
+ * Resolve any sign-in failure code to copy. `overrides` wins, so a surface can
+ * reword a shared code or add its own without forking the whole map.
+ */
+export function authErrorMessage(code, overrides) {
+    if (!code)
+        return HANDOFF_ERROR_FALLBACK;
+    return overrides?.[code] ?? AUTH_ERROR_MESSAGES[code] ?? HANDOFF_ERROR_FALLBACK;
+}
+export function isAuthErrorCode(code, overrides) {
+    if (!code)
+        return false;
+    return (Object.prototype.hasOwnProperty.call(AUTH_ERROR_MESSAGES, code) ||
+        (!!overrides && Object.prototype.hasOwnProperty.call(overrides, code)));
+}

package/dist/handoff.d.ts

@@ -1,11 +1,11 @@
 import type { DeviceIdentityStore } from "./device-cookie.js";
+import { type Resolvable } from "./internal.js";
 import { type AuthResponse } from "./token.js";
 export declare function sourceStartPath(app: string): string;
 export declare function brokerPaths(app: string): {
     readonly start: `/api/v1/platform/auth/handoffs/${string}/start`;
     readonly exchange: `/api/v1/platform/auth/handoffs/${string}/exchange`;
 };
-type Resolvable = string | (() => string);
 export interface HandoffTargetConfig {
     app: string;
     apiUrl: Resolvable;
@@ -53,4 +53,3 @@ export declare function createHandoffSource(config: HandoffSourceConfig): {
     start(request: Request, app: string): Promise<Response>;
 };
 export type HandoffSource = ReturnType<typeof createHandoffSource>;
-export {};

package/dist/handoff.js

@@ -1,6 +1,7 @@
 import { deleteCookie, readCookie, setCookie } from "./cookies.js";
 import { forwardedRequestHeaders } from "./forwarding.js";
 import { safeInternalPath } from "./return-path.js";
+import { DEFAULT_FETCH_TIMEOUT_MS, resolveValue, timedFetch } from "./internal.js";
 import { hasTokenAudience, parseAuthResponse } from "./token.js";
 /**
  * Browser halves of c1m-server's `/api/v1/platform/auth/handoffs/{app}` broker.
@@ -10,7 +11,6 @@ import { hasTokenAudience, parseAuthResponse } from "./token.js";
  */
 const HANDOFF_COOKIE_TTL_SECONDS = 120;
 const CHALLENGE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
-const DEFAULT_TIMEOUT_MS = 10_000;
 export function sourceStartPath(app) {
     return `/api/auth/handoffs/${encodeURIComponent(app)}/start`;
 }
@@ -21,7 +21,6 @@ export function brokerPaths(app) {
         exchange: `/api/v1/platform/auth/handoffs/${key}/exchange`,
     };
 }
-const resolve = (value) => (typeof value === "function" ? value() : value);
 function originOf(value) {
     try {
         return new URL(value).origin;
@@ -56,22 +55,12 @@ function loginErrorRedirect(origin, loginPath, code) {
     target.searchParams.set("error", code);
     return redirect(target);
 }
-async function fetchWithTimeout(input, init, timeoutMs) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        return await fetch(input, { ...init, signal: controller.signal, cache: "no-store" });
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
 export function createHandoffTarget(config) {
     const secure = config.secureCookies ?? true;
     const prefix = `${secure ? "__Host-" : ""}${config.cookiePrefix}_handoff_`;
     const cookies = { state: `${prefix}state`, verifier: `${prefix}verifier`, from: `${prefix}from` };
     const cookieOptions = { httpOnly: true, secure, sameSite: "lax", path: "/", maxAge: HANDOFF_COOKIE_TTL_SECONDS };
-    const timeout = config.fetchTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeout = config.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
     const clearHandoffCookies = (response) => {
         for (const name of Object.values(cookies))
             deleteCookie(response, name, { path: "/", secure });
@@ -87,7 +76,7 @@ export function createHandoffTarget(config) {
             const source = config.sources[sourceKey];
             if (!source)
                 return fail(url.origin, "handoff_request_invalid");
-            const sourceOrigin = originOf(resolve(source));
+            const sourceOrigin = originOf(resolveValue(source));
             if (!sourceOrigin)
                 return fail(url.origin, "handoff_not_configured");
             const verifier = randomToken(48);
@@ -121,7 +110,7 @@ export function createHandoffTarget(config) {
                     "X-Client-Type": config.clientType,
                     "X-Client-Device-ID": device.value,
                 });
-                const response = await fetchWithTimeout(`${resolve(config.apiUrl)}${brokerPaths(config.app).exchange}`, { method: "POST", headers, body: JSON.stringify({ code, code_verifier: verifier }) }, timeout);
+                const response = await timedFetch(`${resolveValue(config.apiUrl)}${brokerPaths(config.app).exchange}`, { init: { method: "POST", headers, body: JSON.stringify({ code, code_verifier: verifier }) }, timeoutMs: timeout });
                 const payload = await response.json().catch(() => ({}));
                 if (!response.ok) {
                     const backendCode = payload?.code;
@@ -144,14 +133,14 @@ export function createHandoffTarget(config) {
 const DEFAULT_TARGET_CALLBACK = "/api/auth/platform-sso/callback";
 const DEFAULT_TARGET_LOGIN = "/login";
 export function createHandoffSource(config) {
-    const timeout = config.fetchTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeout = config.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
     return {
         /** GET `/api/auth/handoffs/{app}/start?code_challenge=&state=` */
         async start(request, app) {
             const target = config.targets[app];
             if (!target)
                 return new Response("unknown handoff application", { status: 404, headers: { "Cache-Control": "no-store" } });
-            const targetOrigin = originOf(resolve(target.origin));
+            const targetOrigin = originOf(resolveValue(target.origin));
             const targetLogin = target.loginPath ?? DEFAULT_TARGET_LOGIN;
             if (!targetOrigin)
                 return new Response("handoff target not configured", { status: 503, headers: { "Cache-Control": "no-store" } });
@@ -175,7 +164,7 @@ export function createHandoffSource(config) {
                     "X-Client-Type": config.clientType,
                     Authorization: `Bearer ${token}`,
                 });
-                const response = await fetchWithTimeout(`${resolve(config.apiUrl)}${brokerPaths(app).start}`, { method: "POST", headers, body: JSON.stringify({ code_challenge: challenge, state }) }, timeout);
+                const response = await timedFetch(`${resolveValue(config.apiUrl)}${brokerPaths(app).start}`, { init: { method: "POST", headers, body: JSON.stringify({ code_challenge: challenge, state }) }, timeoutMs: timeout });
                 if (response.status === 401)
                     return sourceLogin();
                 const payload = await response.json().catch(() => ({}));

package/dist/internal.d.ts

@@ -0,0 +1,16 @@
+/** A value that may be fixed or resolved per call (env read at request time). */
+export type Resolvable<T = string> = T | (() => T);
+export declare function resolveValue<T>(value: Resolvable<T>): T;
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 10000;
+export interface TimedFetchOptions {
+    init?: RequestInit;
+    /** Omit or pass 0 for no timeout. */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * `fetch` with an abort timeout and `cache: "no-store"`. Rejects with whatever
+ * fetch rejects with (an abort surfaces as an AbortError); callers map that to
+ * their own error vocabulary.
+ */
+export declare function timedFetch(url: string, options?: TimedFetchOptions): Promise<Response>;

package/dist/internal.js

@@ -0,0 +1,27 @@
+// Shared internals. Not part of the public surface — exported only so the
+// session and access halves of this package stop keeping private copies.
+export function resolveValue(value) {
+    return typeof value === "function" ? value() : value;
+}
+export const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+/**
+ * `fetch` with an abort timeout and `cache: "no-store"`. Rejects with whatever
+ * fetch rejects with (an abort surfaces as an AbortError); callers map that to
+ * their own error vocabulary.
+ */
+export async function timedFetch(url, options = {}) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const controller = options.timeoutMs ? new AbortController() : undefined;
+    const timer = controller ? setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+    try {
+        return await doFetch(url, {
+            ...options.init,
+            cache: "no-store",
+            ...(controller ? { signal: controller.signal } : {}),
+        });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/session-refresh.d.ts

@@ -1,3 +1,4 @@
+import { type Resolvable } from "./internal.js";
 /**
  * Coalesced refresh-token exchange for a BFF proxy: same refresh token within
  * a short window shares one backend call. Per-process best effort; backend
@@ -8,7 +9,7 @@ export interface RefreshedSession {
     refreshToken?: string;
 }
 export interface SessionRefresherConfig {
-    apiUrl: string | (() => string);
+    apiUrl: Resolvable;
     refreshPath: string;
     clientType: string;
     audience: string;

package/dist/session-refresh.js

@@ -1,23 +1,21 @@
+import { DEFAULT_FETCH_TIMEOUT_MS, resolveValue, timedFetch } from "./internal.js";
 import { hasTokenAudience, parseAuthResponse } from "./token.js";
 const DEFAULT_TTL_MS = 5000;
 const DEFAULT_MAX = 1000;
-const DEFAULT_TIMEOUT_MS = 10_000;
 export function createSessionRefresher(config) {
     const ttl = config.singleflightTtlMs ?? DEFAULT_TTL_MS;
     const max = config.maxSingleflights ?? DEFAULT_MAX;
-    const timeoutMs = config.fetchTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeoutMs = config.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
     const inflight = new Map();
     async function perform(refreshToken) {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
         try {
-            const apiUrl = typeof config.apiUrl === "function" ? config.apiUrl() : config.apiUrl;
-            const response = await fetch(`${apiUrl}${config.refreshPath}`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json", "X-Client-Type": config.clientType },
-                body: JSON.stringify({ refresh_token: refreshToken }),
-                cache: "no-store",
-                signal: controller.signal,
+            const response = await timedFetch(`${resolveValue(config.apiUrl)}${config.refreshPath}`, {
+                init: {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", "X-Client-Type": config.clientType },
+                    body: JSON.stringify({ refresh_token: refreshToken }),
+                },
+                timeoutMs,
             });
             if (!response.ok)
                 return null;
@@ -29,9 +27,6 @@ export function createSessionRefresher(config) {
         catch {
             return null;
         }
-        finally {
-            clearTimeout(timer);
-        }
     }
     function prune(now) {
         for (const [token, entry] of inflight) {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@c1m-public/platform-auth",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "license": "MIT",
-  "description": "Framework-neutral session helpers for C1M platform surfaces: token payload reads, forwarded client headers, safe return paths, device identity cookies, and the first-party session handoff (target callback + source start) built on Web Request/Response",
+  "description": "Server-side session and authorization helpers for C1M platform surfaces: token/session reads, the first-party handoff (PKCE target + source), proxy session gate and coalesced refresh, plus the resolved access snapshot, typed permission keys, predicates, a Next loader and React bindings under ./access",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cloud1mediaLtd/mml-js.git",
@@ -12,12 +12,61 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
-    "./next": { "types": "./dist/next.d.ts", "default": "./dist/next.js" }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    },
+    "./access": {
+      "types": "./dist/access/index.d.ts",
+      "default": "./dist/access/index.js"
+    },
+    "./access/next": {
+      "types": "./dist/access/next.d.ts",
+      "default": "./dist/access/next.js"
+    },
+    "./access/react": {
+      "types": "./dist/access/react.d.ts",
+      "default": "./dist/access/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "server-only": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "next": "16.3.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
-  "files": ["dist", "README.md"],
-  "engines": { "node": ">=20" },
-  "publishConfig": { "access": "public" },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "pnpm clean && tsc -p tsconfig.build.json",
@@ -25,7 +74,5 @@
     "test": "vitest",
     "test:run": "vitest run",
     "type-check": "tsc -p tsconfig.json --noEmit"
-  },
-  "dependencies": { "server-only": "0.0.1" },
-  "devDependencies": { "typescript": "5.9.3", "vitest": "^4.1.4" }
-}
+  }
+}