@c1m-public/platform-auth 0.2.0

package/README.md

@@ -0,0 +1,28 @@
+# @c1m-public/platform-auth
+
+Framework-neutral session helpers for C1M platform surfaces (Platform Admin
+Center, Knowledge Library, SaaSDash BFFs):
+
+- `token` — decode access-token payloads (audience, expiry, default session).
+  Decoding is routing, not verification; the backend stays the boundary.
+- `safeInternalPath` — strict same-origin return-path sanitiser.
+- `forwardedRequestHeaders` — copy the browser's client identity onto a
+  backend call (`X-Client-*` / `X-Forwarded-*`).
+- `createDeviceIdentity` — the `X-Client-Device-ID` cookie the backend needs to
+  create a session.
+- `createHandoffTarget` / `createHandoffSource` — the browser halves of the
+  first-party session handoff (`/api/v1/platform/auth/handoffs/{app}`):
+  PKCE S256 + state, one-time code, host-local cookies, no tokens in URLs.
+- `HANDOFF_ERROR_MESSAGES` — the one error vocabulary for handoff failures.
+
+Import from `@c1m-public/platform-auth/next` inside Next.js server code.
+
+```ts
+// target: app/api/auth/platform-sso/[action]/route.ts
+const target = createHandoffTarget({ app: "docs", apiUrl: API_URL, audience: "platform_docs", ... });
+export const GET = (req: Request, ctx) => ctx.params.action === "callback" ? target.callback(req) : target.start(req);
+
+// source: app/api/auth/handoffs/[app]/start/route.ts
+const source = createHandoffSource({ apiUrl: API_URL, clientType: "nextjs-platform-admin", targets: { docs: { origin: DOCS_URL } }, getAccessToken, loginPath: "/login" });
+export const GET = (req: Request, ctx) => source.start(req, ctx.params.app);
+```

package/dist/cookies.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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;
+    sameSite?: "lax" | "strict" | "none";
+    path?: string;
+    maxAge?: number;
+}
+export declare function readCookie(request: Request, name: string): string | null;
+export declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+export declare function setCookie(response: Response, name: string, value: string, options?: CookieOptions): Response;
+export declare function deleteCookie(response: Response, name: string, options?: Pick<CookieOptions, "path" | "secure">): Response;

package/dist/cookies.js

