@voltro/protocol 0.85.0 → 0.87.0

package/dist/scopes.js

@@ -0,0 +1,273 @@
+import { RequestedTenantRefused as e } from "./tenantSelection.js";
+import { Unauthenticated as t, currentSubjectAuthority as n, reauthorizeSubject as r } from "./auth.js";
+import { Effect as i, Schema as a } from "effect";
+//#region src/scopes.ts
+var o = "admin:full", s = "apikeys:issue:self", c = "apikeys:issue:org", l = "apikeys:issue:other", u = "devices:manage", d = class extends a.TaggedError()("ScopeError", {
+	required: a.String,
+	message: a.String
+}) {}, f = class extends a.TaggedError()("NoSuchResource", {
+	resourceType: a.NullOr(a.String),
+	resourceId: a.String,
+	message: a.String
+}) {}, p = (e) => "scopes" in e && e.scopes ? e.scopes : [], m = /* @__PURE__ */ new WeakMap(), h = /* @__PURE__ */ new WeakMap(), g = (e, t) => {
+	h.set(e, t);
+}, _ = async (e, t) => {
+	let n = h.get(e);
+	n !== void 0 && (await n(t), h.set(t, n));
+}, v = (e, t) => {
+	typeof e == "object" && e && m.set(e, t);
+}, y = (e) => {
+	if (e = n(e), typeof e == "object" && e) {
+		let t = m.get(e);
+		if (t) return t;
+	}
+	return p(e);
+}, b = (e, t) => {
+	let n = y(e);
+	return n.includes("admin:full") || n.includes(t);
+}, x = (e, t) => {
+	let n = p(e);
+	return n.includes("admin:full") || n.includes(t);
+}, S = (e, t) => b(e, t) ? i.void : i.fail(new d({
+	required: t,
+	message: `missing required scope '${t}'`
+})), C = (e, t) => {
+	let n;
+	try {
+		n = typeof e.action == "function" ? e.action(t) : e.action;
+	} catch {
+		throw new d({
+			required: e.resourceType,
+			message: "policy action selector failed"
+		});
+	}
+	if (typeof n != "string" || n.trim() === "") throw new d({
+		required: e.resourceType,
+		message: "policy action selector returned no action"
+	});
+	return n;
+}, w = (e) => (typeof e.action == "string" || typeof e.action == "function") && typeof e.resourceType == "string", T = (e) => e !== void 0 && e.some((e) => w(e) || typeof e.resource == "function"), E = (e) => typeof e.open == "string", D = (e) => Array.isArray(e.service), O = (e) => ({ service: [...e] }), k = (e) => e?.find(D)?.service, A = (e, t) => {
+	for (let n of t ?? []) {
+		let t = N(n);
+		if (t) return K(e, t);
+	}
+	if (t?.some(M)) {
+		let t = P(e);
+		if (t) return t;
+	}
+	let n = k(t);
+	if (e.type === "service") return n !== void 0 && n.includes(e.service) ? null : new d({
+		required: "service-procedure",
+		message: n === void 0 ? `service '${e.service}' may only call procedures that declare it in \`service: { callers }\`` : `service '${e.service}' is not among this procedure's callers [${n.join(", ")}]`
+	});
+	if (n !== void 0) return K(e, new d({
+		required: `service:${n.join("|")}`,
+		message: `this procedure is callable only by the service${n.length === 1 ? "" : "s"} [${n.join(", ")}]`
+	}));
+}, j = (e) => e.authenticated === !0, M = (e) => e.upgraded === !0, N = (e) => typeof e != "object" || !e || !("upgraded" in e) || e.upgraded !== !0 ? null : [
+	"scope",
+	"mode",
+	"resource",
+	"action",
+	"resourceType",
+	"authenticated",
+	"open",
+	"service"
+].some((t) => t in e) ? new d({
+	required: "guard-shape",
+	message: "An upgraded guard must be a separate entry; put each additional scope, policy or identity requirement in its own guard entry."
+}) : null, P = (e) => e.type === "user" && e.kind !== "guest" ? null : K(e, new d({
+	required: "upgraded",
+	message: "this procedure requires a registered user account"
+})), F = (e) => ({ open: e }), I = (e) => typeof e == "string" ? [e] : e, L, R = (e) => {
+	L = e;
+}, z = (e) => L === void 0 ? e.filter((e) => (e.guards ?? []).some((e) => !w(e) && e.resource !== void 0)).map((e) => e.tag) : [], B = (e) => [
+	`${e.length} procedure${e.length === 1 ? "" : "s"} declare a per-resource guard that nothing enforces:`,
+	...e.slice(0, 10).map((e) => `    ${e}`),
+	...e.length > 10 ? [`    … and ${e.length - 10} more`] : [],
+	"",
+	"  `guards: [{ scope, resource }]` reads as \"may you do this to THIS resource\",",
+	"  but with no resource-scope resolver registered the extractor is advisory and",
+	"  the check runs against the caller's GLOBAL scopes. For an app whose",
+	"  authorization is per-resource, that guard passes callers it should refuse.",
+	"",
+	"  Fix it one of two ways:",
+	"    • setResourceScopeResolver((req) => Effect<boolean>) — answers \"does this",
+	"      subject hold `req.scope` on `req.resource`\" from your own tables.",
+	"    • Drop the `resource` extractor if a global scope check is what you meant."
+].join("\n"), V = () => L, H, U = (e) => {
+	H = e;
+}, W = () => H, G = (e) => new d({
+	required: "access-decision",
+	message: `${e ?? "this procedure"} declares no access decision: it has neither \`guards:\` nor \`openAccess:\`, and the app runs with \`security.defaultDeny\`. Add the scope(s) a caller must hold (\`guards: [{ scope: '…' }]\`), or declare it open on purpose with \`openAccess: '<why anyone may call this>'\`.`
+}), K = (e, n) => {
+	let r = e.credentialRejected;
+	return r === void 0 ? n : new t({ reason: `${r} — the request carried a credential and it was REJECTED, so this caller resolved to anonymous. The guard then refused (${n.message}); the scope is not the problem. Re-authenticate and retry.` });
+}, q = (e) => {
+	let t = Array.isArray(e), n = Object.getPrototypeOf(e);
+	if (t ? n !== Array.prototype : n !== Object.prototype && n !== null) return !1;
+	for (let n of Reflect.ownKeys(e)) if (t && (typeof n != "string" || n !== "length" && !/^(0|[1-9][0-9]*)$/.test(n)) || !("value" in Object.getOwnPropertyDescriptor(e, n))) return !1;
+	return !0;
+}, J = (e, t) => {
+	let n, r = 0, i, a = 0, o;
+	return (s) => {
+		let c = y(e);
+		return (c !== n || c.length !== r) && (n = c, r = c.length, i = void 0, a = 0, o = void 0), i === void 0 && c.length >= 32 && ++a > 1 && (o ??= q(c) && q(e) && q(t) && t.every((e) => q(e) && (!("scope" in e) || typeof e.scope == "string" || q(e.scope))), o && (i = new Set(c))), i === void 0 ? c.includes("admin:full") || c.includes(s) : i.has("admin:full") || i.has(s);
+	};
+}, Y = (e, t, n) => {
+	let r = A(e, t);
+	if (r !== void 0) return r;
+	if (!t || t.length === 0) return n?.defaultDeny === !0 ? G(n.procedure) : null;
+	let i = 0, a;
+	for (let n of t) {
+		if (E(n) || D(n)) continue;
+		if (M(n)) {
+			let t = P(e);
+			if (t) return t;
+			continue;
+		}
+		if (j(n)) {
+			if (e.id !== null && e.id !== void 0) continue;
+			return K(e, new d({
+				required: "authenticated",
+				message: "this procedure requires an authenticated caller"
+			}));
+		}
+		if (w(n)) {
+			if (i++, a === void 0 && (t.length >= 512 || i >= 512) && (a = J(e, t)), a === void 0 ? b(e, "admin:full") : a("admin:full")) continue;
+			return K(e, new d({
+				required: `${n.resourceType}:${n.action}`,
+				message: `relationship guard '${n.action}' on '${n.resourceType}' cannot be checked synchronously`
+			}));
+		}
+		let r = I(n.scope);
+		if (n.resourceOnly === !0) return K(e, new d({
+			required: r[0] ?? "resource",
+			message: "resource-only guard cannot be checked synchronously"
+		}));
+		if (r.length === 0) continue;
+		i += r.length, a === void 0 && (t.length >= 512 || i >= 512) && (a = J(e, t));
+		let o = n.mode ?? "all", s;
+		if (o === "any") {
+			if (a === void 0 ? r.some((t) => b(e, t)) : r.some(a)) continue;
+			s = r[0];
+		} else {
+			let t = a === void 0 ? r.find((t) => !b(e, t)) : r.find((e) => !a(e));
+			if (t === void 0) continue;
+			s = t;
+		}
+		return K(e, new d({
+			required: s,
+			message: o === "any" ? `missing all of required scopes [${r.join(", ")}]` : `missing required scope '${s}'`
+		}));
+	}
+	return null;
+}, X = (e, t, n) => {
+	let r;
+	try {
+		r = C(t, n);
+	} catch (e) {
+		return i.succeed(e);
+	}
+	let a = (e) => new d({
+		required: `${t.resourceType}:${r}`,
+		message: e
+	});
+	if (b(e, "admin:full")) return i.succeed(null);
+	let o = H;
+	if (o === void 0) return i.succeed(a(`no policy resolver registered — cannot authorize '${r}' on '${t.resourceType}'`));
+	let s = t.resource(n);
+	return s === void 0 || s === "" ? i.succeed(a(`input does not identify a '${t.resourceType}' to authorize`)) : i.suspend(() => o({
+		subject: e,
+		action: r,
+		resourceType: t.resourceType,
+		resourceId: s
+	})).pipe(i.catchCause(() => i.succeed(!1)), i.map((n) => Z(e, n, t.resourceType, s, () => a(`no '${r}' relation on ${t.resourceType}:${s}`))));
+}, Z = (e, t, n, r, i) => t === !0 ? null : t === "missing" && e.id !== null && e.id !== void 0 ? new f({
+	resourceType: n,
+	resourceId: r,
+	message: n === null ? `no such resource '${r}'` : `no such ${n} '${r}'`
+}) : i(), Q = (e, t, n, r) => {
+	let a = A(e, t);
+	if (a !== void 0) return i.succeed(a);
+	if (!t || t.length === 0) return i.succeed(Y(e, t, r));
+	let o = L, s = t.some(w), c = t.some((e) => "scope" in e && e.resourceOnly === !0);
+	return !s && !c && (!o || !t.some((e) => e.resource !== void 0)) ? i.succeed(Y(e, t, r)) : i.gen(function* () {
+		for (let r of t) {
+			if (E(r) || D(r)) continue;
+			if (M(r)) {
+				let t = P(e);
+				if (t) return t;
+				continue;
+			}
+			if (j(r)) {
+				if (e.id !== null && e.id !== void 0) continue;
+				return K(e, new d({
+					required: "authenticated",
+					message: "this procedure requires an authenticated caller"
+				}));
+			}
+			if (w(r)) {
+				let t = yield* X(e, r, n);
+				if (t) return t;
+				continue;
+			}
+			let t = I(r.scope);
+			if (t.length === 0) {
+				if (r.resourceOnly === !0) return K(e, new d({
+					required: "resource",
+					message: "resource-only guard requires a non-empty scope list"
+				}));
+				continue;
+			}
+			let a;
+			try {
+				a = r.resource ? r.resource(n) : void 0;
+			} catch (n) {
+				if (r.resourceOnly !== !0) throw n;
+				return K(e, new d({
+					required: t[0],
+					message: "resource selector failed"
+				}));
+			}
+			if (r.resourceOnly === !0 && (o === void 0 || typeof a != "string" || a === "")) return K(e, new d({
+				required: t[0],
+				message: "resource-only guard requires a resolver and a non-empty resource id"
+			}));
+			let s = [], c = !1;
+			for (let n of t) if (r.resourceOnly !== !0 && b(e, n)) s.push(!0);
+			else if (a !== void 0 && o !== void 0) {
+				let t = yield* i.suspend(() => o({
+					subject: e,
+					scope: n,
+					resource: a
+				})).pipe(i.catchCause(() => i.succeed(!1)));
+				t === "missing" && (c = !0), s.push(t === !0);
+			} else s.push(!1);
+			let l = r.mode ?? "all";
+			if (!(l === "any" ? s.some(Boolean) : s.every(Boolean))) {
+				let n = l === "any" ? t[0] : t[t.findIndex((e, t) => !s[t])];
+				if (c && a !== void 0) {
+					let t = Z(e, "missing", null, a, () => new d({
+						required: n,
+						message: `missing required scope '${n}' on resource '${a}'`
+					}));
+					if (t !== null) return t;
+				}
+				return new d({
+					required: n,
+					message: l === "any" ? `missing all of required scopes [${t.join(", ")}]` : `missing required scope '${n}'` + (a === void 0 ? "" : ` on resource '${a}'`)
+				});
+			}
+		}
+		return null;
+	});
+}, $ = (n, o, s, c) => i.tryPromise({
+	try: async () => r(n, (e) => _(n, e)),
+	catch: (e) => e
+}).pipe(i.matchEffect({
+	onFailure: (n) => a.is(t)(n) || a.is(e)(n) ? i.succeed(n) : i.die(n),
+	onSuccess: (e) => Q(e, o, s, c)
+}));
+//#endregion
+export { o as ADMIN_SCOPE, c as APIKEY_ISSUE_ORG_SCOPE, l as APIKEY_ISSUE_OTHER_SCOPE, s as APIKEY_ISSUE_SELF_SCOPE, u as DEVICES_MANAGE_SCOPE, f as NoSuchResource, d as ScopeError, B as advisoryResourceGuardWarning, Y as checkGuards, Q as checkGuardsEffect, T as declaresResourceGuard, y as effectiveScopes, z as findAdvisoryResourceGuards, W as getPolicyGuardResolver, V as getResourceScopeResolver, b as hasEffectiveScope, x as hasScope, j as isAuthenticatedCheck, E as isOpenAccess, w as isPolicyCheck, D as isServiceAccess, M as isUpgradedCheck, G as missingAccessDecision, F as openAccessSpec, $ as recheckGuardsEffect, _ as refreshEffectiveScopes, S as requireScope, C as resolvePolicyAction, O as serviceAccessSpec, k as serviceCallersOf, v as setEffectiveScopes, g as setEffectiveScopesRefresher, U as setPolicyGuardResolver, R as setResourceScopeResolver, p as subjectScopes, N as upgradedGuardShapeError };

