@voltro/protocol 0.33.0 → 0.34.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
@@ -224,11 +251,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 +306,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 +335,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 +433,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 +662,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

package/dist/session.js

@@ -1,22 +1,24 @@
-import { i as e } from "./auth-CXMrvPyX.js";
-import { Schema as t } from "effect";
-import { createHmac as n, timingSafeEqual as r } from "node:crypto";
+import { U as e, s as t, v as n } from "./auth-B6YZuSBr.js";
+import { Schema as r } from "effect";
+import { createHmac as i, timingSafeEqual as a } from "node:crypto";
+import { createLogger as o } from "@voltro/logger";
 //#region src/session.ts
-var i = t.Struct({
-	subject: e,
-	exp: t.Number,
-	iat: t.Number,
-	kid: t.optional(t.String)
-}), a = "k0", o = "k-previous", s = () => {
+var s = o({ scope: "@voltro/protocol:session" }), c = 2, l = r.Struct({
+	v: r.Literal(2),
+	subject: t,
+	exp: r.Number,
+	iat: r.Number,
+	kid: r.optional(r.String)
+}), u = "k0", d = "k-previous", f = () => {
 	throw Error("VOLTRO_SESSION_SECRET is not set. It signs and verifies session cookies, and the framework refuses to invent one at this point: a fixed fallback would be readable by anyone with the source, making every session forgeable. `voltro dev` mints a project-local value into .env.local on boot; for a deployment, generate one with `voltro secret generate session`.");
-}, c = () => process.env.VOLTRO_SESSION_SECRET ?? s(), l = () => d() ?? { current: {
-	kid: u(),
-	secret: c()
-} }, u = () => process.env.VOLTRO_SESSION_KID ?? "k0", d = () => {
+}, p = () => process.env.VOLTRO_SESSION_SECRET ?? f(), m = () => g() ?? { current: {
+	kid: h(),
+	secret: p()
+} }, h = () => process.env.VOLTRO_SESSION_KID ?? "k0", g = () => {
 	let e = process.env.VOLTRO_SESSION_SECRET;
 	if (e === void 0 || e === "") return;
 	let t = {
-		kid: u(),
+		kid: h(),
 		secret: e
 	}, n = process.env.VOLTRO_SESSION_SECRET_PREVIOUS;
 	return n ? {
@@ -26,51 +28,54 @@ var i = t.Struct({
 			secret: n
 		}
 	} : { current: t };
-}, f = 32, p = (e = process.env) => {
+}, _ = 32, v = (e = process.env) => {
 	let t = e.VOLTRO_SESSION_SECRET;
 	if (t === void 0 || t === "") throw Error("VOLTRO_SESSION_SECRET is not set — refusing to serve. It signs session cookies, and there is no fallback: a built-in one would be readable by anyone with the source. Generate one with `voltro secret generate session`. (`voltro dev` mints a project-local value automatically; a deployment needs its own.)");
 	if (t.length < 32) throw Error(`VOLTRO_SESSION_SECRET is only ${t.length} chars — too short for a session secret (need >= 32). This looks like a placeholder. Generate a real one with \`voltro secret generate session\`.`);
-}, m = t.encodeSync(i), h = t.decodeUnknownSync(i), g = (e) => (typeof e == "string" ? Buffer.from(e, "utf8") : e).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""), _ = (e) => {
+}, y = r.encodeSync(l), b = r.decodeUnknownSync(l), x = (e) => (typeof e == "string" ? Buffer.from(e, "utf8") : e).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""), S = (e) => {
 	let t = e.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - e.length % 4) % 4);
 	return Buffer.from(t, "base64");
