@c1m-public/platform-auth 0.6.0 → 0.8.0

package/dist/handoff.js

@@ -1,195 +0,0 @@
-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";
-/**
- * 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}$/;
-export function sourceStartPath(app) {
-    return `/api/auth/handoffs/${encodeURIComponent(app)}/start`;
-}
-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`,
-    };
-}
-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);
-}
-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_FETCH_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=&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(resolveValue(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=` */
-        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 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;
-                    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_FETCH_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(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" } });
-            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 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(() => ({}));
-                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/internal.d.ts

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

@@ -1,27 +0,0 @@
-// 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/return-path.d.ts

@@ -1,6 +0,0 @@
-/**
- * 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,33 +0,0 @@
-/**
- * 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)
-        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-gate.d.ts

@@ -1,26 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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,24 +0,0 @@
-import { type Resolvable } from "./internal.js";
-/**
- * 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 {
-    apiUrl: Resolvable;
-    refreshPath: string;
-    clientType: string;
-    audience: string;
-    singleflightTtlMs?: number;
-    maxSingleflights?: number;
-    fetchTimeoutMs?: number;
-}
-export declare function createSessionRefresher(config: SessionRefresherConfig): {
-    refresh(refreshToken: string): Promise<RefreshedSession | null>;
-    size(): number;
-};
-export type SessionRefresher = ReturnType<typeof createSessionRefresher>;

package/dist/session-refresh.js

@@ -1,62 +0,0 @@
-import { DEFAULT_FETCH_TIMEOUT_MS, resolveValue, timedFetch } from "./internal.js";
-import { hasTokenAudience, parseAuthResponse } from "./token.js";
-const DEFAULT_TTL_MS = 5000;
-const DEFAULT_MAX = 1000;
-export function createSessionRefresher(config) {
-    const ttl = config.singleflightTtlMs ?? DEFAULT_TTL_MS;
-    const max = config.maxSingleflights ?? DEFAULT_MAX;
-    const timeoutMs = config.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
-    const inflight = new Map();
-    async function perform(refreshToken) {
-        try {
-            const response = await timedFetch(`${resolveValue(config.apiUrl)}${config.refreshPath}`, {
-                init: {
-                    method: "POST",
-                    headers: { "Content-Type": "application/json", "X-Client-Type": config.clientType },
-                    body: JSON.stringify({ refresh_token: refreshToken }),
-                },
-                timeoutMs,
-            });
-            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;
-        }
-    }
-    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 {
-        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;
-        },
-        size() {
-            return inflight.size;
-        },
-    };
-}

package/dist/token.d.ts

@@ -1,51 +0,0 @@
-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;
-    effective_user_id?: string;
-    customer_id?: string;
-    user_id?: string;
-    aud?: string | string[];
-    email?: string;
-    name?: string;
-    role?: string;
-    is_active?: boolean;
-    email_verified?: boolean;
-    created_at?: string;
-    has_passkeys?: boolean;
-};
-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

@@ -1,104 +0,0 @@
-// 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;
-}
-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 {
-        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;
-    // 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);
-    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;
-}