package/dist/secretWindows.js

@@ -0,0 +1,71 @@
+import { createHash as e, createHmac as t, timingSafeEqual as n } from "node:crypto";
+//#region src/secretWindows.ts
+var r = (e) => t("sha256", e).update("voltro:secret-fingerprint:v1").digest("hex").slice(0, 16), i = Symbol.for("voltro.secretWindows"), a = () => {
+	let e = globalThis;
+	return e[i] ??= {
+		signed: /* @__PURE__ */ new Map(),
+		configured: /* @__PURE__ */ new Map(),
+		presented: /* @__PURE__ */ new Map(),
+		declared: /* @__PURE__ */ new Map(),
+		windows: /* @__PURE__ */ new Map()
+	}, e[i];
+}, o = (e, t) => {
+	let n = e.get(t);
+	if (n !== void 0) return n;
+	let r = /* @__PURE__ */ new Map();
+	return e.set(t, r), r;
+}, s = (e, t, n, i = Date.now()) => {
+	let s = o(a().signed, e), c = r(t), l = n ?? Infinity, u = s.get(c), d = Math.max(u?.longestMs ?? 0, l - i);
+	s.set(c, {
+		until: Math.max(u?.until ?? -Infinity, l),
+		longestMs: d
+	});
+}, c = (e, t) => {
+	let n = a().declared;
+	n.set(e, Math.max(n.get(e) ?? 0, t));
+}, l = (e, t, n) => {
+	a().configured.set(e, {
+		current: r(t),
+		previous: n === void 0 || n === "" || n === t ? null : r(n)
+	});
+}, u = () => {
+	let e = a(), t = [...e.signed].flatMap(([e, t]) => [...t].map(([t, n]) => ({
+		purpose: e,
+		fingerprint: t,
+		signedUntil: n.until,
+		longestMs: n.longestMs
+	}))), n = [...e.presented].flatMap(([e, t]) => [...t].map(([t, n]) => ({
+		purpose: e,
+		fingerprint: t,
+		at: n
+	}))), r = [...e.configured].map(([e, t]) => ({
+		purpose: e,
+		...t
+	})), i = [...e.declared].map(([e, t]) => ({
+		purpose: e,
+		lifetimeMs: t
+	}));
+	return e.signed.clear(), e.presented.clear(), {
+		signed: t,
+		configured: r,
+		presented: n,
+		declared: i
+	};
+}, d = (e) => {
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e) o(t, n.purpose).set(n.fingerprint, n.closesAt);
+	a().windows = t;
+}, f = (e, t, n) => {
+	o(a().windows, e).set(r(t), n);
+}, p = () => {
+	let e = a();
+	e.windows = /* @__PURE__ */ new Map(), e.signed.clear(), e.configured.clear(), e.presented.clear(), e.declared.clear();
+}, m = (e, t, n = Date.now()) => {
+	let i = a().windows.get(e)?.get(r(t));
+	return i == null || n <= i;
+}, h = (t) => e("sha256").update(t).digest(), g = (e, t, i, s) => {
+	let c = h(t), l = i !== "" && n(c, h(i)), u = s !== void 0 && s !== "" && s !== i && n(c, h(s));
+	return l ? !0 : !u || !m(e, s) ? !1 : (o(a().presented, e).set(r(s), Date.now()), !0);
+};
+//#endregion
+export { d as applySecretWindows, g as bearerMatches, p as clearSecretWindows, u as drainSecretActivity, l as noteConfigured, s as noteSigned, c as noteSigningLifetime, m as previousAccepted, r as secretFingerprint, f as setSecretWindow };

