@c1m-public/platform-auth 0.9.0 → 0.9.1

package/dist/index-CbsCWtku.d.ts

@@ -0,0 +1,154 @@
+/** 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;
+
+/** Onboarding pipeline stages, in funnel order. Labels and copy stay with the app; the strings are the backend's. */
+declare const PIPELINE_STAGES: readonly ["created", "awaiting_payment", "provisioning", "attention", "active"];
+type PipelineStage = (typeof PIPELINE_STAGES)[number];
+declare function isPipelineStage(value: unknown): value is PipelineStage;
+
+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[];
+
+/** A value that may be fixed or resolved per call (env read at request time). */
+type Resolvable<T = string> = T | (() => T);
+
+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 AccessSnapshot as A, isAccessSnapshotError as B, isPipelineStage as C, DASH_PERMISSIONS as D, isPlatformOwner as E, type FetchAccessSnapshotOptions as F, managedDashes as G, parseAccessSnapshot as H, permissionsFor as I, LEADBROKER_PERMISSIONS as L, type PermissionCheckOptions as P, type Resolvable as R, WORKSPACE_PERMISSIONS as W, type AccessEntry as a, type AccessErrorCode as b, type AccessScopeType as c, AccessSnapshotError as d, DASH_ROLES as e, DEFAULT_ACCESS_ENDPOINT_PATH as f, type DashPermissionKey as g, type DashRole as h, type LeadBrokerPermissionKey as i, PIPELINE_STAGES as j, PLATFORM_PERMISSIONS as k, type PermissionKey as l, type PipelineStage as m, type PlatformPermissionKey as n, WORKSPACE_ROLES as o, type WorkspacePermissionKey as p, type WorkspaceRole as q, appScopes as r, dashRole as s, emptySnapshot as t, entryCoversApp as u, fetchAccessSnapshot as v, hasAllPermissions as w, hasAnyPermission as x, hasPermission as y, hasWorkspacePermission as z };

package/dist/index.d.ts

@@ -1,231 +1,2 @@
+export { a as AUTH_ERROR_MESSAGES, b as AuthResponse, C as CookieOptions, D as DeviceIdentity, c as DeviceIdentityConfig, d as DeviceIdentityStore, H as HANDOFF_ERROR_FALLBACK, e as HANDOFF_ERROR_MESSAGES, f as HandoffSource, g as HandoffSourceConfig, h as HandoffSourceTarget, i as HandoffTarget, j as HandoffTargetConfig, k as RefreshedSession, l as SSO_ERROR_MESSAGES, S as SessionData, m as SessionGateDecision, n as SessionGateInput, o as SessionRefresher, p as SessionRefresherConfig, q as SessionUser, T as TokenPayload, r as authErrorMessage, s as brokerPaths, t as createDeviceIdentity, u as createHandoffSource, v as createHandoffTarget, w as createSessionRefresher, x as decodeBase64Url, y as decodeDefaultSession, z as decodeTokenPayload, B as deleteCookie, E as evaluateSessionGate, F as handoffErrorMessage, G as hasSessionShape, I as hasTokenAudience, J as isAuthErrorCode, K as isHandoffErrorCode, L as isTokenExpired, M as isTokenExpiringSoon, N as parseAuthResponse, O as parseRefreshEnvelope, P as readCookie, Q as safeInternalPath, U as serializeCookie, V as setCookie, W as sourceStartPath, X as tokenMaxAgeSeconds } from './index-BnchfjP_.js';
 export { applyForwardedClientHeaders, forwardedRequestHeaders } from '@c1m-public/transport';
