@c1m-public/platform-auth 0.21.0 → 0.22.0

package/README.md

@@ -28,11 +28,13 @@ sessions never needs them.
 | `readCookie`, `serializeCookie`, `setCookie`, `deleteCookie` | Cookie helpers over Web `Request`/`Response`. `__Host-` names get `Secure` automatically. |
 | `createDeviceIdentity` | The `X-Client-Device-ID` cookie the backend requires to create a session. |
 | `applyForwardedClientHeaders`, `forwardedRequestHeaders` | Copy client identity (IP, geo, UA) onto a backend call. Never used for auth. |
-| `safeInternalPath` | Strict same-origin return-path sanitiser (rejects `//`, `://`, encoded slashes, control chars, anything that does not round-trip). |
+| `safeInternalPath(raw, { stripParams? })` | Strict same-origin return-path sanitiser (rejects `//`, `://`, encoded slashes, control chars, anything that does not round-trip). `stripParams` drops named query params (e.g. a one-shot `auth`/`from` flag) from the accepted value so it doesn't survive into the redirect target. |
 | `createSessionRefresher` | Coalesced refresh-token exchange: one backend call per token per window. |
-| `evaluateSessionGate`, `hasSessionShape` | Pure proxy decision — `pass` / `redirect_home` / `anonymous_public` / `unauthorized_api` / `redirect_login`. The proxy owns response construction. |
+| `evaluateSessionGate`, `hasSessionShape` | Pure proxy decision — `pass` / `redirect_home` / `anonymous_public` / `unauthorized_api` / `redirect_login`. The proxy owns response construction. `eagerReauthBufferSeconds` demotes a token expiring within that window to not-live, so a failed refresh rejects the session instead of passing through on the still-valid token. |
 | `createHandoffTarget`, `createHandoffSource`, `brokerPaths`, `sourceStartPath` | 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`, `SSO_ERROR_MESSAGES`, `AUTH_ERROR_MESSAGES`, `authErrorMessage(code, overrides?)`, `isAuthErrorCode`, `handoffErrorMessage`, `isHandoffErrorCode` | One sign-in error vocabulary — handoff, admission and SSO codes. Surfaces pass their own copy as `overrides` instead of forking the map. |
+| `ADMIN_HOST_ROOT`, `isAdminRootHost`, `adminSlugFromHost`, `recoveryAdminOrigin`, `brandedAdminHost` | The `<slug>.saasdash.app` / `admin.<domain>` admin-host rules, mirroring the backend's `internal/platform/domainmanagement/admin_dash_hostnames.go`. |
+| `SIGN_IN_HINT_COOKIE`, `signInHintDomain`, `signInHintCookie`, `hasSignInHint` | The non-secret "signed in" display hint an admin host sets on its own domain so the Dash's public site can show "Open your workspace" instead of "Sign in". `signInHintDomain`/`signInHintCookie` are the pure writer half; `hasSignInHint` the reader. The hint carries no identity and must never gate access. |
 
 ```ts
 // proxy.ts

package/dist/{index-BxyVV6Wt.d.ts → index-Bc_E5HWA.d.ts}

@@ -50,12 +50,22 @@ interface AuthResponse {
 }
 declare function parseAuthResponse(value: unknown): AuthResponse | null;
 
+interface SafeInternalPathOptions {
+    /**
+     * Query params to drop from the accepted value before returning it — e.g. a
+     * one-shot `auth`/`from` flag that must not survive into the redirect
+     * target and reopen a login modal. Omitted or empty: the value comes back
+     * verbatim, as before this option existed.
+     */
+    stripParams?: readonly string[];
+}
 /**
  * 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.
+ * Returns the value verbatim (query/hash kept) or null, unless `stripParams`
+ * asks for named query params to be dropped from the accepted value.
  */
-declare function safeInternalPath(raw: string | null | undefined): string | null;
+declare function safeInternalPath(raw: string | null | undefined, options?: SafeInternalPathOptions): string | null;
 
 declare function applyForwardedClientHeaders(incoming: Headers, headers?: Headers): Headers;
 declare function forwardedRequestHeaders(request: Request, init?: HeadersInit): Headers;