package/dist/serverErrorBus.js

@@ -0,0 +1,15 @@
+//#region src/serverErrorBus.ts
+var e = (e) => {
+	let t = e.error, n = t instanceof Error ? t.name : typeof t?._tag == "string" ? String(t._tag) : "Error", r = [e.name === void 0 ? e.source : `${e.source} '${e.name}'`, ...typeof e.fields?.runId == "string" ? [`run ${e.fields.runId}`] : []].join(", "), i = /* @__PURE__ */ Error(`[message withheld: ${r} is declared encrypted — read it where the run is shown]`);
+	i.name = n;
+	let a = t instanceof Error && typeof t.stack == "string" ? t.stack : "", o = a.search(/^\s+at /m);
+	return i.stack = `${n}: ${i.message}${o === -1 ? "" : `\n${a.slice(o)}`}`, i;
+}, t = /* @__PURE__ */ new Set(), n = (e) => {
+	for (let n of t) try {
+		n(e);
+	} catch {}
+}, r = (e) => (t.add(e), () => {
+	t.delete(e);
+});
+//#endregion
+export { n as publishServerError, r as subscribeServerErrors, e as withheldServerError };

package/dist/serviceCall.js

@@ -0,0 +1,14 @@
+import { Schema as e } from "effect";
+//#region src/serviceCall.ts
+var t = class extends e.TaggedError()("ApiUnavailable", {
+	api: e.String,
+	tag: e.String,
+	reason: e.Literals([
+		"timeout",
+		"transport",
+		"closed"
+	]),
+	message: e.String
+}) {}, n = (e) => typeof e == "object" && !!e && e._tag === "ApiUnavailable";
+//#endregion
+export { t as ApiUnavailable, n as isApiUnavailable };