@@ -0,0 +1,47 @@
+/**
+ * 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 function readCookie(request, name) {
+    const header = request.headers.get("cookie");
+    if (!header)
+        return null;
+    for (const part of header.split(";")) {
+        const separator = part.indexOf("=");
+        if (separator < 0)
+            continue;
+        if (part.slice(0, separator).trim() !== name)
+            continue;
+        const raw = part.slice(separator + 1).trim();
+        try {
+            return decodeURIComponent(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return null;
+}
+export function serializeCookie(name, value, options = {}) {
+    const parts = [`${name}=${encodeURIComponent(value)}`];
+    parts.push(`Path=${options.path ?? "/"}`);
+    if (options.maxAge !== undefined)
+        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";
+    parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
+    return parts.join("; ");
+}
+export function setCookie(response, name, value, options) {
+    response.headers.append("Set-Cookie", serializeCookie(name, value, options));
+    return response;
+}
+export function deleteCookie(response, name, options) {
+    response.headers.append("Set-Cookie", serializeCookie(name, "", { ...options, maxAge: 0 }));
+    return response;
+}

package/dist/device-cookie.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+export interface DeviceIdentity {
+    value: string;
+    created: boolean;
+}
+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): {
+    read(request: Request): DeviceIdentity;
+    persist(response: Response, identity: DeviceIdentity): Response;
+};
+export type DeviceIdentityStore = ReturnType<typeof createDeviceIdentity>;

package/dist/device-cookie.js

@@ -0,0 +1,22 @@
+import { readCookie, setCookie } from "./cookies.js";
+const DEFAULT_DEVICE_MAX_AGE = 365 * 24 * 60 * 60;
+export function createDeviceIdentity(config) {
+    const maxAge = config.maxAgeSeconds ?? DEFAULT_DEVICE_MAX_AGE;
+    return {
+        read(request) {
+            const existing = readCookie(request, config.cookieName)?.trim();
+            return existing ? { value: existing, created: false } : { value: crypto.randomUUID(), created: true };
+        },
+        persist(response, identity) {
+            if (!identity.created)
+                return response;
+            return setCookie(response, config.cookieName, identity.value, {
+                httpOnly: true,
+                secure: config.secure ?? true,
+                sameSite: "lax",
+                path: "/",
+                maxAge,
+            });
+        },
+    };
+}

package/dist/forwarding.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,37 @@
+/**
+ * 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 function applyForwardedClientHeaders(incoming, headers = new Headers()) {
+    const forwardedFor = incoming.get("x-forwarded-for");
+    const realIp = incoming.get("x-real-ip") ?? forwardedFor?.split(",")[0]?.trim();
+    if (realIp && !headers.has("X-Client-IP"))
+        headers.set("X-Client-IP", realIp);
+    if (realIp && !headers.has("X-Real-IP"))
+        headers.set("X-Real-IP", realIp);
+    if (forwardedFor && !headers.has("X-Forwarded-For"))
+        headers.set("X-Forwarded-For", forwardedFor);
+    const country = incoming.get("cf-ipcountry") ??
+        incoming.get("x-vercel-ip-country") ??
+        incoming.get("x-geo-country") ??
+        incoming.get("x-country-code");
+    if (country && country !== "XX" && !headers.has("X-Geo-Country")) {
+        headers.set("X-Geo-Country", country);
+    }
+    const host = incoming.get("host");
+    if (host && !headers.has("X-Forwarded-Host"))
+        headers.set("X-Forwarded-Host", host);
+    const proto = incoming.get("x-forwarded-proto");
+    if (proto && !headers.has("X-Forwarded-Proto"))
+        headers.set("X-Forwarded-Proto", proto);
+    const userAgent = incoming.get("user-agent");
+    if (userAgent && !headers.has("X-Client-User-Agent"))
+        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

@@ -0,0 +1,9 @@
+/**
+ * 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;
+export declare function isHandoffErrorCode(code: string | null | undefined): boolean;

package/dist/handoff-errors.js

@@ -0,0 +1,37 @@
+/**
+ * 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 const HANDOFF_ERROR_MESSAGES = {
+    // backend — handoff broker
+    handoff_unknown_app: "That application is not registered for sign-in handoff.",
+    handoff_not_configured: "Sign-in handoff is not configured for this application yet.",
+    handoff_source_not_allowed: "Your current session cannot open that application. Sign in there directly.",
+    handoff_invalid: "That sign-in handoff expired or was already used. Start again from where you came from.",
+    handoff_device_required: "The handoff could not identify this browser. Please try again.",
+    handoff_request_invalid: "The sign-in handoff request was malformed. Please try again.",
+    handoff_failed: "Sign-in handoff failed. Sign in with an email code instead.",
+    // backend — target admission (same codes the target's own login returns)
+    knowledge_library_access_required: "Your account has not been granted Knowledge Library access. Ask a platform admin to enable it.",
+    admin_center_access_required: "Your account has not been granted Admin Center access.",
+    platform_admin_surface_required: "Platform operator accounts sign in through the Platform Admin Center.",
+    account_disabled: "This account is disabled.",
+    // BFF — target callback
+    handoff_state_invalid: "Sign-in attempt expired — please try again.",
+    handoff_exchange_failed: "Sign-in could not be completed. Please try again.",
+    // BFF — source start
+    handoff_start_failed: "Could not start the sign-in handoff. Please try again.",
+    handoff_redirect_invalid: "The sign-in handoff returned an unexpected destination and was stopped.",
+    // BFF — surface bounces
+    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.";
+export function handoffErrorMessage(code) {
+    if (!code)
+        return HANDOFF_ERROR_FALLBACK;
+    return HANDOFF_ERROR_MESSAGES[code] ?? HANDOFF_ERROR_FALLBACK;
+}
+export function isHandoffErrorCode(code) {
+    return !!code && Object.prototype.hasOwnProperty.call(HANDOFF_ERROR_MESSAGES, code);
+}

package/dist/handoff.d.ts

@@ -0,0 +1,82 @@
+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`.
+     */
+    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;
+}
+export declare function createHandoffTarget(config: HandoffTargetConfig): {
+    cookies: {
+        readonly state: `${string}state`;
+        readonly verifier: `${string}verifier`;
+        readonly from: `${string}from`;
+    };
+    /** GET `?source=<key>&from=<path>` — begin a handoff by bouncing to the source. */
+    start(request: Request): Promise<Response>;
+    /** GET `?code=&state=` — exchange the one-time code and establish the session. */
+    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.
+     */
+    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=`. */
+    start(request: Request, app: string): Promise<Response>;
+};
+export type HandoffSource = ReturnType<typeof createHandoffSource>;
+export {};

package/dist/handoff.js

@@ -0,0 +1,220 @@
+import { deleteCookie, readCookie, setCookie } from "./cookies.js";
+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.
+ */
+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 {
+        start: `/api/v1/platform/auth/handoffs/${key}/start`,
+        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;
+    }
+    catch {
+        return null;
+    }
+}
+function base64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return globalThis.btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomToken(bytes) {
+    const raw = new Uint8Array(bytes);
+    crypto.getRandomValues(raw);
+    return base64Url(raw);
+}
+async function s256(verifier) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+    return base64Url(new Uint8Array(digest));
+}
+function validState(state) {
+    return state.length >= 16 && state.length <= 256 && !/[\r\n]/.test(state);
+}
+function redirect(url, status = 302) {
+    return new Response(null, { status, headers: { Location: url.toString(), "Cache-Control": "no-store" } });
+}
+function loginErrorRedirect(origin, loginPath, code) {
+    const target = new URL(loginPath, origin);
+    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 clearHandoffCookies = (response) => {
+        for (const name of Object.values(cookies))
+            deleteCookie(response, name, { path: "/", secure });
+        return response;
+    };
+    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. */
+        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));
+            if (!sourceOrigin)
+                return fail(url.origin, "handoff_not_configured");
+            const verifier = randomToken(48);
+            const state = randomToken(32);
+            const start = new URL(sourceStartPath(config.app), sourceOrigin);
+            start.searchParams.set("code_challenge", await s256(verifier));
+            start.searchParams.set("state", state);
+            const response = redirect(start);
+            setCookie(response, cookies.verifier, verifier, cookieOptions);
+            setCookie(response, cookies.state, state, cookieOptions);
+            const from = safeInternalPath(url.searchParams.get("from"));
+            if (from)
+                setCookie(response, cookies.from, from, cookieOptions);
+            return response;
+        },
+        /** GET `?code=&state=` — exchange the one-time code and establish the session. */
+        async callback(request) {
+            const url = new URL(request.url);
+            const code = url.searchParams.get("code") ?? "";
+            const state = url.searchParams.get("state") ?? "";
+            const expectedState = readCookie(request, cookies.state) ?? "";
+            const verifier = readCookie(request, cookies.verifier) ?? "";
+            if (!code || !state || !expectedState || state !== expectedState || !verifier) {
+                return fail(url.origin, "handoff_state_invalid");
+            }
+            const device = config.device.read(request);
+            const respond = (response) => config.device.persist(response, device);
+            try {
+                const headers = forwardedRequestHeaders(request, {
+                    "Content-Type": "application/json",
+                    "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 payload = await response.json().catch(() => ({}));
+                if (!response.ok) {
+                    const backendCode = payload?.code;
+                    return respond(fail(url.origin, typeof backendCode === "string" ? backendCode : "handoff_exchange_failed"));
+                }
+                const session = parseAuthResponse(payload);
+                if (!session || !hasTokenAudience(session.access_token, config.audience)) {
+                    return respond(fail(url.origin, "handoff_exchange_failed"));
+                }
+                const from = safeInternalPath(readCookie(request, cookies.from)) ?? config.defaultReturnPath;
+                const established = (await config.establishSession(session, redirect(new URL(from, url.origin)), request)) ?? redirect(new URL(from, url.origin));
+                return respond(clearHandoffCookies(established));
+            }
+            catch {
+                return respond(fail(url.origin, "handoff_exchange_failed"));
+            }
+        },
+    };
+}
+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;
+    return {
+        /** GET `/api/auth/handoffs/{app}/start?code_challenge=&state=`. */
+        async start(request, app) {
+            const target = config.targets[app];
+            if (!target)
+                return new Response("unknown handoff application", { status: 404, headers: { "Cache-Control": "no-store" } });
+            const targetOrigin = originOf(resolve(target.origin));
+            const targetLogin = target.loginPath ?? DEFAULT_TARGET_LOGIN;
+            if (!targetOrigin)
+                return new Response("handoff target not configured", { status: 503, headers: { "Cache-Control": "no-store" } });
+            const targetError = (code) => loginErrorRedirect(targetOrigin, targetLogin, code);
+            const url = new URL(request.url);
+            const challenge = url.searchParams.get("code_challenge")?.trim() ?? "";
+            const state = url.searchParams.get("state")?.trim() ?? "";
+            if (!CHALLENGE_PATTERN.test(challenge) || !validState(state))
+                return targetError("handoff_request_invalid");
+            const sourceLogin = () => {
+                const login = new URL(config.loginPath, url.origin);
+                login.searchParams.set("from", `${url.pathname}${url.search}`);
+                return redirect(login);
+            };
+            const token = await config.getAccessToken(request);
+            if (!token)
+                return sourceLogin();
+            try {
+                const headers = forwardedRequestHeaders(request, {
+                    "Content-Type": "application/json",
+                    "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);
+                if (response.status === 401)
+                    return sourceLogin();
+                const payload = await response.json().catch(() => ({}));
+                if (!response.ok) {
+                    const backendCode = payload?.code;
+                    return targetError(typeof backendCode === "string" ? backendCode : "handoff_start_failed");
+                }
+                const redirectUrl = payload?.redirect_url;
+                if (typeof redirectUrl !== "string")
+                    return targetError("handoff_start_failed");
+                let destination;
+                try {
+                    destination = new URL(redirectUrl);
+                }
+                catch {
+                    return targetError("handoff_redirect_invalid");
+                }
+                if (destination.origin !== targetOrigin || destination.pathname !== (target.callbackPath ?? DEFAULT_TARGET_CALLBACK)) {
+                    return targetError("handoff_redirect_invalid");
+                }
+                return redirect(destination);
+            }
+            catch {
+                return targetError("handoff_start_failed");
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./token.js";
+export * from "./return-path.js";
+export * from "./forwarding.js";
+export * from "./cookies.js";
+export * from "./device-cookie.js";
+export * from "./handoff-errors.js";
+export * from "./handoff.js";
+export * from "./session-refresh.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./token.js";
+export * from "./return-path.js";
+export * from "./forwarding.js";
+export * from "./cookies.js";
+export * from "./device-cookie.js";
+export * from "./handoff-errors.js";
+export * from "./handoff.js";
+export * from "./session-refresh.js";

package/dist/next.d.ts

@@ -0,0 +1,2 @@
+import "server-only";
+export * from "./index.js";

package/dist/next.js

@@ -0,0 +1,5 @@
+// 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.
+import "server-only";
+export * from "./index.js";

package/dist/return-path.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export declare function safeInternalPath(raw: string | null | undefined): string | null;

package/dist/return-path.js

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export function safeInternalPath(raw) {
+    if (raw == null)
+        return null;
+    const candidate = raw.trim();
+    if (candidate.length === 0)
+        return null;
+    if (!candidate.startsWith("/"))
+        return null;
+    if (candidate.startsWith("//") || candidate.includes("://"))
+        return null;
+    if (/%(?:2f|5c)/i.test(candidate))
+        return null;
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(candidate))
+        return null;
+    try {
+        const parsed = new URL(candidate, "https://internal.invalid");
+        if (parsed.origin !== "https://internal.invalid")
+            return null;
+        const roundtrip = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+        if (roundtrip !== candidate)
+            return null;
+        return candidate;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/session-refresh.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+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

@@ -0,0 +1,69 @@
+import { hasTokenAudience, parseAuthResponse } from "./token.js";
+const DEFAULT_TTL_MS = 5000;
+const DEFAULT_MAX = 1000;
+const DEFAULT_TIMEOUT_MS = 10_000;
+export function createSessionRefresher(config) {
+    const ttl = config.singleflightTtlMs ?? DEFAULT_TTL_MS;
+    const max = config.maxSingleflights ?? DEFAULT_MAX;
+    const timeoutMs = config.fetchTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const inflight = new Map();
+    async function perform(refreshToken) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const apiUrl = typeof config.apiUrl === "function" ? config.apiUrl() : config.apiUrl;
+            const response = await fetch(`${apiUrl}${config.refreshPath}`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "X-Client-Type": config.clientType },
+                body: JSON.stringify({ refresh_token: refreshToken }),
+                cache: "no-store",
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                return null;
+            const data = parseAuthResponse(await response.json());
+            return data && hasTokenAudience(data.access_token, config.audience)
+                ? { accessToken: data.access_token, refreshToken: data.refresh_token }
+                : null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    function prune(now) {
+        for (const [token, entry] of inflight) {
+            if (entry.expiresAt <= now)
+                inflight.delete(token);
+        }
+        while (inflight.size >= max) {
+            const oldest = inflight.keys().next().value;
+            if (typeof oldest !== "string")
+                break;
+            inflight.delete(oldest);
+        }
+    }
+    return {
+        /** Exchange a refresh token; identical concurrent calls share one backend request. */
+        refresh(refreshToken) {
+            const now = Date.now();
+            prune(now);
+            const existing = inflight.get(refreshToken);
+            if (existing && existing.expiresAt > now)
+                return existing.promise;
+            const promise = perform(refreshToken).then((result) => {
+                if (!result)
+                    inflight.delete(refreshToken);
+                return result;
+            });
+            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

@@ -0,0 +1,55 @@
+/**
+ * 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;
+    name: string;
+    role: string;
+    is_active: boolean;
+    email_verified: boolean;
+    created_at: string;
+    last_login_at?: string;
+    has_passkey?: boolean;
+}
+export interface SessionData {
+    user: SessionUser;
+    token: string;
+    exp: number;
+    iat: number;
+}
+export type TokenPayload = Record<string, unknown> & {
+    sub?: string;
+    exp?: number;
+    iat?: number;
+    actor_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;
+};
+export declare function decodeBase64Url(input: string): string | null;
+export declare function decodeTokenPayload(token: string): TokenPayload | null;
+export declare function hasTokenAudience(token: string, requiredAudience: string): boolean;
+/** Cookie max-age clamped to the token's remaining lifetime. */
+export declare function tokenMaxAgeSeconds(token: string, configuredMaxAge: number): number;
+export declare function isTokenExpired(token: string): boolean;
+export declare function isTokenExpiringSoon(token: string, bufferSeconds?: number): boolean;
+export declare function decodeDefaultSession(token: string): SessionData | null;
+/** Backend auth response shape shared by verify-code, OIDC complete, and handoff exchange. */
+export interface AuthResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_at: string;
+    user: Record<string, unknown>;
+}
+export declare function parseAuthResponse(value: unknown): AuthResponse | null;

package/dist/token.js

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+function readStringClaim(value, fallback = "") {
+    return typeof value === "string" ? value : fallback;
+}
+function readBooleanClaim(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+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);
+    }
+    catch {
+        return null;
+    }
+}
+export function decodeTokenPayload(token) {
+    const payloadSegment = token.split(".")[1];
+    if (!payloadSegment)
+        return null;
+    const decodedJson = decodeBase64Url(payloadSegment);
+    if (!decodedJson)
+        return null;
+    try {
+        const parsed = JSON.parse(decodedJson);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hasTokenAudience(token, requiredAudience) {
+    const audience = decodeTokenPayload(token)?.aud;
+    return typeof audience === "string"
+        ? audience === requiredAudience
+        : Array.isArray(audience) && audience.includes(requiredAudience);
+}
+function nowInSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+/** Cookie max-age clamped to the token's remaining lifetime. */
+export function tokenMaxAgeSeconds(token, configuredMaxAge) {
+    const decoded = decodeTokenPayload(token);
+    if (!decoded?.exp)
+        return configuredMaxAge;
+    return Math.max(0, Math.min(configuredMaxAge, decoded.exp - nowInSeconds()));
+}
+export function isTokenExpired(token) {
+    const decoded = decodeTokenPayload(token);
+    if (!decoded?.exp)
+        return true;
+    return decoded.exp <= nowInSeconds();
+}
+export function isTokenExpiringSoon(token, bufferSeconds = 120) {
+    const decoded = decodeTokenPayload(token);
+    if (!decoded?.exp)
+        return true;
+    return decoded.exp < nowInSeconds() + bufferSeconds;
+}
+export function decodeDefaultSession(token) {
+    const decoded = decodeTokenPayload(token);
+    if (!decoded)
+        return null;
+    const actorId = decoded.actor_id ||
+        decoded.customer_id ||
+        decoded.user_id ||
+        (typeof decoded.sub === "string" ? decoded.sub : undefined);
+    if (!actorId)
+        return null;
+    return {
+        user: {
+            id: String(actorId),
+            email: readStringClaim(decoded.email),
+            name: readStringClaim(decoded.name),
+            role: readStringClaim(decoded.role, "user"),
+            is_active: readBooleanClaim(decoded.is_active, true),
+            email_verified: readBooleanClaim(decoded.email_verified, false),
+            created_at: readStringClaim(decoded.created_at),
+            has_passkey: readBooleanClaim(decoded.has_passkeys, false),
+        },
+        token,
+        exp: decoded.exp || 0,
+        iat: decoded.iat || 0,
+    };
+}
+export function parseAuthResponse(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const candidate = value;
+    if (typeof candidate.access_token !== "string" ||
+        typeof candidate.refresh_token !== "string" ||
+        typeof candidate.token_type !== "string" ||
+        typeof candidate.expires_at !== "string" ||
+        !candidate.user ||
+        typeof candidate.user !== "object") {
+        return null;
+    }
+    return candidate;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@c1m-public/platform-auth",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Framework-neutral session helpers for C1M platform surfaces: token payload reads, forwarded client headers, safe return paths, device identity cookies, and the first-party session handoff (target callback + source start) built on Web Request/Response",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloud1mediaLtd/mml-js.git",
+    "directory": "packages/platform-auth"
+  },
+  "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"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "type-check": "tsc -p tsconfig.json --noEmit"
+  }
+}