@voltro/protocol 0.33.0 → 0.35.0

package/dist/rest.d.ts

@@ -24,11 +24,19 @@ declare interface ActionProcedureDescriptor<Name extends string, Input extends S
     readonly target: TargetSpec | ReadonlyArray<TargetSpec> | undefined;
     /** Declarative authorization guard(s) — enforced before the executor runs,
      *  failing with a typed `ScopeError`. Absent → no framework-level authz. */
-    readonly guards: Guards | undefined;
+    readonly guards: DeclaredAccess | undefined;
+    /** The declared reason this procedure needs NO authorization check —
+     *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
+     *  the only two shapes `security.defaultDeny` accepts. */
+    readonly openAccess: string | undefined;
     /** Opt this action into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this action into the auto-synthesized agent toolset (innovation/07). */
     readonly exposeAsTool: ExposeAsTool | undefined;
+    /** Require a SECOND human to approve before this action takes effect. The gate
+     *  runs in the dispatch spine after `guards:` and BEFORE the executor's
+     *  external I/O — the only point at which nothing has happened yet. */
+    readonly requiresApproval: AnyApprovalPolicy | undefined;
     /** True when the procedure is kept OFF the wire — no client-group entry and no
      *  route in dev or serve. See `internal` on the definer's options. */
     /**
@@ -56,6 +64,13 @@ declare interface ActionProcedureDescriptor<Name extends string, Input extends S
     readonly internal: boolean | undefined;
 }
 
+/** The erased policy a descriptor carries (input generic dropped). */
+declare interface AnyApprovalPolicy {
+    readonly approvers: Guards;
+    readonly expiresIn?: string;
+    readonly reason?: string;
+}
+
 /** A guard is either a scope check or a relationship check. */
 declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input>;
 
@@ -66,6 +81,18 @@ declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<
  */
 export declare const collectPublicApiRoutes: (entries: ReadonlyArray<PublicApiEntry>) => ReadonlyArray<RestRouteDescriptor<Record<string, unknown>, unknown>>;
 
+/**
+ * What a descriptor CARRIES: the author's guards, or the erased form of their
+ * `openAccess:` decision — never both.
+ *
+ * The option a user writes is still `Guards` (an `OpenAccessSpec` is not
+ * something to hand-write into `guards:`; there is one spelling for the
+ * decision and it is the `openAccess:` field). The DESCRIPTOR type is wider
+ * because that is where the normalised decision lands, and because every
+ * enforcement path reads the descriptor's array and nothing else.
+ */
+declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec>;
+
 /**
  * Identity helper that fixes the descriptor's types (like `defineAction` /
  * `definePlugin`). Returns its argument unchanged at runtime; exists for
@@ -94,7 +121,8 @@ export declare const derivePublicPath: (tag: string, spec: PublicApiSpec) => str
  * side effect when the method isn't its own — so probing the group in order and
  * taking the FIRST non-405 result yields the route that owns the request's
  * method. This is what lets the standard GET + POST on one resource path
- * coexist: the serve pipeline mounts ONE dispatcher per path (the underlying
+ * coexist: the runtime's rpc server (`rpcServer.ts`, started by both boot
+ * paths) mounts ONE dispatcher per path (the underlying
  * router rejects two mounts on the same `(method, path)`). A single-route group
  * returns that route's result directly (its own 405 included); when no route in
  * the group owns the method, the last 405 stands.
@@ -131,13 +159,32 @@ declare interface GuardSpec<Input = unknown> {
      *  scope); `'any'` = OR (hold at least one). Ignored for a single scope. */
     readonly mode?: 'all' | 'any';
     /**
-     * PURE `input → resource id` extractor for a row/resource-scoped guard.
-     * Browser-safe (no DB, no server import) — exactly like `target.identify`.
-     * The framework passes the extracted id to a resource-aware scope resolver
-     * (a future ReBAC / `accessPolicy()` resolver) so the check can be scoped to
-     * THAT resource. With only the default (subject-global) resolver installed
-     * the id is advisory and the guard checks the subject's global scopes. Omit
-     * for a plain subject-scope guard.
+     * PURE `input → resource id` extractor. Browser-safe (no DB, no server
+     * import) — exactly like `target.identify`. Omit for a plain subject-scope
+     * guard.
+     *
+     * **On a `GuardSpec` this id is ADVISORY.** A scope guard answers "what may
+     * this subject do at all", against the subject's global scope set; the id is
+     * carried for logging and for a future subject-scope resolver that narrows by
+     * resource. It does not, on its own, make the check per-resource.
+     *
+     * **If your authority is per-resource, you want {@link PolicyGuardSpec}, not
+     * this field** — `guards: [{ action, resourceType, resource }]`, backed by
+     * `defineResourcePolicy` + a tuple source you register. That is built, wired
+     * on both boot paths, fail-closed without a resolver, and documented under
+     * *Authentication → Authorization*. An app whose relationships already live
+     * in its own tables (a `teamMembers` row, say) registers its own tuple source
+     * rather than copying data across; see `policyGuardResolver.ts`.
+     *
+     * That paragraph is here because its absence cost a consumer their access
+     * gate. This comment used to describe the resolver as "a future ReBAC /
+     * `accessPolicy()` resolver" — written before the ReBAC path shipped and
+     * never updated. They read the type, quoted the sentence, concluded there was
+     * "nothing in between" declaring an untruth and turning the gate off, and set
+     * `security: { defaultDeny: false }` on an app with 565 undecided procedures.
+     * The capability they needed was two fields away. A doc comment that says
+     * "future" about something shipped is not a small inaccuracy: it is the only
+     * thing a careful reader has, and it argued them out of a feature.
      */
     readonly resource?: (input: Input) => string | undefined;
 }