package/dist/session.d.ts

@@ -1,5 +1,12 @@
 import { Schema } from 'effect';
 
+/** Replace every recorded window with the boot's computed ones. */
+export declare const applySecretWindows: (windows: ReadonlyArray<{
+    readonly purpose: string;
+    readonly fingerprint: string;
+    readonly closesAt: number | null;
+}>) => void;
+
 /**
  * Fail-closed check that a real session secret is configured. Throws a plain
  * `Error` (a fatal boot condition, not a wire error) when
@@ -8,6 +15,14 @@ import { Schema } from 'effect';
  */
 export declare const assertProductionSessionSecret: (env?: NodeJS.ProcessEnv) => void;
 
+/**
+ * Does a presented bearer token match the current value or — during a
+ * rotation, while its window is open — the previous one? Both comparisons run,
+ * in constant time over digests, so neither which one matched nor a length
+ * leaks through timing. A match on the previous value is recorded.
+ */
+export declare const bearerMatches: (purpose: string, presented: string, current: string, previous?: string) => boolean;
+
 /**
  * Build a `Set-Cookie` header value. Pure helper — the caller adds it
  * to the actual HTTP response. Used by the framework's login route
@@ -46,6 +61,9 @@ export declare const checkBearer: (headers: Readonly<Record<string, string | und
     readonly openWhenUnset?: boolean;
 }) => boolean;
 
+/** Forget every record — a test seam, and a process that stops verifying. */
+export declare const clearSecretWindows: () => void;
+
 /** Key id assigned to `VOLTRO_SESSION_SECRET_PREVIOUS` when no explicit
  *  `VOLTRO_SESSION_KID_PREVIOUS` is set. The kid is a non-secret label —
  *  rotation works with just the `_PREVIOUS` secret var. */