@@ -269,7 +279,97 @@ interface SessionGateInput {
     isLoginPath: boolean;
     isApiPath: boolean;
     expiringSoonBufferSeconds?: number;
+    /**
+     * Demotes a token expiring within this many seconds to not-live, so refresh
+     * becomes mandatory rather than best-effort: a failed exchange rejects the
+     * session (`redirect_login` / `anonymous_public` / `unauthorized_api`)
+     * instead of passing through on the still-valid access token. Unset, a
+     * live token always passes even when its pre-emptive refresh fails — the
+     * default, and what `expiringSoonBufferSeconds` alone gives you. Set this
+     * where a surface wants to force reauthentication near expiry rather than
+     * ride out the old token (saasdash-app's proxy did this by hand, passing
+     * `accessToken: undefined` once inside its own buffer).
+     */
+    eagerReauthBufferSeconds?: number;
 }
 declare function evaluateSessionGate(input: SessionGateInput): Promise<SessionGateDecision>;
 
-export { type AsyncResolvable as A, decodeDefaultSession as B, type CookieOptions as C, type DeviceIdentity as D, decodeTokenPayload as E, deleteCookie as F, evaluateSessionGate as G, HANDOFF_ERROR_FALLBACK as H, forwardedRequestHeaders as I, handoffErrorMessage as J, hasSessionShape as K, hasTokenAudience as L, isAuthErrorCode as M, isHandoffErrorCode as N, isTokenExpired as O, isTokenExpiringSoon as P, parseAuthResponse as Q, type Resolvable as R, type SessionData as S, type TokenPayload as T, parseRefreshEnvelope as U, readCookie as V, safeInternalPath as W, serializeCookie as X, setCookie as Y, sourceStartPath as Z, tokenMaxAgeSeconds as _, AUTH_ERROR_MESSAGES as a, type AuthResponse as b, type DeviceIdentityConfig as c, type DeviceIdentityStore as d, HANDOFF_ERROR_MESSAGES as e, type HandoffSource as f, type HandoffSourceConfig as g, type HandoffSourceTarget as h, type HandoffTarget as i, type HandoffTargetConfig as j, type RefreshOutcome as k, type RefreshedSession as l, SSO_ERROR_MESSAGES as m, type SessionGateDecision as n, type SessionGateInput as o, type SessionRefresher as p, type SessionRefresherConfig as q, type SessionUser as r, applyForwardedClientHeaders as s, authErrorMessage as t, brokerPaths as u, createDeviceIdentity as v, createHandoffSource as w, createHandoffTarget as x, createSessionRefresher as y, decodeBase64Url as z };
+/**
+ * Root of the shared `<slug>.saasdash.app` admin hosts every Dash gets
+ * (`c1m-server` `internal/platform/domainmanagement/admin_dash_hostnames.go`
+ * `AdminHostRoot`), alongside its own `admin.<domain>` once it has a managed
+ * domain.
+ */
+declare const ADMIN_HOST_ROOT = "saasdash.app";
+/**
+ * True for any host under the shared admin root, excluding the bare root
+ * itself (`saasdash.app` is the shared app, not an admin host).
+ */
+declare function isAdminRootHost(hostname: string): boolean;
+/**
+ * The Dash slug a `<slug>.saasdash.app` admin host is locked to, or null for
+ * every other host — including the bare root, a nested label
+ * (`a.b.saasdash.app`), and a `www` label, which is a real subdomain here and
+ * never stripped: `www.saasdash.app` and `www.<slug>.saasdash.app` are both
+ * rejected rather than aliased to `<slug>`.
+ */
+declare function adminSlugFromHost(hostname: string): string | null;
+/**
+ * The Dash's platform-owned recovery admin origin
+ * (`https://<slug>.saasdash.app`). Unlike `admin.<customer domain>` it cannot
+ * be broken by the customer's DNS, so links the platform sends itself
+ * (billing and security mail, hosted-checkout returns) use it. Mirrors
+ * `DashRecoveryBaseURL`. Returns `""` for an empty slug, exactly as the Go
+ * source does.
+ */
+declare function recoveryAdminOrigin(slug: string): string;
+/**
+ * The branded admin host for a Dash's own managed domain (`admin.<domain>`).
+ * Mirrors the second entry `DashAdminHostnames` returns once a Dash has a
+ * managed domain.
+ */
+declare function brandedAdminHost(domain: string): string;
+
+/**
+ * Set by a Dash's admin host on the Dash's own domain while someone is signed
+ * in there. A display hint only ("Open your workspace" instead of "Sign
+ * in"): it carries no identity and must never gate access.
+ */
+declare const SIGN_IN_HINT_COOKIE = "c1m_signed_in";
+interface SignInHintDomainOptions {
+    /**
+     * Extra hosts (and their subdomains) that must never receive the hint's
+     * cookie Domain because their siblings are other Dashes — e.g. the shared
+     * app's own host. `ADMIN_HOST_ROOT` is always excluded, in addition to
+     * these.
+     */
+    excludedRoots?: readonly string[];
+}
+/**
+ * The cookie Domain for an admin host's sign-in hint: the host minus its
+ * first label (`admin.simplevan.co.uk` → `simplevan.co.uk`). null for the
+ * shared admin root (and any `excludedRoots`) or one of their subdomains —
+ * their siblings are other Dashes — and for a host with fewer than three
+ * labels, which has nothing to strip.
+ */
+declare function signInHintDomain(hostname: string, options?: SignInHintDomainOptions): string | null;
+interface SignInHintCookieAttributes {
+    name: string;
+    value: string;
+    domain: string;
+    path: "/";
+    sameSite: "lax";
+    secure: true;
+    httpOnly: false;
+    maxAge: number;
+}
+/**
+ * The cookie attributes to set (`signedIn: true`) or clear (`signedIn:
+ * false`) the hint with. Pure data — the caller applies it to its own
+ * response.
+ */
+declare function signInHintCookie(domain: string, signedIn: boolean): SignInHintCookieAttributes;
+/** Reads the hint from a `Cookie` header or `document.cookie` string. */
+declare function hasSignInHint(cookieHeader: string | null | undefined): boolean;
+
+export { isTokenExpiringSoon as $, type AsyncResolvable as A, brandedAdminHost as B, type CookieOptions as C, type DeviceIdentity as D, brokerPaths as E, createDeviceIdentity as F, createHandoffSource as G, HANDOFF_ERROR_FALLBACK as H, createHandoffTarget as I, createSessionRefresher as J, decodeBase64Url as K, decodeDefaultSession as L, decodeTokenPayload as M, deleteCookie as N, evaluateSessionGate as O, forwardedRequestHeaders as P, handoffErrorMessage as Q, type Resolvable as R, type SessionData as S, type TokenPayload as T, hasSessionShape as U, hasSignInHint as V, hasTokenAudience as W, isAdminRootHost as X, isAuthErrorCode as Y, isHandoffErrorCode as Z, isTokenExpired as _, ADMIN_HOST_ROOT as a, parseAuthResponse as a0, parseRefreshEnvelope as a1, readCookie as a2, recoveryAdminOrigin as a3, safeInternalPath as a4, serializeCookie as a5, setCookie as a6, signInHintCookie as a7, signInHintDomain as a8, sourceStartPath as a9, tokenMaxAgeSeconds as aa, AUTH_ERROR_MESSAGES as b, type AuthResponse as c, type DeviceIdentityConfig as d, type DeviceIdentityStore as e, HANDOFF_ERROR_MESSAGES as f, type HandoffSource as g, type HandoffSourceConfig as h, type HandoffSourceTarget as i, type HandoffTarget as j, type HandoffTargetConfig as k, type RefreshOutcome as l, type RefreshedSession as m, SIGN_IN_HINT_COOKIE as n, SSO_ERROR_MESSAGES as o, type SafeInternalPathOptions as p, type SessionGateDecision as q, type SessionGateInput as r, type SessionRefresher as s, type SessionRefresherConfig as t, type SessionUser as u, type SignInHintCookieAttributes as v, type SignInHintDomainOptions as w, adminSlugFromHost as x, applyForwardedClientHeaders as y, authErrorMessage as z };

