@c1m-public/platform-auth 0.2.0 → 0.3.1

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,8 +1,3 @@
-/**
- * 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 function handoffErrorMessage(code: string | null | undefined): string;

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.",

package/dist/handoff.d.ts

@@ -1,41 +1,24 @@
 import type { DeviceIdentityStore } from "./device-cookie.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,37 +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>;

package/dist/handoff.js

@@ -3,31 +3,17 @@ import { forwardedRequestHeaders } from "./forwarding.js";
 import { safeInternalPath } from "./return-path.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 {
@@ -94,7 +80,7 @@ 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;
@@ -117,7 +103,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") ?? "";
@@ -160,7 +146,7 @@ const DEFAULT_TARGET_LOGIN = "/login";
 export function createHandoffSource(config) {
     const timeout = config.fetchTimeoutMs ?? DEFAULT_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)

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/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>;

package/dist/session-gate.js

@@ -0,0 +1,33 @@
+import { decodeTokenPayload, hasTokenAudience, isTokenExpired, isTokenExpiringSoon } from "./token.js";
+// Pure decision for a BFF proxy/middleware: given the request's session cookies and path
+// class, decide pass / bounce / clear. The proxy owns response construction.
+export function hasSessionShape(token) {
+    if (!token)
+        return false;
+    const payload = decodeTokenPayload(token);
+    return Boolean(payload?.user_id || payload?.actor_id || payload?.customer_id || payload?.sub);
+}
+export async function evaluateSessionGate(input) {
+    const { accessToken, refreshToken, audience, refresher, isPublic, isLoginPath, isApiPath } = input;
+    const live = !!accessToken && hasSessionShape(accessToken) && hasTokenAudience(accessToken, audience) && !isTokenExpired(accessToken);
+    if (live) {
+        if (isPublic && isLoginPath)
+            return { kind: "redirect_home" };
+        if (refreshToken && isTokenExpiringSoon(accessToken, input.expiringSoonBufferSeconds)) {
+            const refreshed = await refresher.refresh(refreshToken);
+            if (refreshed)
+                return { kind: "pass", refreshed };
+        }
+        return { kind: "pass" };
+    }
+    if (refreshToken) {
+        const refreshed = await refresher.refresh(refreshToken);
+        if (refreshed)
+            return isPublic ? { kind: "redirect_home", refreshed } : { kind: "pass", refreshed };
+    }
+    if (isPublic)
+        return { kind: "anonymous_public" };
+    if (isApiPath)
+        return { kind: "unauthorized_api" };
+    return { kind: "redirect_login" };
+}

package/dist/session-refresh.d.ts

@@ -1,33 +1,23 @@
 /**
- * Coalesced refresh-token exchange for a BFF proxy/middleware. Concurrent
- * requests carrying the same refresh token share one backend call for a short
- * window, so a burst of parallel page/API requests after expiry cannot rotate
- * the family more than once. Best-effort inside a single process only — the
- * backend's reuse detection remains the correctness guarantee.
+ * 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.
  */
 export interface RefreshedSession {
     accessToken: string;
     refreshToken?: string;
 }
 export interface SessionRefresherConfig {
-    /** Backend origin (no /api/v1). */
     apiUrl: string | (() => string);
-    /** Refresh endpoint path, e.g. /api/v1/platform/auth/refresh. */
     refreshPath: string;
-    /** X-Client-Type sent to the backend. */
     clientType: string;
-    /** Audience the refreshed access token must carry; anything else is rejected. */
     audience: string;
-    /** How long a completed refresh keeps answering for the same token. Default 5 s. */
     singleflightTtlMs?: number;
-    /** Bound on remembered in-flight/recent refreshes. Default 1000. */
     maxSingleflights?: number;
     fetchTimeoutMs?: number;
 }
 export declare function createSessionRefresher(config: SessionRefresherConfig): {
-    /** Exchange a refresh token; identical concurrent calls share one backend request. */
     refresh(refreshToken: string): Promise<RefreshedSession | null>;
-    /** Test/inspection hook: number of remembered refreshes. */
     size(): number;
 };
 export type SessionRefresher = ReturnType<typeof createSessionRefresher>;

package/dist/session-refresh.js

@@ -46,7 +46,6 @@ export function createSessionRefresher(config) {
         }
     }
     return {
-        /** Exchange a refresh token; identical concurrent calls share one backend request. */
         refresh(refreshToken) {
             const now = Date.now();
             prune(now);
@@ -61,7 +60,6 @@ export function createSessionRefresher(config) {
             inflight.set(refreshToken, { expiresAt: now + ttl, promise });
             return promise;
         },
-        /** Test/inspection hook: number of remembered refreshes. */
         size() {
             return inflight.size;
         },

package/dist/token.d.ts

@@ -1,8 +1,3 @@
-/**
- * Read-only access-token payload helpers. Decoding is not verification: these
- * helpers exist so a BFF can route on audience/expiry before calling the
- * backend, which remains the security boundary.
- */
 export interface SessionUser {
     id: string;
     email: string;
@@ -25,6 +20,7 @@ export type TokenPayload = Record<string, unknown> & {
     exp?: number;
     iat?: number;
     actor_id?: string;
+    effective_user_id?: string;
     customer_id?: string;
     user_id?: string;
     aud?: string | string[];

package/dist/token.js

@@ -1,8 +1,4 @@
-/**
- * Read-only access-token payload helpers. Decoding is not verification: these
- * helpers exist so a BFF can route on audience/expiry before calling the
- * backend, which remains the security boundary.
- */
+// Access-token payload reads for BFF routing. Decoding is not verification; the backend is the boundary.
 function readStringClaim(value, fallback = "") {
     return typeof value === "string" ? value : fallback;
 }
@@ -13,7 +9,6 @@ export function decodeBase64Url(input) {
     const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
     const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), "=");
     try {
-        // Node >= 20 and every browser expose atob globally.
         const binary = globalThis.atob(padded);
         const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
         return new TextDecoder().decode(bytes);
@@ -69,7 +64,9 @@ export function decodeDefaultSession(token) {
     const decoded = decodeTokenPayload(token);
     if (!decoded)
         return null;
-    const actorId = decoded.actor_id ||
+    // effective_user_id wins: a support-session token re-identifies as the impersonated user.
+    const actorId = decoded.effective_user_id ||
+        decoded.actor_id ||
         decoded.customer_id ||
         decoded.user_id ||
         (typeof decoded.sub === "string" ? decoded.sub : undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c1m-public/platform-auth",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",
@@ -12,32 +12,12 @@
   "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"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "server-only": "0.0.1"
-  },
-  "devDependencies": {
-    "typescript": "5.9.3",
-    "vitest": "^4.1.4"
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./next": { "types": "./dist/next.d.ts", "default": "./dist/next.js" }
   },
+  "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",
@@ -45,5 +25,7 @@
     "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" }
+}