@c1m-public/platform-auth 0.6.0 → 0.7.0

package/README.md

@@ -56,6 +56,33 @@ const source = createHandoffSource({ apiUrl, clientType, targets: { docs: { orig
   getAccessToken, loginPath: "/login" });
 ```
 
+## `./next` — a Next.js surface's session, fetch and errors
+
+Server-only. Everything under `.` plus the three things every first-party app
+used to hand-roll:
+
+| Export | Purpose |
+|---|---|
+| `createSessionStore({ audience, cookies, maxAgeSeconds?, secure?, cookieDomain?, defaultRememberMe?, refresh?, requestBoundary?, onError? })` | The session/refresh/remember cookies over `next/headers`: `createSession`, `writeSessionCookies(response, …)`, `getSession`, `getAccessToken`, `getRefreshToken`, `getSessionWithRefresh`, `updateAccessToken`, `isRememberMe`, `destroySession`, `clearSessionCookies(response)`, `requireSession`, `isAuthenticated`. rememberMe=false → no Max-Age; the remember choice survives refresh; deletes carry the same attributes as sets (a `__Host-` cookie ignores a Secure-less delete); a token for another audience is never stored or read. Pass `requestBoundary: connection` (from `next/server`) so Cache Components treat session state as request-time. |
+| `createPlatformFetch({ apiUrl, getAccessToken, forwardHeaders?, timeoutMs?, fetch? })` | Bearer + forwarded client headers + `no-store` + per-method timeout (10 s reads, 30 s writes): `fetchAuthed`, `fetchAuthedJson` (null on 204/404), `fetchAuthedJsonStrict`, `fetchJsonWithAccessToken`, `fetchPublicJson`, `fetchAuthedField`, `fetchAuthedItems`. A missing session **throws** (401), never returns null. |
+| `buildForwardedRequestHeaders` | The incoming request's client identity as headers, for a call you make yourself. |
+| `SessionExpiredError`, `RecentAuthenticationRequiredError`, `SSOReauthenticationRequiredError`, `PlatformServerFetchError{path,status?,code?,requestId?}` + `is*Error` predicates | One error vocabulary; 401 bodies map by `code`. |
+| `mapControlError`, `controlRequest(run)` | Translate a `@c1m-public/control-client` failure into that vocabulary, keeping the backend's code and request id. |
+
+```ts
+// lib/auth/session.ts
+export const sessions = createSessionStore({
+  audience: "platform_admin",
+  cookies: { session: "__Host-platform_session", refreshToken: "__Host-platform_refresh_token", rememberMe: "platform_remember" },
+  requestBoundary: connection,
+  refresh: { apiUrl: getApiUrl, refreshPath: "/api/v1/platform/auth/refresh", clientType: "nextjs-platform" },
+});
+
+// lib/platform/fetch.ts
+export const platform = createPlatformFetch({ apiUrl: getApiUrl, getAccessToken: sessions.getAccessToken });
+const items = await platform.fetchAuthedItems<Workspace>("/api/v1/platform/workspaces");
+```
+
 ## `./access` — authorization
 
 The resolved snapshot from `GET /api/v1/platform/access`.

package/dist/access/index.d.ts

@@ -1,5 +1,148 @@
-export * from "./generated/keys.js";
-export * from "./errors.js";
-export * from "./snapshot.js";
-export * from "./predicates.js";
-export * from "./fetch.js";
+import { R as Resolvable } from '../internal-rnEuAE21.js';
+
+/** Platform-operator permission keys. */
+declare const PLATFORM_PERMISSIONS: readonly ["affiliates.finance.manage", "affiliates.partners.manage", "affiliates.programmes.manage", "affiliates.view", "linkservice.domains.manage", "linkservice.links.manage", "linkservice.qr.manage", "linkservice.view", "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.offboarding.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"];
+type PlatformPermissionKey = (typeof PLATFORM_PERMISSIONS)[number];
+/** Dash-owner permission keys (granted at dash scope, mirrored from the membership role). */
+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"];
+type DashPermissionKey = (typeof DASH_PERMISSIONS)[number];
+/** Membership-mirrored dash role bundles (grant keys at dash scope). */
+declare const DASH_ROLES: readonly ["dash.admin", "dash.owner"];
+type DashRole = (typeof DASH_ROLES)[number];
+/** Lead-broker workload permission keys. */
+declare const LEADBROKER_PERMISSIONS: readonly ["leadbroker.finance.manage", "leadbroker.leads.dispatch", "leadbroker.leads.review", "leadbroker.leads.view", "leadbroker.policy.manage"];
+type LeadBrokerPermissionKey = (typeof LEADBROKER_PERMISSIONS)[number];
+/** Workspace-staff permission keys. */
+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"];
+type WorkspacePermissionKey = (typeof WORKSPACE_PERMISSIONS)[number];
+/** Assignable workspace-staff role bundles (grant keys at workspace scope). */
+declare const WORKSPACE_ROLES: readonly ["workspace.editor", "workspace.frontdesk", "workspace.manager"];
+type WorkspaceRole = (typeof WORKSPACE_ROLES)[number];
+/** Every permission key the backend can grant, across all scopes. */
+type PermissionKey = PlatformPermissionKey | DashPermissionKey | LeadBrokerPermissionKey | WorkspacePermissionKey;
+
+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.
+ */
+declare class AccessSnapshotError extends Error {
+    readonly code: AccessErrorCode;
+    readonly status: number | undefined;
+    constructor(code: AccessErrorCode, message: string, status?: number);
+}
+declare function isAccessSnapshotError(error: unknown, code?: AccessErrorCode): error is AccessSnapshotError;
+
+/** Scope a permission entry applies to. Mirrors c1m-server authz.Scope*. */
+type AccessScopeType = "platform" | "saas_app" | "workspace";
+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.
+ */
+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>;
+}
+declare function emptySnapshot(subjectId?: string): AccessSnapshot;
+/** Runtime validator for the wire payload. Throws AccessSnapshotError("invalid_snapshot"). */
+declare function parseAccessSnapshot(input: unknown): AccessSnapshot;
+
+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.
+ */
+declare function entryCoversApp(entry: AccessEntry, saasApp: string | undefined): boolean;
+/** True when the subject is active and holds `key` for the given app (or anywhere). */
+declare function hasPermission(snapshot: AccessSnapshot, key: string, opts?: PermissionCheckOptions): boolean;
+declare function hasAnyPermission(snapshot: AccessSnapshot, keys: readonly string[], opts?: PermissionCheckOptions): boolean;
+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.
+ */
+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.
+ */
+declare function managedDashes(snapshot: AccessSnapshot): Array<{
+    saasApp: string;
+    role: string;
+}>;
+/** The dash bundle held on one dash, or "" when the subject holds none there. */
+declare function dashRole(snapshot: AccessSnapshot, saasApp: string): string;
+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.
+ */
+declare function appScopes(snapshot: AccessSnapshot, key: string): {
+    all: boolean;
+    apps: string[];
+};
+/** Distinct permission keys held for `saasApp` (or anywhere). Handy for nav/badges. */
+declare function permissionsFor(snapshot: AccessSnapshot, opts?: PermissionCheckOptions): string[];
+
+declare const DEFAULT_ACCESS_ENDPOINT_PATH = "/api/v1/platform/access";
+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.
+ */
+declare function fetchAccessSnapshot(opts: FetchAccessSnapshotOptions): Promise<AccessSnapshot>;
+
+export { type AccessEntry, type AccessErrorCode, type AccessScopeType, type AccessSnapshot, AccessSnapshotError, DASH_PERMISSIONS, DASH_ROLES, DEFAULT_ACCESS_ENDPOINT_PATH, type DashPermissionKey, type DashRole, type FetchAccessSnapshotOptions, LEADBROKER_PERMISSIONS, type LeadBrokerPermissionKey, PLATFORM_PERMISSIONS, type PermissionCheckOptions, type PermissionKey, type PlatformPermissionKey, WORKSPACE_PERMISSIONS, WORKSPACE_ROLES, type WorkspacePermissionKey, type WorkspaceRole, appScopes, dashRole, emptySnapshot, entryCoversApp, fetchAccessSnapshot, hasAllPermissions, hasAnyPermission, hasPermission, hasWorkspacePermission, isAccessSnapshotError, isPlatformOwner, managedDashes, parseAccessSnapshot, permissionsFor };

package/dist/access/index.js

@@ -1,5 +1,2 @@
-export * from "./generated/keys.js";
-export * from "./errors.js";
-export * from "./snapshot.js";
-export * from "./predicates.js";
-export * from "./fetch.js";
+export { AccessSnapshotError, DASH_PERMISSIONS, DASH_ROLES, DEFAULT_ACCESS_ENDPOINT_PATH, LEADBROKER_PERMISSIONS, PLATFORM_PERMISSIONS, WORKSPACE_PERMISSIONS, WORKSPACE_ROLES, appScopes, dashRole, emptySnapshot, entryCoversApp, fetchAccessSnapshot, hasAllPermissions, hasAnyPermission, hasPermission, hasWorkspacePermission, isAccessSnapshotError, isPlatformOwner, managedDashes, parseAccessSnapshot, permissionsFor } from '../chunk-RR5DP3QT.js';
+import '../chunk-RVKIDFXM.js';

package/dist/access/next.d.ts

@@ -1,11 +1,10 @@
-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";
+import { R as Resolvable } from '../internal-rnEuAE21.js';
+import { AccessSnapshot, PermissionCheckOptions } from './index.js';
+export { AccessEntry, AccessErrorCode, AccessScopeType, AccessSnapshotError, DASH_PERMISSIONS, DASH_ROLES, DEFAULT_ACCESS_ENDPOINT_PATH, DashPermissionKey, DashRole, FetchAccessSnapshotOptions, LEADBROKER_PERMISSIONS, LeadBrokerPermissionKey, PLATFORM_PERMISSIONS, PermissionKey, PlatformPermissionKey, WORKSPACE_PERMISSIONS, WORKSPACE_ROLES, WorkspacePermissionKey, WorkspaceRole, appScopes, dashRole, emptySnapshot, entryCoversApp, fetchAccessSnapshot, hasAllPermissions, hasAnyPermission, hasPermission, hasWorkspacePermission, isAccessSnapshotError, isPlatformOwner, managedDashes, parseAccessSnapshot, permissionsFor } from './index.js';
+
 /** Default cache tag for one subject's snapshot: `access:<subjectId>`. */
-export declare function accessCacheTag(subjectId: string): string;
-export interface CreateAccessLoaderOptions {
+declare function accessCacheTag(subjectId: string): string;
+interface CreateAccessLoaderOptions {
     apiUrl: Resolvable;
     endpointPath?: string;
     /** Resolve the current request's bearer token (usually from the httpOnly session cookie). null = no session. */
@@ -32,11 +31,11 @@ export interface CreateAccessLoaderOptions {
     }) => Promise<AccessSnapshot>;
     cacheTag?: (subjectId: string) => string;
 }
-export interface RequireAccessOptions extends PermissionCheckOptions {
+interface RequireAccessOptions extends PermissionCheckOptions {
     /** "all" (default) requires every key; "any" requires at least one. */
     mode?: "all" | "any";
 }
-export interface AccessLoader {
+interface AccessLoader {
     /** Snapshot for the current request. Throws AccessSnapshotError (never interrupts). */
     getAccess(): Promise<AccessSnapshot>;
     /** Snapshot or null when unauthenticated. Other failures still throw. */
@@ -48,4 +47,6 @@ export interface AccessLoader {
     invalidateAccess(subjectId: string): void;
     cacheTag(subjectId: string): string;
 }
-export declare function createAccessLoader(options: CreateAccessLoaderOptions): AccessLoader;
+declare function createAccessLoader(options: CreateAccessLoaderOptions): AccessLoader;
+
+export { type AccessLoader, AccessSnapshot, type CreateAccessLoaderOptions, PermissionCheckOptions, type RequireAccessOptions, accessCacheTag, createAccessLoader };

package/dist/access/next.js

@@ -1,86 +1,75 @@
-// 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}`;
+import { decodeTokenPayload } from '../chunk-FBC2NUH7.js';
+import { AccessSnapshotError, fetchAccessSnapshot, isAccessSnapshotError, hasAnyPermission, hasAllPermissions, hasWorkspacePermission } from '../chunk-RR5DP3QT.js';
+export { AccessSnapshotError, DASH_PERMISSIONS, DASH_ROLES, DEFAULT_ACCESS_ENDPOINT_PATH, LEADBROKER_PERMISSIONS, PLATFORM_PERMISSIONS, WORKSPACE_PERMISSIONS, WORKSPACE_ROLES, appScopes, dashRole, emptySnapshot, entryCoversApp, fetchAccessSnapshot, hasAllPermissions, hasAnyPermission, hasPermission, hasWorkspacePermission, isAccessSnapshotError, isPlatformOwner, managedDashes, parseAccessSnapshot, permissionsFor } from '../chunk-RR5DP3QT.js';
+import { resolveValue } from '../chunk-RVKIDFXM.js';
+import 'server-only';
+import { cache } from 'react';
+import { forbidden, unauthorized } from 'next/navigation';
+import { updateTag } from 'next/cache';
+
+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;
-        }
+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 });
     }