@@ -224,11 +271,19 @@ declare interface MutationProcedureDescriptor<Name extends string, Input extends
     /** Declarative authorization guard(s) — enforced before the transaction
      *  opens, failing with a typed `ScopeError`. Absent → no framework-level
      *  authz (author gates in-handler, or the mutation is unguarded). */
-    readonly guards: Guards | undefined;
+    readonly guards: DeclaredAccess | undefined;
+    /** The declared reason this procedure needs NO authorization check —
+     *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
+     *  the only two shapes `security.defaultDeny` accepts. */
+    readonly openAccess: string | undefined;
     /** Opt this mutation into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this mutation into the auto-synthesized agent toolset (innovation/07). */
     readonly exposeAsTool: ExposeAsTool | undefined;
+    /** Require a SECOND human to approve before this mutation takes effect. The
+     *  gate runs in the dispatch spine after `guards:` and before the transaction
+     *  opens; the pending intent is a durable `_voltro_approvals` row. */
+    readonly requiresApproval: AnyApprovalPolicy | undefined;
     /** True when the procedure is kept OFF the wire — no client-group entry and no
      *  route in dev or serve. See `internal` on the definer's options. */
     /**
@@ -271,6 +326,27 @@ declare interface NestedTargetFields<Input = unknown> {
     readonly match?: ((value: unknown, input: Input) => boolean) | undefined;
 }
 
+/**
+ * The runtime-erased form of a procedure's `openAccess:` — a DECLARED decision
+ * that this procedure needs no authorization check, and the reason.
+ *
+ * It is a guard entry rather than a bare descriptor field on purpose. Every
+ * enforcement path in the framework — `servePipeline`'s `enforceGuards`,
+ * `bindStream`, `bindEvent`, `@voltro/testing`'s `invoke` — is handed the
+ * `guards` ARRAY and nothing else. A decision that does not live in that array
+ * is invisible to all of them, so "guarded" and "deliberately open" would be
+ * distinguishable in the source and identical at the point that enforces.
+ *
+ * It always passes. The value is the WHY, and the why is the point: it is what
+ * a reviewer reads, what `voltro doctor` prints, and what makes an open
+ * procedure a decision somebody made rather than a field somebody forgot.
+ */
+declare interface OpenAccessSpec {
+    /** Why this procedure is callable without an authorization check. Non-empty
+     *  by construction — `defineQuery` & co. refuse an empty reason. */
+    readonly open: string;
+}
+
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 declare interface PluginHttpRoute {
     /** HTTP method, or `'*'` for any (the handler decides). */
@@ -279,6 +355,42 @@ declare interface PluginHttpRoute {
      *  any sub-path (`/_voltro/storage/abc123`). */
     readonly path: string;
     readonly handle: (req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+    /**
+     * Opt this route's path OUT of the listener's cross-site origin check.
+     *
+     * Every state-changing request (anything but GET/HEAD/OPTIONS) is
+     * origin-checked by default, because the default assumption has to be that a
+     * route can be reached with the browser's ambient session cookie — and a
+     * route that can is CSRF-reachable. Declaring `'exempt'` is a claim that this
+     * route CANNOT be: its caller must present something a browser will not
+     * attach cross-site.
+     *
+     * The test to apply, and it is the only one:
+     *
+     *   > If an attacker's page makes a browser send this request with the
+     *   > victim's cookies attached, does anything happen?
+     *
+     * If the answer is "no, the request still needs a signature / a bearer token
+     * / a signed ticket the attacker does not have", the route is exempt.
+     * Otherwise it is not, and no amount of "but it is behind the dashboard"
+     * makes it so.
+     *
+     * The first-party exemptions and why each qualifies:
+     *   - `@voltro/plugin-sso-saml` `/saml` — the IdP delivers the assertion as a
+     *     genuine cross-site browser form POST; authority is the signed
+     *     SAMLResponse, not the cookie.
+     *   - `@voltro/plugin-storage` `/…/upload` + `/…/upload/resumable` — a signed
+     *     upload ticket in the query string, and the route ships its own CORS
+     *     allowlist because a cross-origin upload is the point.
+     *   - `@voltro/plugin-billing` `/billing/webhook` — an HMAC-verified provider
+     *     callback.
+     *   - `@voltro/plugin-scim` `/scim/v2` — bearer-only, refuses to mount without
+     *     a token.
+     *
+     * Granularity is the PATH PREFIX the route mounts, not the sub-path its
+     * handler branches on: exempting `/saml` exempts `POST /saml/anything`.
+     */
+    readonly originGuard?: 'exempt';
 }
 
 declare interface PluginHttpRouteRequest {
@@ -341,6 +453,22 @@ declare interface PluginHttpRouteRequest {
      * this store reads them.
      */
     readonly store?: DataStore;
+    /**
+     * The client address, resolved through the app's `security.trustedProxies`
+     * policy — the SAME value the rate limiter, the geo-block and every audit row
+     * use (`resolveClientAddress`). Use this, never `headers['x-forwarded-for']`.
+     *
+     * `x-forwarded-for` is a request header: any client can write it. Reading it
+     * raw means a caller picks the IP that lands in your `sessions.ipAddress`
+     * column, which is the one field a breach investigation leans on. Three
+     * first-party routes did exactly that until SEC-8 was extended down to this
+     * surface. The resolution here ignores the header entirely unless a trusted
+     * proxy is declared, and then believes only the hops that are one.
+     *
+     * `undefined` when the socket address is unavailable (a unix socket, an
+     * in-process test harness that constructs the request by hand).
+     */
+    readonly remoteAddr?: string | undefined;
 }
 
 /**
@@ -554,7 +682,11 @@ declare interface QueryProcedureDescriptor<Name extends string, Input extends Sc
     readonly cache: QueryCacheConfig | undefined;
     /** Declarative authorization guard(s) — enforced before the executor runs,
      *  failing with a typed `ScopeError`. Absent → no framework-level authz. */
-    readonly guards: Guards | undefined;
+    readonly guards: DeclaredAccess | undefined;
+    /** The declared reason this procedure needs NO authorization check —
+     *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
+     *  the only two shapes `security.defaultDeny` accepts. */
+    readonly openAccess: string | undefined;
     /** Opt this query into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this query into the auto-synthesized agent toolset (innovation/07). */

package/dist/rest.js

@@ -1,5 +1,5 @@
-import { a as e, i as t, o as n, r, t as i } from "./serverErrorBus-C3JTqgIc.js";
-import { s as a } from "./auth-CXMrvPyX.js";
+import { u as e } from "./auth-B6YZuSBr.js";
+import { a as t, i as n, o as r, r as i, t as a } from "./serverErrorBus-BeN9pOpY.js";
 import { Effect as o, Schema as s } from "effect";
 //#region src/publicApi.ts
 var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.path ?? `/${t.version ?? "v1"}/${e.replace(/\./g, "/")}`, u = (e, t, n) => {
@@ -110,7 +110,7 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 				}, f);
 				p = t.value;
 			}
-			let m = l.resolveSubject ? await l.resolveSubject(s.headers) : a(s.headers["x-tenant"] ?? null), h = {
+			let m = l.resolveSubject ? await l.resolveSubject(s.headers) : e(s.headers["x-tenant"] ?? null), h = {
 				subject: m,
 				headers: s.headers,
 				store: l.store
@@ -119,9 +119,9 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 				let t = await e(h);
 				if (t) return v(t.status, { error: t.message }, f);
 			}
-			let g = l.idempotency, y = g && C.has(c.method) ? s.headers[g.header.toLowerCase()] : void 0, b = g && y ? n(m.tenantId, c.method, c.path) : "";
+			let g = l.idempotency, y = g && C.has(c.method) ? s.headers[g.header.toLowerCase()] : void 0, b = g && y ? r(m.tenantId, c.method, c.path) : "";
 			if (g && y) {
-				let e = await r(g.store, b, y, g.ttlMs, Date.now());
+				let e = await i(g.store, b, y, g.ttlMs, Date.now());
 				if (e.kind === "replay") return v(e.response.status, e.response.body, {
 					...f,
 					"Idempotency-Replayed": "true"
@@ -129,23 +129,23 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 				if (e.kind === "conflict") return v(409, { error: "A request with this Idempotency-Key is already being processed" }, f);
 			}
 			try {
-				let t = await c.handler(p, h);
-				if (_(t)) return {
+				let e = await c.handler(p, h);
+				if (_(e)) return {
 					status: 200,
 					headers: f,
-					stream: t.stream
+					stream: e.stream
 				};
-				let n = await o.runPromise(d(t));
-				return g && y && await e(g.store, b, y, {
+				let n = await o.runPromise(d(e));
+				return g && y && await t(g.store, b, y, {
 					status: 200,
 					body: n
 				}, Date.now()), v(200, n, f);
 			} catch (e) {
-				if (g && y && await t(g.store, b, y), typeof e == "object" && e && typeof e.status == "number") {
+				if (g && y && await n(g.store, b, y), typeof e == "object" && e && typeof e.status == "number") {
 					let t = e;
 					return v(t.status, { error: t.message ?? "Error" }, f);
 				}
-				return i({
+				return a({
 					error: e,
 					source: "rest",
 					name: `${c.method} ${c.path}`,

package/dist/serverErrorBus-BeN9pOpY.js

@@ -0,0 +1,43 @@
+//#region src/idempotency.ts
+var e = (e, t, n) => `${e ?? "(global)"}|${t.toUpperCase()}|${n}`, t = (e, t, n) => `${e ?? "(global)"}|${t ?? "(anon)"}|WS|${n}`, n = async (e, t, n, r, i) => {
+	let a = await e.claim(t, n, i, r);
+	return a === "claimed" ? { kind: "fresh" } : a.status === "completed" && a.response ? {
+		kind: "replay",
+		response: a.response
+	} : { kind: "conflict" };
+}, r = (e, t, n, r, i) => e.complete(t, n, r, i), i = (e, t, n) => e.release(t, n), a = () => {
+	let e = /* @__PURE__ */ new Map(), t = (e, t) => `${e}\u0000${t}`;
+	return {
+		get: async (n, r) => e.get(t(n, r)) ?? null,
+		claim: async (n, r, i, a) => {
+			let o = e.get(t(n, r));
+			return o && i - o.createdAt < a ? o : (e.set(t(n, r), {
+				scope: n,
+				key: r,
+				status: "in_flight",
+				response: null,
+				createdAt: i
+			}), "claimed");
+		},
+		complete: async (n, r, i, a) => {
+			e.set(t(n, r), {
+				scope: n,
+				key: r,
+				status: "completed",
+				response: i,
+				createdAt: a
+			});
+		},
+		release: async (n, r) => {
+			e.delete(t(n, r));
+		}
+	};
+}, o = /* @__PURE__ */ new Set(), s = (e) => {
+	for (let t of o) try {
+		t(e);
+	} catch {}
+}, c = (e) => (o.add(e), () => {
+	o.delete(e);
+});
+//#endregion
+export { r as a, t as c, i, c as n, e as o, n as r, a as s, s as t };

package/dist/session.d.ts

@@ -74,6 +74,13 @@ export declare const MIN_SESSION_SECRET_LENGTH: 32;
  */
 export declare const readCookie: (header: string | undefined, name: string) => string | undefined;
 
+/**
+ * Reset the once-per-process warning latch. Tests only — the latch is what
+ * makes the diagnostic readable in production and unobservable in a second
+ * test case.
+ */
+export declare const resetSessionSecretWarningLatch: () => void;
+
 /**
  * The same resolution as `resolveSessionSecrets`, but yielding `undefined`
  * instead of throwing when `VOLTRO_SESSION_SECRET` is unset.
@@ -118,9 +125,22 @@ export declare const resolveSessionSecrets: () => SessionSecrets;
  */
 export declare const SESSION_COOKIE_NAME: string;
 
+/**
+ * The session payload format this build mints and accepts.
+ *
+ * Bumped when the payload's MEANING changes, not when a field is added — a
+ * reader that ignores an unknown field is fine; a reader that would take a
+ * field to mean something it no longer means is not. `2` dropped `scopes`:
+ * a `1` payload asserted authority, and honouring that assertion is the defect.
+ */
+export declare const SESSION_PAYLOAD_VERSION: 2;
+
 /**
  * The verified expiry of the session cookie in `headers`, in unix SECONDS, or
- * `undefined` when there is no session or it does not verify.
+ * `undefined` when there is no session cookie, it does not verify, or no
+ * session secret is configured (that last case is logged once, loudly — see
+ * the branch below; a security bound that is absent must not be absent
+ * SILENTLY).
  *
  * It VERIFIES rather than decoding. An unverified read would be worse than
  * nothing here: the value bounds how long a subscription may live, so a client
@@ -138,33 +158,32 @@ export declare const sessionExpiryFromHeaders: (headers: Record<string, string |
 export declare type SessionPayload = typeof SessionPayload_2.Type;
 
 declare const SessionPayload_2: Schema.Struct<{
+    /** Payload format version. Required and pinned — see the header. */
+    v: Schema.Literal<[2]>;
+    /** WHO, never WHAT-THEY-MAY-DO. `SubjectIdentity` has no `scopes` field. */
     subject: Schema.Union<[Schema.Struct<{
-        type: Schema.Literal<["user"]>;
         id: typeof Schema.String;
+        type: Schema.Literal<["user"]>;
         tenantId: typeof Schema.String;
-        scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
         metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
     }>, Schema.Struct<{
-        type: Schema.Literal<["apiKey"]>;
         id: typeof Schema.String;
+        type: Schema.Literal<["apiKey"]>;
         tenantId: typeof Schema.String;
-        scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
         metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
     }>, Schema.Struct<{
-        type: Schema.Literal<["serviceAccount"]>;
         id: typeof Schema.String;
+        type: Schema.Literal<["serviceAccount"]>;
         tenantId: typeof Schema.String;
-        scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
         metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
     }>, Schema.Struct<{
         type: Schema.Literal<["anonymous"]>;
         id: typeof Schema.Null;
         tenantId: Schema.NullOr<typeof Schema.String>;
     }>, Schema.Struct<{
-        type: Schema.Literal<["system"]>;
         id: typeof Schema.String;
+        type: Schema.Literal<["system"]>;
         tenantId: typeof Schema.Null;
-        scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
         metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
     }>]>;
     /** Unix seconds when this session expires. Verify rejects past expiry. */
@@ -226,8 +245,17 @@ export declare interface SignOptions {
  * forge a new one without the secret. `HttpOnly` blocks JS access for
  * defence-in-depth; the verify side doesn't care whether the client
  * could read it.
+ *
+ * **It REFUSES a subject carrying `scopes`.** A cookie cannot carry authority
+ * (see the header), and the two alternatives to refusing are both worse than a
+ * thrown error at the one call site per app that mints a session. Signing them
+ * would reintroduce exactly the defect. Dropping them silently would change
+ * what a caller may do with no error, no log line, and no diff — an
+ * authorization change disguised as a no-op, discovered later as "permissions
+ * randomly stopped working". So: throw, name the subject, name the seam that
+ * replaces it.
  */
-export declare const signSession: (subject: Subject, secret: string | KeyedSecret, options?: SignOptions) => string;
+export declare const signSession: (subject: Subject | SubjectIdentity, secret: string | KeyedSecret, options?: SignOptions) => string;
 
 declare const Subject: Schema.Union<[Schema.Struct<{
     type: Schema.Literal<["user"]>;
@@ -261,6 +289,34 @@ declare const Subject: Schema.Union<[Schema.Struct<{
 
 declare type Subject = typeof Subject.Type;
 
+declare const SubjectIdentity: Schema.Union<[Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["user"]>;
+    tenantId: typeof Schema.String;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["apiKey"]>;
+    tenantId: typeof Schema.String;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["serviceAccount"]>;
+    tenantId: typeof Schema.String;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["anonymous"]>;
+    id: typeof Schema.Null;
+    tenantId: Schema.NullOr<typeof Schema.String>;
+}>, Schema.Struct<{
+    id: typeof Schema.String;
+    type: Schema.Literal<["system"]>;
+    tenantId: typeof Schema.Null;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>]>;
+
+declare type SubjectIdentity = typeof SubjectIdentity.Type;
+
 /**
  * Constant-time string equality via `timingSafeEqual`. Returns false fast
  * on a length mismatch (the lengths aren't secret); only equal-length inputs
@@ -280,7 +336,11 @@ export declare interface VerifyOptions {
  *  the sliding-window threshold — the caller re-issues the cookie so an
  *  active user never gets logged out mid-session. */
 export declare interface VerifyResult {
-    readonly subject: Subject;
+    /** IDENTITY, not a Subject. The narrow type is the guarantee stated at the
+     *  type level: nothing downstream can read authority out of a cookie,
+     *  because the value it gets back has no field for it. It is still assignable
+     *  to `Subject` wherever one is wanted — a Subject with no scopes. */
+    readonly subject: SubjectIdentity;
     readonly renew: boolean;
     /** The key id that verified the value (current or previous). */
     readonly kid: string;
@@ -293,18 +353,19 @@ export declare interface VerifyResult {
 }
 
 /**
- * Verify a session cookie value. Returns the decoded Subject on success,
- * null on any failure (malformed, signature mismatch, expired). Never
- * throws — callers shouldn't have to wrap this in try/catch.
+ * Verify a session cookie value. Returns the decoded identity on success,
+ * null on any failure (malformed, signature mismatch, expired, or a payload
+ * from a superseded format version). Never throws — callers shouldn't have to
+ * wrap this in try/catch.
  *
  * Uses `timingSafeEqual` for the signature comparison so attackers
  * can't recover bytes one-at-a-time via response-time analysis.
  *
  * This is the single-secret entry point and stays a pure
- * `Subject | null`. Use `verifySessionKeyed` for the multi-key +
+ * `SubjectIdentity | null`. Use `verifySessionKeyed` for the multi-key +
  * sliding-window result shape.
  */
-export declare const verifySession: (cookieValue: string, secret: string) => Subject | null;
+export declare const verifySession: (cookieValue: string, secret: string) => SubjectIdentity | null;
 
 /**
  * Multi-key + sliding-window verify. Tries `secrets.current` first, then