-}, v = 3600 * 24 * 7, y = .7, b = (e, t) => g(n("sha256", t).update(e).digest()), x = (e) => typeof e == "string" ? {
+}, C = 3600 * 24 * 7, w = .7, T = (e, t) => x(i("sha256", t).update(e).digest()), E = (e) => typeof e == "string" ? {
 	kid: "k0",
 	secret: e
-} : e, S = (e, t, n = {}) => {
-	let r = x(t);
-	if (!r.secret) throw Error("signSession: secret must be a non-empty string");
-	let i = n.ttlSeconds ?? v, a = Math.floor((n.now ?? Date.now)() / 1e3), o = {
-		subject: e,
-		exp: a + i,
-		iat: a,
-		...typeof t == "string" ? {} : { kid: r.kid }
-	}, s = g(JSON.stringify(m(o)));
-	return `${s}.${b(s, r.secret)}`;
-}, C = (e, t, i, a) => {
-	let o = n("sha256", i).update(e).digest(), s = _(t);
-	if (s.length !== o.length || !r(s, o)) return null;
+} : e, D = (t, r, i = {}) => {
+	let a = E(r);
+	if (!a.secret) throw Error("signSession: secret must be a non-empty string");
+	let o = e(t);
+	if (o.length > 0) throw Error(`signSession: refusing to mint a session cookie for a ${t.type} subject carrying ${o.length} scope(s) (${o.slice(0, 5).join(", ")}). A session cookie carries IDENTITY only — authority is resolved per request, so that removing a role takes effect on the session that already exists instead of in up to 7 days. Mint the session from the identity and move the scopes into the auth.resolveScopes resolver, which runs on every request and can be invalidated the moment a role changes.`);
+	let s = i.ttlSeconds ?? C, c = Math.floor((i.now ?? Date.now)() / 1e3), l = {
+		v: 2,
+		subject: n(t),
+		exp: c + s,
+		iat: c,
+		...typeof r == "string" ? {} : { kid: a.kid }
+	}, u = x(JSON.stringify(y(l)));
+	return `${u}.${T(u, a.secret)}`;
+}, O = (e, t, n, r) => {
+	let o = i("sha256", n).update(e).digest(), s = S(t);
+	if (s.length !== o.length || !a(s, o)) return null;
 	try {
-		let t = _(e).toString("utf8"), n = h(JSON.parse(t));
-		return n.exp < Math.floor(a() / 1e3) ? null : n;
+		let t = S(e).toString("utf8"), n = b(JSON.parse(t));
+		return n.exp < Math.floor(r() / 1e3) ? null : n;
 	} catch {
 		return null;
 	}
-}, w = (e, t) => {
+}, k = (e, t) => {
 	if (!e || !t) return null;
 	let n = e.indexOf(".");
 	if (n <= 0 || n === e.length - 1) return null;
-	let r = C(e.slice(0, n), e.slice(n + 1), t, Date.now);
+	let r = O(e.slice(0, n), e.slice(n + 1), t, Date.now);
 	return r ? r.subject : null;
-}, T = (e, t, n = {}) => {
+}, A = (e, t, n = {}) => {
 	if (!e) return null;
 	let r = e.indexOf(".");
 	if (r <= 0 || r === e.length - 1) return null;
 	let i = e.slice(0, r), a = e.slice(r + 1), o = t.previous ? [t.current, t.previous] : [t.current], s = n.now ?? Date.now;
 	for (let e of o) {
 		if (!e.secret) continue;
-		let t = C(i, a, e.secret, s);
+		let t = O(i, a, e.secret, s);
 		if (!t) continue;
-		let r = n.renewFraction ?? y, o = Math.floor(s() / 1e3), c = t.exp - t.iat, l = t.iat + c * r;
+		let r = n.renewFraction ?? w, o = Math.floor(s() / 1e3), c = t.exp - t.iat, l = t.iat + c * r;
 		return {
 			subject: t.subject,
 			renew: o >= l,
@@ -80,14 +85,14 @@ var i = t.Struct({
 		};
 	}
 	return null;
-}, E = (e, t) => {
-	let n = Buffer.from(e, "utf8"), i = Buffer.from(t, "utf8");
-	return n.length === i.length && r(n, i);
-}, D = (e, t, n) => {
+}, j = (e, t) => {
+	let n = Buffer.from(e, "utf8"), r = Buffer.from(t, "utf8");
+	return n.length === r.length && a(n, r);
+}, M = (e, t, n) => {
 	if (!t || t.length === 0) return n?.openWhenUnset === !0;
 	let r = e.authorization ?? e.Authorization;
-	return !r || !r.startsWith("Bearer ") ? !1 : E(r.slice(7).trim(), t);
-}, O = (e, t) => {
+	return !r || !r.startsWith("Bearer ") ? !1 : j(r.slice(7).trim(), t);
+}, N = (e, t) => {
 	if (e) for (let n of e.split(";")) {
 		let e = n.indexOf("=");
 		if (e < 0 || n.slice(0, e).trim() !== t) continue;
@@ -99,18 +104,26 @@ var i = t.Struct({
 			return r;
 		}
 	}
-}, k = (e, t, n = {}) => {
+}, P = (e, t, n = {}) => {
 	let r = [`${e}=${encodeURIComponent(t)}`];
 	if (r.push(`Path=${n.path ?? "/"}`), n.maxAgeSeconds !== void 0 && r.push(`Max-Age=${n.maxAgeSeconds}`), r.push("HttpOnly"), n.httpOnly === !1) {
 		let e = r.indexOf("HttpOnly");
 		e >= 0 && r.splice(e, 1);
 	}
 	return r.push(`SameSite=${n.sameSite ?? "Lax"}`), (n.secure ?? !0) && r.push("Secure"), n.domain && r.push(`Domain=${n.domain}`), r.join("; ");
-}, A = process.env.VOLTRO_SESSION_COOKIE ?? "voltro:session", j = (e) => {
-	let t = O(e.cookie ?? e.Cookie, A);
+}, F = process.env.VOLTRO_SESSION_COOKIE ?? "voltro:session", I = (e) => {
+	let t = N(e.cookie ?? e.Cookie, F);
 	if (!t) return;
-	let n = d();
-	if (n) return T(t, n)?.exp;
+	let n = g();
+	if (!n) {
+		R();
+		return;
+	}
+	return A(t, n)?.exp;
+}, L = !1, R = () => {
+	L || (L = !0, s.error("a `voltro:session` cookie was presented but VOLTRO_SESSION_SECRET is not set — the session cannot be verified, so no credential-expiry bound is imposed and realtime subscriptions on this connection will not be cut off when the session expires. Set VOLTRO_SESSION_SECRET (`voltro secret generate session`); `voltro dev` mints one, `voltro serve` refuses to boot without one.", { cookieName: F }));
+}, z = () => {
+	L = !1;
 };
 //#endregion
-export { o as DEFAULT_PREVIOUS_SESSION_KID, a as DEFAULT_SESSION_KID, f as MIN_SESSION_SECRET_LENGTH, A as SESSION_COOKIE_NAME, p as assertProductionSessionSecret, k as buildSetCookie, D as checkBearer, O as readCookie, d as resolveOptionalSessionSecrets, c as resolveSessionSecret, l as resolveSessionSecrets, j as sessionExpiryFromHeaders, S as signSession, E as timingSafeStringEqual, w as verifySession, T as verifySessionKeyed };
+export { d as DEFAULT_PREVIOUS_SESSION_KID, u as DEFAULT_SESSION_KID, _ as MIN_SESSION_SECRET_LENGTH, F as SESSION_COOKIE_NAME, c as SESSION_PAYLOAD_VERSION, v as assertProductionSessionSecret, P as buildSetCookie, M as checkBearer, N as readCookie, z as resetSessionSecretWarningLatch, g as resolveOptionalSessionSecrets, p as resolveSessionSecret, m as resolveSessionSecrets, I as sessionExpiryFromHeaders, D as signSession, j as timingSafeStringEqual, k as verifySession, A as verifySessionKeyed };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "The Voltro wire + plugin contract — defineQuery/Mutation/Action/Stream, definePlugin, sessions / JWT / API-keys, and the RPC protocol.",
   "keywords": [
     "voltro",
@@ -54,7 +54,8 @@
   },
   "dependencies": {
     "@effect/sql": "^0.52.0",
-    "@voltro/database": "0.33.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/logger": "0.34.0",
     "jose": "^6.2.4"
   },
   "peerDependencies": {