package/dist/index.d.ts

@@ -1 +1 @@
-export { a as AUTH_ERROR_MESSAGES, b as AuthResponse, C as CookieOptions, D as DeviceIdentity, c as DeviceIdentityConfig, d as DeviceIdentityStore, H as HANDOFF_ERROR_FALLBACK, e as HANDOFF_ERROR_MESSAGES, f as HandoffSource, g as HandoffSourceConfig, h as HandoffSourceTarget, i as HandoffTarget, j as HandoffTargetConfig, k as RefreshOutcome, l as RefreshedSession, m as SSO_ERROR_MESSAGES, S as SessionData, n as SessionGateDecision, o as SessionGateInput, p as SessionRefresher, q as SessionRefresherConfig, r as SessionUser, T as TokenPayload, s as applyForwardedClientHeaders, t as authErrorMessage, u as brokerPaths, v as createDeviceIdentity, w as createHandoffSource, x as createHandoffTarget, y as createSessionRefresher, z as decodeBase64Url, B as decodeDefaultSession, E as decodeTokenPayload, F as deleteCookie, G as evaluateSessionGate, I as forwardedRequestHeaders, J as handoffErrorMessage, K as hasSessionShape, L as hasTokenAudience, M as isAuthErrorCode, N as isHandoffErrorCode, O as isTokenExpired, P as isTokenExpiringSoon, Q as parseAuthResponse, U as parseRefreshEnvelope, V as readCookie, W as safeInternalPath, X as serializeCookie, Y as setCookie, Z as sourceStartPath, _ as tokenMaxAgeSeconds } from './index-BxyVV6Wt.js';
+export { a as ADMIN_HOST_ROOT, b as AUTH_ERROR_MESSAGES, c as AuthResponse, C as CookieOptions, D as DeviceIdentity, d as DeviceIdentityConfig, e as DeviceIdentityStore, H as HANDOFF_ERROR_FALLBACK, f as HANDOFF_ERROR_MESSAGES, g as HandoffSource, h as HandoffSourceConfig, i as HandoffSourceTarget, j as HandoffTarget, k as HandoffTargetConfig, l as RefreshOutcome, m as RefreshedSession, n as SIGN_IN_HINT_COOKIE, o as SSO_ERROR_MESSAGES, p as SafeInternalPathOptions, S as SessionData, q as SessionGateDecision, r as SessionGateInput, s as SessionRefresher, t as SessionRefresherConfig, u as SessionUser, v as SignInHintCookieAttributes, w as SignInHintDomainOptions, T as TokenPayload, x as adminSlugFromHost, y as applyForwardedClientHeaders, z as authErrorMessage, B as brandedAdminHost, E as brokerPaths, F as createDeviceIdentity, G as createHandoffSource, I as createHandoffTarget, J as createSessionRefresher, K as decodeBase64Url, L as decodeDefaultSession, M as decodeTokenPayload, N as deleteCookie, O as evaluateSessionGate, P as forwardedRequestHeaders, Q as handoffErrorMessage, U as hasSessionShape, V as hasSignInHint, W as hasTokenAudience, X as isAdminRootHost, Y as isAuthErrorCode, Z as isHandoffErrorCode, _ as isTokenExpired, $ as isTokenExpiringSoon, a0 as parseAuthResponse, a1 as parseRefreshEnvelope, a2 as readCookie, a3 as recoveryAdminOrigin, a4 as safeInternalPath, a5 as serializeCookie, a6 as setCookie, a7 as signInHintCookie, a8 as signInHintDomain, a9 as sourceStartPath, aa as tokenMaxAgeSeconds } from './index-Bc_E5HWA.js';