@@ -56,6 +74,9 @@ export declare const DEFAULT_PREVIOUS_SESSION_KID: "k-previous";
  *  string produce the same label the resolver would. */
 export declare const DEFAULT_SESSION_KID: "k0";
 
+/** What this process signed, holds and was presented since the last drain — for the boot to persist. */
+export declare const drainSecretActivity: () => SecretActivity;
+
 /** A keyed signing secret. `kid` is stamped into the payload on sign and
  *  matched on verify; it's an opaque, non-secret label (e.g. `'2026-06'`). */
 export declare interface KeyedSecret {
@@ -68,6 +89,31 @@ export declare interface KeyedSecret {
  *  placeholders, not real secrets. */
 export declare const MIN_SESSION_SECRET_LENGTH: 32;
 
+/** A resolver read `current` (and, during a rotation, `previous`) for `purpose`. */
+export declare const noteConfigured: (purpose: string, current: string, previous: string | undefined) => void;
+
+/**
+ * A signer signed something under `secret` that is valid until `expiresAtMs`
+ * (undefined: no expiry). The lifetime it signed with is recorded too: it is
+ * what bounds the tokens signed before anything was recorded.
+ */
+export declare const noteSigned: (purpose: string, secret: string, expiresAtMs: number | undefined, now?: number) => void;
+
+/**
+ * A configured signer can sign `purpose` tokens valid for up to `lifetimeMs` —
+ * declared when it is built, before it signs anything. The first rotation after
+ * an upgrade needs it: the previous value signed tokens nothing recorded, and
+ * only the configuration says how long they can live.
+ */
+export declare const noteSigningLifetime: (purpose: string, lifetimeMs: number) => void;
+
+/**
+ * Is this previous value still accepted? Yes while its window is open, and
+ * when no window is recorded for it (nothing has decided otherwise). No once
+ * the latest expiry it signed has passed, or a compromise closed it.
+ */
+export declare const previousAccepted: (purpose: string, previous: string, now?: number) => boolean;
+
 /**
  * Read a cookie value by name from a `Cookie:` header string.
  * Returns undefined if the cookie isn't present.
@@ -123,6 +169,37 @@ export declare const resolveSessionSecret: () => string;
  */
 export declare const resolveSessionSecrets: () => SessionSecrets;
 
+/** What a process recorded since the last drain: signatures, configured values, previous bearer values that answered. */
+export declare interface SecretActivity {
+    /** Per purpose and fingerprint: the latest expiry signed and the longest lifetime signed with. */
+    readonly signed: ReadonlyArray<{
+        readonly purpose: string;
+        readonly fingerprint: string;
+        readonly signedUntil: number;
+        readonly longestMs: number;
+    }>;
+    /** Per purpose: the fingerprints of the current and the previous value this process holds. */
+    readonly configured: ReadonlyArray<{
+        readonly purpose: string;
+        readonly current: string;
+        readonly previous: string | null;
+    }>;
+    /** Per purpose: when a previous bearer value last answered. */
+    readonly presented: ReadonlyArray<{
+        readonly purpose: string;
+        readonly fingerprint: string;
+        readonly at: number;
+    }>;
+    /** Per purpose: the longest lifetime a configured signer declared. */
+    readonly declared: ReadonlyArray<{
+        readonly purpose: string;
+        readonly lifetimeMs: number;
+    }>;
+}
+
+/** A non-reversible name for a secret value: 16 hex of an HMAC under a fixed label. */
+export declare const secretFingerprint: (value: string) => string;
+
 /**
  * The cookie the framework's own session strategy writes and reads.
  *
@@ -166,15 +243,16 @@ export declare const SESSION_PAYLOAD_VERSION: 2;
  */
 export declare const sessionExpiryFromHeaders: (headers: Record<string, string | undefined>) => number | undefined;
 
-export declare type SessionPayload = typeof SessionPayload_2.Type;
+export declare type SessionPayload = typeof SessionPayloadSchema.Type;
 
-declare const SessionPayload_2: Schema.Struct<{
+declare const SessionPayloadSchema: Schema.Struct<{
     /** Payload format version. Required and pinned — see the header. */
     readonly v: Schema.Literal<2>;
     /** WHO, never WHAT-THEY-MAY-DO. `SubjectIdentity` has no `scopes` field. */
     readonly subject: Schema.Union<readonly [Schema.Struct<{
         readonly type: Schema.Literal<"user">;
         readonly id: Schema.String;
+        readonly kind: Schema.optional<Schema.Literal<"guest">>;
         readonly tenantId: Schema.String;
         readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
     }>, Schema.Struct<{
@@ -201,9 +279,9 @@ declare const SessionPayload_2: Schema.Struct<{
     }>, Schema.Struct<{
         readonly type: Schema.Literal<"service">;
         readonly id: Schema.String;
+        readonly service: Schema.String;
         readonly tenantId: Schema.Null;
         readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
-        readonly service: Schema.String;
     }>]>;
     /** Unix seconds when this session expires. Verify rejects past expiry. */
     readonly exp: Schema.Number;
@@ -217,8 +295,6 @@ declare const SessionPayload_2: Schema.Struct<{
     readonly kid: Schema.optional<Schema.String>;
 }>;
 
-declare type SessionPayload = typeof SessionPayload_2.Type;
-
 /** The resolved secret set: `current` always signs; `previous` is accepted
  *  on verify during a rotation window. */
 export declare interface SessionSecrets {
@@ -242,6 +318,9 @@ export declare interface SetCookieOptions {
     readonly domain?: string;
 }
 
+/** Record one window by value — a test seam and a single-process embedder's. */
+export declare const setSecretWindow: (purpose: string, previous: string, closesAt: number | null) => void;
+
 export declare interface SignOptions {
     /** TTL in seconds. Defaults to 7 days. */
     readonly ttlSeconds?: number;
@@ -278,6 +357,9 @@ export declare const signSession: (subject: Subject | SubjectIdentity, secret: s
 
 declare const Subject: Schema.Union<readonly [Schema.Struct<{
     readonly type: Schema.Literal<"user">;
+    /** A guest has a stable identity but has not linked a registered account.
+     * This identity mark survives session signing; it never grants authority. */
+    readonly kind: Schema.optional<Schema.Literal<"guest">>;
     readonly id: Schema.String;
     readonly tenantId: Schema.String;
     readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
@@ -339,6 +421,7 @@ declare type Subject = typeof Subject.Type;
 declare const SubjectIdentity: Schema.Union<readonly [Schema.Struct<{
     readonly type: Schema.Literal<"user">;
     readonly id: Schema.String;
+    readonly kind: Schema.optional<Schema.Literal<"guest">>;
     readonly tenantId: Schema.String;
     readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
 }>, Schema.Struct<{
@@ -381,9 +464,9 @@ declare const SubjectIdentity: Schema.Union<readonly [Schema.Struct<{
 }>, Schema.Struct<{
     readonly type: Schema.Literal<"service">;
     readonly id: Schema.String;
+    readonly service: Schema.String;
     readonly tenantId: Schema.Null;
     readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
-    readonly service: Schema.String;
 }>]>;
 
 declare type SubjectIdentity = typeof SubjectIdentity.Type;