-import { R as Resolvable, A as AsyncResolvable } from './internal-D6RafCm2.js';
-
-interface SessionUser {
-    id: string;
-    email: string;
-    name: string;
-    role: string;
-    is_active: boolean;
-    email_verified: boolean;
-    created_at: string;
-    last_login_at?: string;
-    has_passkey?: boolean;
-}
-interface SessionData {
-    user: SessionUser;
-    token: string;
-    exp: number;
-    iat: number;
-}
-type TokenPayload = Record<string, unknown> & {
-    sub?: string;
-    exp?: number;
-    iat?: number;
-    actor_id?: string;
-    effective_user_id?: string;
-    customer_id?: string;
-    user_id?: string;
-    aud?: string | string[];
-    email?: string;
-    name?: string;
-    role?: string;
-    is_active?: boolean;
-    email_verified?: boolean;
-    created_at?: string;
-    has_passkeys?: boolean;
-};
-declare function decodeBase64Url(input: string): string | null;
-declare function decodeTokenPayload(token: string): TokenPayload | null;
-declare function hasTokenAudience(token: string, requiredAudience: string): boolean;
-/** Cookie max-age clamped to the token's remaining lifetime. */
-declare function tokenMaxAgeSeconds(token: string, configuredMaxAge: number): number;
-declare function isTokenExpired(token: string): boolean;
-declare function isTokenExpiringSoon(token: string, bufferSeconds?: number): boolean;
-declare function decodeDefaultSession(token: string): SessionData | null;
-/** Backend auth response shape shared by verify-code, OIDC complete, and handoff exchange. */
-interface AuthResponse {
-    access_token: string;
-    refresh_token: string;
-    token_type: string;
-    expires_at: string;
-    user: Record<string, unknown>;
-}
-declare function parseAuthResponse(value: unknown): AuthResponse | null;
-
-/**
- * Strict same-origin return path: must start with `/`, not `//` or contain `://`,
- * no encoded slashes or control chars, and round-trip URL parsing unchanged.
- * Returns the value verbatim (query/hash kept) or null.
- */
-declare function safeInternalPath(raw: string | null | undefined): string | null;
-
-interface CookieOptions {
-    httpOnly?: boolean;
-    secure?: boolean;
-    sameSite?: "lax" | "strict" | "none";
-    path?: string;
-    maxAge?: number;
-}
-declare function readCookie(request: Request, name: string): string | null;
-declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
-declare function setCookie(response: Response, name: string, value: string, options?: CookieOptions): Response;
-declare function deleteCookie(response: Response, name: string, options?: Pick<CookieOptions, "path" | "secure">): Response;
-
-/**
- * Per-browser identity sent as `X-Client-Device-ID`; c1m-server refuses to
- * create a session without it. Informational only, no authority.
- */
-interface DeviceIdentity {
-    value: string;
-    created: boolean;
-}
-interface DeviceIdentityConfig {
-    cookieName: string;
-    secure?: boolean;
-    maxAgeSeconds?: number;
-}
-declare function createDeviceIdentity(config: DeviceIdentityConfig): {
-    read(request: Request): DeviceIdentity;
-    persist(response: Response, identity: DeviceIdentity): Response;
-};
-type DeviceIdentityStore = ReturnType<typeof createDeviceIdentity>;
-
-declare const HANDOFF_ERROR_MESSAGES: Record<string, string>;
-declare const HANDOFF_ERROR_FALLBACK = "Sign-in failed \u2014 please try again.";
-declare const SSO_ERROR_MESSAGES: Record<string, string>;
-/** Every sign-in failure code this package knows: handoff, admission, and SSO. */
-declare const AUTH_ERROR_MESSAGES: Record<string, string>;
-declare function handoffErrorMessage(code: string | null | undefined): string;
-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.
- */
-declare function authErrorMessage(code: string | null | undefined, overrides?: Record<string, string>): string;
-declare function isAuthErrorCode(code: string | null | undefined, overrides?: Record<string, string>): boolean;
-
-declare function sourceStartPath(app: string): string;
-declare function brokerPaths(app: string): {
-    readonly start: `/api/v1/platform/auth/handoffs/${string}/start`;
-    readonly exchange: `/api/v1/platform/auth/handoffs/${string}/exchange`;
-};
-interface HandoffTargetConfig {
-    app: string;
-    apiUrl: Resolvable;
-    audience: string;
-    clientType: string;
-    sources: Record<string, Resolvable>;
-    defaultSource: string;
-    cookiePrefix: string;
-    loginPath: string;
-    defaultReturnPath: string;
-    device: DeviceIdentityStore;
-    /** Write session cookies onto `response` (or return void if written via a framework store). */
-    establishSession: (session: AuthResponse, response: Response, request: Request) => Promise<Response | void> | Response | void;
-    secureCookies?: boolean;
-    timeoutMs?: number;
-    /** @deprecated use `timeoutMs`. */
-    fetchTimeoutMs?: number;
-    fetch?: typeof fetch;
-}
-declare function createHandoffTarget(config: HandoffTargetConfig): {
-    cookies: {
-        readonly state: `${string}state`;
-        readonly verifier: `${string}verifier`;
-        readonly from: `${string}from`;
-    };
-    /** GET `?source=&from=` */
-    start(request: Request): Promise<Response>;
-    /** GET `?code=&state=` */
-    callback(request: Request): Promise<Response>;
-};
-type HandoffTarget = ReturnType<typeof createHandoffTarget>;
-interface HandoffSourceTarget {
-    origin: Resolvable;
-    callbackPath?: string;
-    loginPath?: string;
-}
-interface HandoffSourceConfig {
-    apiUrl: Resolvable;
-    clientType: string;
-    targets: Record<string, HandoffSourceTarget>;
-    /** Live bearer or null when signed out; refresh an expiring token before returning it. */
-    getAccessToken: (request: Request) => Promise<string | null> | string | null;
-    loginPath: string;
-    timeoutMs?: number;
-    /** @deprecated use `timeoutMs`. */
-    fetchTimeoutMs?: number;
-    fetch?: typeof fetch;
-}
-declare function createHandoffSource(config: HandoffSourceConfig): {
-    /** GET `/api/auth/handoffs/{app}/start?code_challenge=&state=` */
-    start(request: Request, app: string): Promise<Response>;
-};
-type HandoffSource = ReturnType<typeof createHandoffSource>;
-
-/**
- * Coalesced refresh-token exchange for a BFF proxy: same refresh token within
- * a short window shares one backend call. Per-process best effort; backend
- * reuse detection is the correctness guarantee.
- */
-interface RefreshedSession {
-    accessToken: string;
-    refreshToken?: string;
-}
-interface SessionRefresherConfig {
-    /** Backend origin, no /api/v1. May resolve asynchronously (a tenant-scoped origin). */
-    apiUrl: AsyncResolvable<string>;
-    /** e.g. /api/v1/platform/auth/refresh; empty when `apiUrl` already resolves to the full URL. */
-    refreshPath: string;
-    /** Extra request headers, e.g. a service credential and its tenant selector. */
-    headers?: AsyncResolvable<HeadersInit | undefined>;
-    clientType: string;
-    audience: string;
-    singleflightTtlMs?: number;
-    maxSingleflights?: number;
-    timeoutMs?: number;
-    /** @deprecated use `timeoutMs`. */
-    fetchTimeoutMs?: number;
-    fetch?: typeof fetch;
-}
-/**
- * Two refresh envelopes exist: the platform one (flat, with token_type and
- * expires_at) and the end-user one (`{ data: { access_token, refresh_token? } }`,
- * where a rotated refresh token is optional). Both carry the access token the
- * same way; that is all a refresh needs.
- */
-declare function parseRefreshEnvelope(value: unknown): RefreshedSession | null;
-declare function createSessionRefresher(config: SessionRefresherConfig): {
-    refresh(refreshToken: string): Promise<RefreshedSession | null>;
-    size(): number;
-};
-type SessionRefresher = ReturnType<typeof createSessionRefresher>;
-
-declare function hasSessionShape(token: string | undefined | null): boolean;
-type SessionGateDecision = {
-    kind: "pass";
-    refreshed?: RefreshedSession;
-} | {
-    kind: "redirect_home";
-    refreshed?: RefreshedSession;
-} | {
-    kind: "anonymous_public";
-} | {
-    kind: "unauthorized_api";
-} | {
-    kind: "redirect_login";
-};
-interface SessionGateInput {
-    accessToken?: string | null;
-    refreshToken?: string | null;
-    audience: string;
-    refresher: Pick<SessionRefresher, "refresh">;
-    isPublic: boolean;
-    isLoginPath: boolean;
-    isApiPath: boolean;
-    expiringSoonBufferSeconds?: number;
-}
-declare function evaluateSessionGate(input: SessionGateInput): Promise<SessionGateDecision>;
-
-export { AUTH_ERROR_MESSAGES, type AuthResponse, type CookieOptions, type DeviceIdentity, type DeviceIdentityConfig, type DeviceIdentityStore, HANDOFF_ERROR_FALLBACK, HANDOFF_ERROR_MESSAGES, type HandoffSource, type HandoffSourceConfig, type HandoffSourceTarget, type HandoffTarget, type HandoffTargetConfig, type RefreshedSession, SSO_ERROR_MESSAGES, type SessionData, type SessionGateDecision, type SessionGateInput, type SessionRefresher, type SessionRefresherConfig, type SessionUser, type TokenPayload, authErrorMessage, brokerPaths, createDeviceIdentity, createHandoffSource, createHandoffTarget, createSessionRefresher, decodeBase64Url, decodeDefaultSession, decodeTokenPayload, deleteCookie, evaluateSessionGate, handoffErrorMessage, hasSessionShape, hasTokenAudience, isAuthErrorCode, isHandoffErrorCode, isTokenExpired, isTokenExpiringSoon, parseAuthResponse, parseRefreshEnvelope, readCookie, safeInternalPath, serializeCookie, setCookie, sourceStartPath, tokenMaxAgeSeconds };