package/dist/index.js

@@ -81,7 +81,7 @@ function parseAuthResponse(value) {
 }
 
 // src/return-path.ts
-function safeInternalPath(raw) {
+function safeInternalPath(raw, options) {
   if (raw == null) return null;
   const candidate = raw.trim();
   if (candidate.length === 0) return null;
@@ -94,7 +94,11 @@ function safeInternalPath(raw) {
     if (parsed.origin !== "https://internal.invalid") return null;
     const roundtrip = `${parsed.pathname}${parsed.search}${parsed.hash}`;
     if (roundtrip !== candidate) return null;
-    return candidate;
+    if (!options?.stripParams?.length) return candidate;
+    const params = new URLSearchParams(parsed.search);
+    for (const key of options.stripParams) params.delete(key);
+    const query = params.toString();
+    return `${parsed.pathname}${query ? `?${query}` : ""}${parsed.hash}`;
   } catch {
     return null;
   }
@@ -564,7 +568,9 @@ function hasSessionShape(token) {
 }
 async function evaluateSessionGate(input) {
   const { accessToken, refreshToken, audience, refresher, isPublic, isLoginPath, isApiPath } = input;
-  const live = !!accessToken && hasSessionShape(accessToken) && hasTokenAudience(accessToken, audience) && !isTokenExpired(accessToken);
+  const rawLive = !!accessToken && hasSessionShape(accessToken) && hasTokenAudience(accessToken, audience) && !isTokenExpired(accessToken);
+  const eagerlyExpiring = rawLive && input.eagerReauthBufferSeconds != null && isTokenExpiringSoon(accessToken, input.eagerReauthBufferSeconds);
+  const live = rawLive && !eagerlyExpiring;
   const attempt = async (token) => refresher.attemptRefresh ? await refresher.attemptRefresh(token) : await refresher.refresh(token).then(
     (session) => session ? { status: "refreshed", session } : { status: "rejected" }
   );
@@ -588,4 +594,78 @@ async function evaluateSessionGate(input) {
   return { kind: "redirect_login" };
 }
 
-export { AUTH_ERROR_MESSAGES, HANDOFF_ERROR_FALLBACK, HANDOFF_ERROR_MESSAGES, SSO_ERROR_MESSAGES, applyForwardedClientHeaders2 as applyForwardedClientHeaders, authErrorMessage, brokerPaths, createDeviceIdentity, createHandoffSource, createHandoffTarget, createSessionRefresher, decodeBase64Url, decodeDefaultSession, decodeTokenPayload, deleteCookie, evaluateSessionGate, forwardedRequestHeaders2 as forwardedRequestHeaders, handoffErrorMessage, hasSessionShape, hasTokenAudience, isAuthErrorCode, isHandoffErrorCode, isTokenExpired, isTokenExpiringSoon, parseAuthResponse, parseRefreshEnvelope, readCookie, safeInternalPath, serializeCookie, setCookie, sourceStartPath, tokenMaxAgeSeconds };
+// src/hosts.ts
+var ADMIN_HOST_ROOT = "saasdash.app";
+function normalizeRequestHost(hostname) {
+  let host = hostname.trim().toLowerCase();
+  if (host.startsWith("[")) {
+    const end = host.indexOf("]");
+    host = end >= 0 ? host.slice(1, end) : host;
+  } else {
+    const colon = host.lastIndexOf(":");
+    if (colon >= 0) host = host.slice(0, colon);
+  }
+  while (host.endsWith(".")) host = host.slice(0, -1);
+  return host;
+}
+function normalizeGeneratedHost(raw) {
+  let host = raw.trim().toLowerCase();
+  host = host.replace(/^https?:\/\//, "");
+  host = host.replace(/^www\./, "");
+  host = host.replace(/\/$/, "");
+  return host;
+}
+function isAdminRootHost(hostname) {
+  const host = normalizeRequestHost(hostname);
+  return host !== ADMIN_HOST_ROOT && host.endsWith(`.${ADMIN_HOST_ROOT}`);
+}
+function adminSlugFromHost(hostname) {
+  if (!isAdminRootHost(hostname)) return null;
+  const host = normalizeRequestHost(hostname);
+  const slug = host.slice(0, host.length - `.${ADMIN_HOST_ROOT}`.length);
+  if (!slug || slug === "www" || slug.includes(".")) return null;
+  return slug;
+}
+function recoveryAdminOrigin(slug) {
+  const normalized = normalizeGeneratedHost(slug);
+  if (!normalized) return "";
+  return `https://${normalized}.${ADMIN_HOST_ROOT}`;
+}
+function brandedAdminHost(domain) {
+  return `admin.${normalizeGeneratedHost(domain)}`;
+}
+
+// src/sign-in-hint.ts
+var SIGN_IN_HINT_COOKIE = "c1m_signed_in";
+function normalizeHost(hostname) {
+  return hostname.split(":")[0]?.trim().toLowerCase() ?? "";
+}
+function signInHintDomain(hostname, options = {}) {
+  const host = normalizeHost(hostname);
+  const roots = [ADMIN_HOST_ROOT, ...options.excludedRoots ?? []];
+  for (const raw of roots) {
+    const root = normalizeHost(raw);
+    if (!host || !root || host === root || host.endsWith(`.${root}`)) return null;
+  }
+  const labels = host.split(".");
+  if (labels.length < 3) return null;
+  return labels.slice(1).join(".");
+}
+function signInHintCookie(domain, signedIn) {
+  return {
+    name: SIGN_IN_HINT_COOKIE,
+    value: signedIn ? "1" : "",
+    domain,
+    path: "/",
+    sameSite: "lax",
+    secure: true,
+    httpOnly: false,
+    maxAge: signedIn ? 30 * 24 * 60 * 60 : 0
+  };
+}
+function hasSignInHint(cookieHeader) {
+  if (!cookieHeader) return false;
+  return cookieHeader.split(";").some((pair) => pair.trim() === `${SIGN_IN_HINT_COOKIE}=1`);
+}
+
+export { ADMIN_HOST_ROOT, AUTH_ERROR_MESSAGES, HANDOFF_ERROR_FALLBACK, HANDOFF_ERROR_MESSAGES, SIGN_IN_HINT_COOKIE, SSO_ERROR_MESSAGES, adminSlugFromHost, applyForwardedClientHeaders2 as applyForwardedClientHeaders, authErrorMessage, brandedAdminHost, brokerPaths, createDeviceIdentity, createHandoffSource, createHandoffTarget, createSessionRefresher, decodeBase64Url, decodeDefaultSession, decodeTokenPayload, deleteCookie, evaluateSessionGate, forwardedRequestHeaders2 as forwardedRequestHeaders, handoffErrorMessage, hasSessionShape, hasSignInHint, hasTokenAudience, isAdminRootHost, isAuthErrorCode, isHandoffErrorCode, isTokenExpired, isTokenExpiringSoon, parseAuthResponse, parseRefreshEnvelope, readCookie, recoveryAdminOrigin, safeInternalPath, serializeCookie, setCookie, signInHintCookie, signInHintDomain, sourceStartPath, tokenMaxAgeSeconds };

package/dist/next.d.ts

@@ -1,5 +1,5 @@
-import { R as Resolvable, A as AsyncResolvable, S as SessionData, C as CookieOptions } from './index-BxyVV6Wt.js';
-export { a as AUTH_ERROR_MESSAGES, b as AuthResponse, D as DeviceIdentity, c as DeviceIdentityConfig, d as DeviceIdentityStore, H as HANDOFF_ERROR_FALLBACK, e as HANDOFF_ERROR_MESSAGES, f as HandoffSource, g as HandoffSourceConfig, h as HandoffSourceTarget, i as HandoffTarget, j as HandoffTargetConfig, k as RefreshOutcome, l as RefreshedSession, m as SSO_ERROR_MESSAGES, n as SessionGateDecision, o as SessionGateInput, p as SessionRefresher, q as SessionRefresherConfig, r as SessionUser, T as TokenPayload, s as applyForwardedClientHeaders, t as authErrorMessage, u as brokerPaths, v as createDeviceIdentity, w as createHandoffSource, x as createHandoffTarget, y as createSessionRefresher, z as decodeBase64Url, B as decodeDefaultSession, E as decodeTokenPayload, F as deleteCookie, G as evaluateSessionGate, I as forwardedRequestHeaders, J as handoffErrorMessage, K as hasSessionShape, L as hasTokenAudience, M as isAuthErrorCode, N as isHandoffErrorCode, O as isTokenExpired, P as isTokenExpiringSoon, Q as parseAuthResponse, U as parseRefreshEnvelope, V as readCookie, W as safeInternalPath, X as serializeCookie, Y as setCookie, Z as sourceStartPath, _ as tokenMaxAgeSeconds } from './index-BxyVV6Wt.js';
+import { R as Resolvable, A as AsyncResolvable, S as SessionData, C as CookieOptions } from './index-Bc_E5HWA.js';
+export { a as ADMIN_HOST_ROOT, b as AUTH_ERROR_MESSAGES, c as AuthResponse, D as DeviceIdentity, d as DeviceIdentityConfig, e as DeviceIdentityStore, H as HANDOFF_ERROR_FALLBACK, f as HANDOFF_ERROR_MESSAGES, g as HandoffSource, h as HandoffSourceConfig, i as HandoffSourceTarget, j as HandoffTarget, k as HandoffTargetConfig, l as RefreshOutcome, m as RefreshedSession, n as SIGN_IN_HINT_COOKIE, o as SSO_ERROR_MESSAGES, p as SafeInternalPathOptions, q as SessionGateDecision, r as SessionGateInput, s as SessionRefresher, t as SessionRefresherConfig, u as SessionUser, v as SignInHintCookieAttributes, w as SignInHintDomainOptions, T as TokenPayload, x as adminSlugFromHost, y as applyForwardedClientHeaders, z as authErrorMessage, B as brandedAdminHost, E as brokerPaths, F as createDeviceIdentity, G as createHandoffSource, I as createHandoffTarget, J as createSessionRefresher, K as decodeBase64Url, L as decodeDefaultSession, M as decodeTokenPayload, N as deleteCookie, O as evaluateSessionGate, P as forwardedRequestHeaders, Q as handoffErrorMessage, U as hasSessionShape, V as hasSignInHint, W as hasTokenAudience, X as isAdminRootHost, Y as isAuthErrorCode, Z as isHandoffErrorCode, _ as isTokenExpired, $ as isTokenExpiringSoon, a0 as parseAuthResponse, a1 as parseRefreshEnvelope, a2 as readCookie, a3 as recoveryAdminOrigin, a4 as safeInternalPath, a5 as serializeCookie, a6 as setCookie, a7 as signInHintCookie, a8 as signInHintDomain, a9 as sourceStartPath, aa as tokenMaxAgeSeconds } from './index-Bc_E5HWA.js';
 
 /**
  * The error vocabulary every first-party platform surface uses at its edge,

package/dist/next.js

@@ -86,7 +86,7 @@ function parseAuthResponse(value) {
 }
 
 // src/return-path.ts
-function safeInternalPath(raw) {
+function safeInternalPath(raw, options) {
   if (raw == null) return null;
   const candidate = raw.trim();
   if (candidate.length === 0) return null;
@@ -99,7 +99,11 @@ function safeInternalPath(raw) {
     if (parsed.origin !== "https://internal.invalid") return null;
     const roundtrip = `${parsed.pathname}${parsed.search}${parsed.hash}`;
     if (roundtrip !== candidate) return null;
-    return candidate;
+    if (!options?.stripParams?.length) return candidate;
+    const params = new URLSearchParams(parsed.search);
+    for (const key of options.stripParams) params.delete(key);
+    const query = params.toString();
+    return `${parsed.pathname}${query ? `?${query}` : ""}${parsed.hash}`;
   } catch {
     return null;
   }
@@ -569,7 +573,9 @@ function hasSessionShape(token) {
 }
 async function evaluateSessionGate(input) {
   const { accessToken, refreshToken, audience, refresher, isPublic, isLoginPath, isApiPath } = input;
-  const live = !!accessToken && hasSessionShape(accessToken) && hasTokenAudience(accessToken, audience) && !isTokenExpired(accessToken);
+  const rawLive = !!accessToken && hasSessionShape(accessToken) && hasTokenAudience(accessToken, audience) && !isTokenExpired(accessToken);
+  const eagerlyExpiring = rawLive && input.eagerReauthBufferSeconds != null && isTokenExpiringSoon(accessToken, input.eagerReauthBufferSeconds);
+  const live = rawLive && !eagerlyExpiring;
   const attempt = async (token) => refresher.attemptRefresh ? await refresher.attemptRefresh(token) : await refresher.refresh(token).then(
     (session) => session ? { status: "refreshed", session } : { status: "rejected" }
   );
@@ -593,6 +599,80 @@ async function evaluateSessionGate(input) {
   return { kind: "redirect_login" };
 }
 
+// src/hosts.ts
+var ADMIN_HOST_ROOT = "saasdash.app";
+function normalizeRequestHost(hostname) {
+  let host = hostname.trim().toLowerCase();
+  if (host.startsWith("[")) {
+    const end = host.indexOf("]");
+    host = end >= 0 ? host.slice(1, end) : host;
+  } else {
+    const colon = host.lastIndexOf(":");
+    if (colon >= 0) host = host.slice(0, colon);
+  }
+  while (host.endsWith(".")) host = host.slice(0, -1);
+  return host;
+}
+function normalizeGeneratedHost(raw) {
+  let host = raw.trim().toLowerCase();
+  host = host.replace(/^https?:\/\//, "");
+  host = host.replace(/^www\./, "");
+  host = host.replace(/\/$/, "");
+  return host;
+}
+function isAdminRootHost(hostname) {
+  const host = normalizeRequestHost(hostname);
+  return host !== ADMIN_HOST_ROOT && host.endsWith(`.${ADMIN_HOST_ROOT}`);
+}
+function adminSlugFromHost(hostname) {
+  if (!isAdminRootHost(hostname)) return null;
+  const host = normalizeRequestHost(hostname);
+  const slug = host.slice(0, host.length - `.${ADMIN_HOST_ROOT}`.length);
+  if (!slug || slug === "www" || slug.includes(".")) return null;
+  return slug;
+}
+function recoveryAdminOrigin(slug) {
+  const normalized = normalizeGeneratedHost(slug);
+  if (!normalized) return "";
+  return `https://${normalized}.${ADMIN_HOST_ROOT}`;
+}
+function brandedAdminHost(domain) {
+  return `admin.${normalizeGeneratedHost(domain)}`;
+}
+
+// src/sign-in-hint.ts
+var SIGN_IN_HINT_COOKIE = "c1m_signed_in";
+function normalizeHost(hostname) {
+  return hostname.split(":")[0]?.trim().toLowerCase() ?? "";
+}
+function signInHintDomain(hostname, options = {}) {
+  const host = normalizeHost(hostname);
+  const roots = [ADMIN_HOST_ROOT, ...options.excludedRoots ?? []];
+  for (const raw of roots) {
+    const root = normalizeHost(raw);
+    if (!host || !root || host === root || host.endsWith(`.${root}`)) return null;
+  }
+  const labels = host.split(".");
+  if (labels.length < 3) return null;
+  return labels.slice(1).join(".");
+}
+function signInHintCookie(domain, signedIn) {
+  return {
+    name: SIGN_IN_HINT_COOKIE,
+    value: signedIn ? "1" : "",
+    domain,
+    path: "/",
+    sameSite: "lax",
+    secure: true,
+    httpOnly: false,
+    maxAge: signedIn ? 30 * 24 * 60 * 60 : 0
+  };
+}
+function hasSignInHint(cookieHeader) {
+  if (!cookieHeader) return false;
+  return cookieHeader.split(";").some((pair) => pair.trim() === `${SIGN_IN_HINT_COOKIE}=1`);
+}
+
 // src/next/errors.ts
 var SessionExpiredError = class extends Error {
   constructor() {
@@ -900,4 +980,4 @@ function createSessionStore(config) {
   };
 }
 
-export { AUTH_ERROR_MESSAGES, HANDOFF_ERROR_FALLBACK, HANDOFF_ERROR_MESSAGES, PlatformServerFetchError, RecentAuthenticationRequiredError, SSOReauthenticationRequiredError, SSO_ERROR_MESSAGES, SessionExpiredError, applyForwardedClientHeaders2 as applyForwardedClientHeaders, authErrorMessage, authenticationErrorFor, brokerPaths, buildForwardedRequestHeaders, controlRequest, createDeviceIdentity, createHandoffSource, createHandoffTarget, createPlatformFetch, createSessionRefresher, createSessionStore, decodeBase64Url, decodeDefaultSession, decodeTokenPayload, deleteCookie, evaluateSessionGate, forwardedRequestHeaders2 as forwardedRequestHeaders, handoffErrorMessage, hasSessionShape, hasTokenAudience, isAuthErrorCode, isHandoffErrorCode, isPlatformServerFetchError, isRecentAuthenticationRequiredError, isSSOReauthenticationRequiredError, isSessionExpiredError, isTokenExpired, isTokenExpiringSoon, mapControlError, parseAuthResponse, parseRefreshEnvelope, readCookie, safeInternalPath, serializeCookie, setCookie, sourceStartPath, tokenMaxAgeSeconds };
+export { ADMIN_HOST_ROOT, AUTH_ERROR_MESSAGES, HANDOFF_ERROR_FALLBACK, HANDOFF_ERROR_MESSAGES, PlatformServerFetchError, RecentAuthenticationRequiredError, SIGN_IN_HINT_COOKIE, SSOReauthenticationRequiredError, SSO_ERROR_MESSAGES, SessionExpiredError, adminSlugFromHost, applyForwardedClientHeaders2 as applyForwardedClientHeaders, authErrorMessage, authenticationErrorFor, brandedAdminHost, brokerPaths, buildForwardedRequestHeaders, controlRequest, createDeviceIdentity, createHandoffSource, createHandoffTarget, createPlatformFetch, createSessionRefresher, createSessionStore, decodeBase64Url, decodeDefaultSession, decodeTokenPayload, deleteCookie, evaluateSessionGate, forwardedRequestHeaders2 as forwardedRequestHeaders, handoffErrorMessage, hasSessionShape, hasSignInHint, hasTokenAudience, isAdminRootHost, isAuthErrorCode, isHandoffErrorCode, isPlatformServerFetchError, isRecentAuthenticationRequiredError, isSSOReauthenticationRequiredError, isSessionExpiredError, isTokenExpired, isTokenExpiringSoon, mapControlError, parseAuthResponse, parseRefreshEnvelope, readCookie, recoveryAdminOrigin, safeInternalPath, serializeCookie, setCookie, signInHintCookie, signInHintDomain, sourceStartPath, tokenMaxAgeSeconds };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c1m-public/platform-auth",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "license": "MIT",
   "description": "Session and authorization helpers for C1M platform surfaces. The root is runtime-neutral (Web Request/Response): token/session reads, the first-party handoff (PKCE target + source), proxy session gate and coalesced refresh; ./next adds the server-only guard; ./access carries the resolved access snapshot, typed permission keys, predicates, a Next loader and React bindings",