@c1m-public/platform-auth 0.2.0 → 0.4.0

package/dist/access/snapshot.d.ts

@@ -0,0 +1,31 @@
+/** 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[];
+    /** 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,80 @@
+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: [],
+        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, 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 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,
+        workspace_permissions: wsPerms,
+        workspace_roles: wsRoles,
+    };
+}

package/dist/cookies.d.ts

@@ -1,8 +1,3 @@
-/**
- * Minimal, dependency-free cookie helpers over the Web `Request` / `Response`
- * types so route handlers stay framework-neutral (Next.js route handlers
- * accept and return exactly these).
- */
 export interface CookieOptions {
     httpOnly?: boolean;
     secure?: boolean;

package/dist/cookies.js

@@ -1,8 +1,4 @@
-/**
- * Minimal, dependency-free cookie helpers over the Web `Request` / `Response`
- * types so route handlers stay framework-neutral (Next.js route handlers
- * accept and return exactly these).
- */
+// Dependency-free cookie helpers over Web Request/Response (what Next route handlers use).
 export function readCookie(request, name) {
     const header = request.headers.get("cookie");
     if (!header)
@@ -30,7 +26,6 @@ export function serializeCookie(name, value, options = {}) {
         parts.push(`Max-Age=${Math.max(0, Math.floor(options.maxAge))}`);
     if (options.httpOnly ?? true)
         parts.push("HttpOnly");
-    // `__Host-` cookies are only valid with Secure and no Domain.
     if (options.secure ?? name.startsWith("__Host-"))
         parts.push("Secure");
     const sameSite = options.sameSite ?? "lax";

package/dist/device-cookie.d.ts

@@ -1,8 +1,6 @@
 /**
- * A stable per-browser identity that c1m-server hashes into the session's
- * device record (`X-Client-Device-ID`). Session creation refuses requests
- * without it, so every sign-in and handoff exchange must send it. It carries
- * no authority: it is informational device recognition only.
+ * Per-browser identity sent as `X-Client-Device-ID`; c1m-server refuses to
+ * create a session without it. Informational only, no authority.
  */
 export interface DeviceIdentity {
     value: string;
@@ -10,9 +8,7 @@ export interface DeviceIdentity {
 }
 export interface DeviceIdentityConfig {
     cookieName: string;
-    /** Defaults to true; set false only for plain-http local development. */
     secure?: boolean;
-    /** Defaults to one year. */
     maxAgeSeconds?: number;
 }
 export declare function createDeviceIdentity(config: DeviceIdentityConfig): {

package/dist/forwarding.d.ts

@@ -1,9 +1,2 @@
-/**
- * Copies the browser's client identity (IP, geo, user agent, host, proto) from
- * an incoming BFF request onto an outgoing backend request. c1m-server reads
- * these `X-Client-*` / `X-Forwarded-*` headers for session device records,
- * rate limits, and audit — never for authentication.
- */
 export declare function applyForwardedClientHeaders(incoming: Headers, headers?: Headers): Headers;
-/** Builds outgoing headers for a backend call made on behalf of `request`. */
 export declare function forwardedRequestHeaders(request: Request, init?: HeadersInit): Headers;

package/dist/forwarding.js

@@ -1,9 +1,5 @@
-/**
- * Copies the browser's client identity (IP, geo, user agent, host, proto) from
- * an incoming BFF request onto an outgoing backend request. c1m-server reads
- * these `X-Client-*` / `X-Forwarded-*` headers for session device records,
- * rate limits, and audit — never for authentication.
- */
+// Copies client identity (IP, geo, UA, host, proto) from an incoming BFF request onto a backend
+// request as X-Client-* / X-Forwarded-*. Used for device records, rate limits, audit — never auth.
 export function applyForwardedClientHeaders(incoming, headers = new Headers()) {
     const forwardedFor = incoming.get("x-forwarded-for");
     const realIp = incoming.get("x-real-ip") ?? forwardedFor?.split(",")[0]?.trim();
@@ -31,7 +27,6 @@ export function applyForwardedClientHeaders(incoming, headers = new Headers()) {
         headers.set("X-Client-User-Agent", userAgent);
     return headers;
 }
-/** Builds outgoing headers for a backend call made on behalf of `request`. */
 export function forwardedRequestHeaders(request, init) {
     return applyForwardedClientHeaders(request.headers, new Headers(init));
 }

package/dist/handoff-errors.d.ts

@@ -1,9 +1,13 @@
-/**
- * The one error vocabulary for the first-party session handoff. Backend codes
- * (c1m-server `mapHandoffError`) and BFF-side codes share this map so every
- * surface renders the same specific message instead of a generic banner.
- */
 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

@@ -1,8 +1,4 @@
-/**
- * The one error vocabulary for the first-party session handoff. Backend codes
- * (c1m-server `mapHandoffError`) and BFF-side codes share this map so every
- * surface renders the same specific message instead of a generic banner.
- */
+// One error vocabulary for the handoff: backend codes (c1m-server mapHandoffError) + BFF codes.
 export const HANDOFF_ERROR_MESSAGES = {
     // backend — handoff broker
     handoff_unknown_app: "That application is not registered for sign-in handoff.",
@@ -27,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;
@@ -35,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,41 +1,24 @@
 import type { DeviceIdentityStore } from "./device-cookie.js";
+import { type Resolvable } from "./internal.js";
 import { type AuthResponse } from "./token.js";
-/** Path a source exposes to start a handoff to `app` (relative to the source origin). */
 export declare function sourceStartPath(app: string): string;
-/** Backend routes for a registered application key. */
 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 {
-    /** Registered application key (`docs`). */
     app: string;
-    /** Backend origin, e.g. https://api.example.com (no /api/v1). */
     apiUrl: Resolvable;
-    /** Audience the exchange must mint; the callback refuses anything else. */
     audience: string;
-    /** X-Client-Type sent to the backend. */
     clientType: string;
-    /** Source key → source origin. The `?source=` query on start selects one. */
     sources: Record<string, Resolvable>;
-    /** Source used when `?source=` is absent. */
     defaultSource: string;
-    /** Prefix for the temporary handoff cookies (`__Host-<prefix>_handoff_*`). */
     cookiePrefix: string;
-    /** Target's login page (receives `?error=` on failure). */
     loginPath: string;
-    /** Where to land when no `from` was supplied. */
     defaultReturnPath: string;
-    /** Device identity cookie store (X-Client-Device-ID). */
     device: DeviceIdentityStore;
-    /**
-     * Establish the target session on the outgoing redirect. Return the response
-     * (with cookies applied) — or return nothing if cookies were written through
-     * a framework store such as `next/headers`.
-     */
+    /** 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;
-    /** Set false only for plain-http local development (drops the `__Host-` prefix). */
     secureCookies?: boolean;
     fetchTimeoutMs?: number;
 }
@@ -45,38 +28,28 @@ export declare function createHandoffTarget(config: HandoffTargetConfig): {
         readonly verifier: `${string}verifier`;
         readonly from: `${string}from`;
     };
-    /** GET `?source=<key>&from=<path>` — begin a handoff by bouncing to the source. */
+    /** GET `?source=&from=` */
     start(request: Request): Promise<Response>;
-    /** GET `?code=&state=` — exchange the one-time code and establish the session. */
+    /** GET `?code=&state=` */
     callback(request: Request): Promise<Response>;
 };
 export type HandoffTarget = ReturnType<typeof createHandoffTarget>;
 export interface HandoffSourceTarget {
-    /** Exact target origin; must equal the origin of the backend's redirect_url. */
     origin: Resolvable;
-    /** Registered callback path on the target. */
     callbackPath?: string;
-    /** Target login page for error redirects. */
     loginPath?: string;
 }
 export interface HandoffSourceConfig {
     apiUrl: Resolvable;
     clientType: string;
-    /** Registered application key → target. */
     targets: Record<string, HandoffSourceTarget>;
-    /**
-     * The source's current access token, or null when signed out. Implementations
-     * should refresh an expiring token before returning it — the backend needs a
-     * live bearer to mint the code.
-     */
+    /** Live bearer or null when signed out; refresh an expiring token before returning it. */
     getAccessToken: (request: Request) => Promise<string | null> | string | null;
-    /** Source login page; a signed-out start bounces here with `?from=` set to resume. */
     loginPath: string;
     fetchTimeoutMs?: number;
 }
 export declare function createHandoffSource(config: HandoffSourceConfig): {
-    /** GET `/api/auth/handoffs/{app}/start?code_challenge=&state=`. */
+    /** GET `/api/auth/handoffs/{app}/start?code_challenge=&state=` */
     start(request: Request, app: string): Promise<Response>;
 };
 export type HandoffSource = ReturnType<typeof createHandoffSource>;
-export {};

package/dist/handoff.js

@@ -1,33 +1,19 @@
 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";
 /**
- * First-party session handoff — the browser-side halves of c1m-server's
- * `/api/v1/platform/auth/handoffs/{app}/start|exchange` broker.
- *
- *   target.start    (target origin)  mints PKCE verifier + state into
- *                                     host-local cookies, redirects to the
- *                                     source's start route with the S256
- *                                     challenge.
- *   source.start    (source origin)  requires the source session, asks the
- *                                     backend for a one-time code, redirects to
- *                                     the target's registered callback.
- *   target.callback (target origin)  verifies state, exchanges code+verifier,
- *                                     establishes the target session in its own
- *                                     cookies, redirects to the return path.
- *
- * Tokens never appear in URLs; every failure is a redirect to a login page
- * with a code from HANDOFF_ERROR_MESSAGES.
+ * Browser halves of c1m-server's `/api/v1/platform/auth/handoffs/{app}` broker.
+ * target.start → source.start → target.callback. PKCE S256 + state, host-local
+ * cookies, no tokens in URLs; failures redirect to a login page with a code
+ * from HANDOFF_ERROR_MESSAGES.
  */
 const HANDOFF_COOKIE_TTL_SECONDS = 120;
 const CHALLENGE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
-const DEFAULT_TIMEOUT_MS = 10_000;
-/** Path a source exposes to start a handoff to `app` (relative to the source origin). */
 export function sourceStartPath(app) {
     return `/api/auth/handoffs/${encodeURIComponent(app)}/start`;
 }
-/** Backend routes for a registered application key. */
 export function brokerPaths(app) {
     const key = encodeURIComponent(app);
     return {
@@ -35,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;
@@ -70,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 });
@@ -94,14 +69,14 @@ export function createHandoffTarget(config) {
     const fail = (origin, code) => clearHandoffCookies(loginErrorRedirect(origin, config.loginPath, code));
     return {
         cookies,
-        /** GET `?source=<key>&from=<path>` — begin a handoff by bouncing to the source. */
+        /** GET `?source=&from=` */
         async start(request) {
             const url = new URL(request.url);
             const sourceKey = url.searchParams.get("source")?.trim() || config.defaultSource;
             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);
@@ -117,7 +92,7 @@ export function createHandoffTarget(config) {
                 setCookie(response, cookies.from, from, cookieOptions);
             return response;
         },
-        /** GET `?code=&state=` — exchange the one-time code and establish the session. */
+        /** GET `?code=&state=` */
         async callback(request) {
             const url = new URL(request.url);
             const code = url.searchParams.get("code") ?? "";
@@ -135,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;
@@ -158,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=`. */
+        /** 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" } });
@@ -189,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/index.d.ts

@@ -6,3 +6,4 @@ export * from "./device-cookie.js";
 export * from "./handoff-errors.js";
 export * from "./handoff.js";
 export * from "./session-refresh.js";
+export * from "./session-gate.js";

package/dist/index.js

@@ -6,3 +6,4 @@ export * from "./device-cookie.js";
 export * from "./handoff-errors.js";
 export * from "./handoff.js";
 export * from "./session-refresh.js";
+export * from "./session-gate.js";

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/next.js

@@ -1,5 +1,3 @@
-// Server-only entry for Next.js route handlers and server components. The root
-// entry is framework-neutral (Web Request/Response); this one only adds the
-// bundler guard so session helpers cannot leak into client bundles.
+// Server-only entry: root API plus the bundler guard against client bundles.
 import "server-only";
 export * from "./index.js";

package/dist/return-path.d.ts

@@ -1,16 +1,6 @@
 /**
- * Strict same-origin return path sanitiser (the hardened core shared by every
- * MML surface). Accepts only absolute paths that survive a round-trip through
- * URL parsing against a known-safe origin; returns `null` on any rejection.
- *
- * A value is accepted only when it:
- *   1. is non-empty after trimming
- *   2. starts with `/`
- *   3. does NOT start with `//` (protocol-relative bypass) or contain `://`
- *   4. contains no encoded path separators or control characters
- *   5. round-trips to the exact same string (catches `\`, hostname components,
- *      and other parser-normalised trickery)
- *
- * The accepted value is returned verbatim — query and hash are preserved.
+ * 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.
  */
 export declare function safeInternalPath(raw: string | null | undefined): string | null;

package/dist/return-path.js

@@ -1,17 +1,7 @@
 /**
- * Strict same-origin return path sanitiser (the hardened core shared by every
- * MML surface). Accepts only absolute paths that survive a round-trip through
- * URL parsing against a known-safe origin; returns `null` on any rejection.
- *
- * A value is accepted only when it:
- *   1. is non-empty after trimming
- *   2. starts with `/`
- *   3. does NOT start with `//` (protocol-relative bypass) or contain `://`
- *   4. contains no encoded path separators or control characters
- *   5. round-trips to the exact same string (catches `\`, hostname components,
- *      and other parser-normalised trickery)
- *
- * The accepted value is returned verbatim — query and hash are preserved.
+ * 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.
  */
 export function safeInternalPath(raw) {
     if (raw == null)

package/dist/session-gate.d.ts

@@ -0,0 +1,26 @@
+import type { RefreshedSession, SessionRefresher } from "./session-refresh.js";
+export declare function hasSessionShape(token: string | undefined | null): boolean;
+export type SessionGateDecision = {
+    kind: "pass";
+    refreshed?: RefreshedSession;
+} | {
+    kind: "redirect_home";
+    refreshed?: RefreshedSession;
+} | {
+    kind: "anonymous_public";
+} | {
+    kind: "unauthorized_api";
+} | {
+    kind: "redirect_login";
+};
+export interface SessionGateInput {
+    accessToken?: string | null;
+    refreshToken?: string | null;
+    audience: string;
+    refresher: Pick<SessionRefresher, "refresh">;
+    isPublic: boolean;
+    isLoginPath: boolean;
+    isApiPath: boolean;
+    expiringSoonBufferSeconds?: number;
+}
+export declare function evaluateSessionGate(input: SessionGateInput): Promise<SessionGateDecision>;