-    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;
+    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;
     }
-    function invalidateAccess(subjectId) {
-        updateTag(tag(subjectId));
+  }
+  async function loadOrInterrupt() {
+    try {
+      return await load();
+    } catch (error) {
+      if (isAccessSnapshotError(error, "unauthenticated")) unauthorized();
+      if (isAccessSnapshotError(error, "forbidden")) forbidden();
+      throw error;
     }
-    return { getAccess, getAccessOrNull, requireAccess, requireWorkspaceAccess, invalidateAccess, cacheTag: tag };
+  }
+  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 };
 }
+
+export { accessCacheTag, createAccessLoader };

package/dist/access/react.d.ts

@@ -1,19 +1,64 @@
-import { type ReactNode } from "react";
-import { type PermissionCheckOptions } from "./predicates.js";
-import { type AccessSnapshot } from "./snapshot.js";
-export interface AccessProviderProps {
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/** Scope a permission entry applies to. Mirrors c1m-server authz.Scope*. */
+type AccessScopeType = "platform" | "saas_app" | "workspace";
+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.
+ */
+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>;
+}
+
+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;
+}
+
+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;
+declare function AccessProvider({ snapshot, children }: AccessProviderProps): react.JSX.Element;
+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 {
+declare function useAccessOrEmpty(): AccessSnapshot;
+declare function useCan(): (key: string, opts?: PermissionCheckOptions) => boolean;
+declare function useCanWorkspace(workspaceId: string): (key: string) => boolean;
+declare function useIsPlatformOwner(): boolean;
+interface CanProps extends PermissionCheckOptions {
     /** One key, or several — all must hold unless `mode="any"`. */
     permission: string | readonly string[];
     mode?: "all" | "any";
@@ -25,4 +70,6 @@ export interface CanProps extends PermissionCheckOptions {
     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;
+declare function Can({ permission, mode, workspaceId, saasApp, not, fallback, children }: CanProps): react.JSX.Element;
+
+export { AccessProvider, type AccessProviderProps, Can, type CanProps, useAccess, useAccessOrEmpty, useCan, useCanWorkspace, useIsPlatformOwner };

package/dist/access/react.js

@@ -1,40 +1,87 @@
 "use client";
-import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+
+// src/access/react.tsx
 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 });
+
+// src/access/predicates.ts
+function entryCoversApp(entry, saasApp) {
+  switch (entry.scope_type) {
+    case "platform":
+      return true;
+    case "saas_app":
+      if (saasApp === void 0) return true;
+      return entry.scope_id === "*" || entry.scope_id.toLowerCase() === saasApp.toLowerCase();
+    default:
+      return false;
+  }
 }
+function hasPermission(snapshot, key, opts = {}) {
+  if (!snapshot.active) return false;
+  return snapshot.permissions.some((entry) => entry.key === key && entryCoversApp(entry, opts.saasApp));
+}
+function hasWorkspacePermission(snapshot, workspaceId, key) {
+  if (!snapshot.active) return false;
+  if (snapshot.is_owner) return true;
+  return (snapshot.workspace_permissions[workspaceId] ?? []).includes(key);
+}
+function isPlatformOwner(snapshot) {
+  return snapshot.active && snapshot.is_owner;
+}
+
+// src/access/snapshot.ts
+function emptySnapshot(subjectId = "") {
+  return {
+    subject_id: subjectId,
+    access_version: 0,
+    is_owner: false,
+    active: false,
+    platform_role: "",
+    permissions: [],
+    dash_roles: {},
+    workspace_permissions: {},
+    workspace_roles: {}
+  };
+}
+
+// src/access/react.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+var AccessContext = createContext(null);
+function AccessProvider({ snapshot, children }) {
+  const value = useMemo(() => snapshot, [snapshot]);
+  return /* @__PURE__ */ jsx(AccessContext.Provider, { value, children });
+}
+function useAccess() {
+  const snapshot = useContext(AccessContext);
+  if (!snapshot) throw new Error("useAccess must be used inside <AccessProvider>");
+  return snapshot;
+}
+function useAccessOrEmpty() {
+  return useContext(AccessContext) ?? emptySnapshot();
+}
+function useCan() {
+  const snapshot = useAccess();
+  return useMemo(() => (key, opts) => hasPermission(snapshot, key, opts), [snapshot]);
+}
+function useCanWorkspace(workspaceId) {
+  const snapshot = useAccess();
+  return useMemo(() => (key) => hasWorkspacePermission(snapshot, workspaceId, key), [snapshot, workspaceId]);
+}
+function useIsPlatformOwner() {
+  return isPlatformOwner(useAccess());
+}
+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 !== void 0 ? hasWorkspacePermission(snapshot, workspaceId, key) : hasPermission(snapshot, key, { saasApp });
+  const allowed = mode === "any" ? keys.some(check) : keys.every(check);
+  return /* @__PURE__ */ jsx(Fragment, { children: allowed !== not ? children : fallback });
+}
+export {
+  AccessProvider,
+  Can,
+  useAccess,
+  useAccessOrEmpty,
+  useCan,
+  useCanWorkspace,
+  useIsPlatformOwner
+};