@voltro/protocol 0.4.0 → 0.6.0

package/dist/rest.d.ts

@@ -15,6 +15,9 @@ declare interface ActionProcedureDescriptor<Name extends string, Input extends S
     readonly exposeAsTool: ExposeAsTool | undefined;
 }
 
+/** A guard is either a scope check or a relationship check. */
+declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input>;
+
 /**
  * Project every descriptor carrying a `publicApi` annotation into a REST
  * route, in stable (path) order. The boot layer feeds these straight into
@@ -77,7 +80,7 @@ declare interface ExposeAsToolSpec {
 
 /** One or more declarative guards on a descriptor. All must pass (AND across
  *  entries; `mode` controls AND/OR WITHIN one entry's scope array). */
-declare type Guards<Input = unknown> = ReadonlyArray<GuardSpec<Input>>;
+declare type Guards<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input>>;
 
 declare interface GuardSpec<Input = unknown> {
     /** Required permission scope(s). A single string, or an array combined by
@@ -253,6 +256,36 @@ declare interface PluginHttpRouteResult {
     readonly headers?: Record<string, string>;
 }
 
+/**
+ * A relationship (ReBAC) guard — "may this subject perform ACTION on THIS row?"
+ *
+ * The scope guard above answers "what may this subject do at all"; this answers
+ * "on which row". Both live in the same `guards:` array on purpose, because the
+ * alternative is what apps actually built: a hand-maintained map from rpc tag →
+ * policy rule, installed as an interceptor. That map is FAIL-OPEN BY OMISSION —
+ * add an rpc, forget the entry, and it is silently unguarded. A declaration on
+ * the descriptor cannot be forgotten for an rpc that exists, because it IS the
+ * rpc.
+ *
+ * Browser-safe by the same construction as `GuardSpec`: strings plus a PURE
+ * `resource` extractor. Resolution — reading relationship tuples, applying the
+ * policy's `implies` closure — happens server-side through the registered
+ * policy resolver. With no resolver registered the check FAILS CLOSED: an
+ * unanswerable authorization question is a denial, never a pass.
+ *
+ * Because it is data, the same declaration compiles into the capability
+ * manifest the client reads, so a UI gate and the server check cannot drift.
+ */
+declare interface PolicyGuardSpec<Input = unknown> {
+    /** The action to authorize, as named in the resource policy's `actions`. */
+    readonly action: string;
+    /** Which registered resource policy governs the check. */
+    readonly resourceType: string;
+    /** PURE `input → resource id`. Returning undefined DENIES — an unidentifiable
+     *  resource is not a reason to skip the check. */
+    readonly resource: (input: Input) => string | undefined;
+}
+
 /** A descriptor kind that can be projected to REST (streams are not, in v1). */
 export declare type PublicApiDescriptor = QueryProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | MutationProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | ActionProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All>;
 

package/dist/rest.js

@@ -1,4 +1,4 @@
-import { a as e, i as t, o as n, r, t as i } from "./serverErrorBus-0wjvKwGO.js";
+import { a as e, i as t, o as n, r, t as i } from "./serverErrorBus-B3hDwGoL.js";
 import { s as a } from "./auth-DCE6m7Bo.js";
 import { Effect as o, Schema as s } from "effect";
 //#region src/publicApi.ts

package/dist/session.d.ts

@@ -2,9 +2,9 @@ import { Schema } from 'effect';
 
 /**
  * Fail-closed check that a real session secret is configured. Throws a plain
- * `Error` (a fatal boot condition, not a wire error) when `NODE_ENV` is
- * `'production'` and `VOLTRO_SESSION_SECRET` is missing, the dev fallback, or
- * too short. No-op otherwise. Idempotent — safe to call from every prod entry.
+ * `Error` (a fatal boot condition, not a wire error) when
+ * `VOLTRO_SESSION_SECRET` is missing or too short. Idempotent — safe to call
+ * from every serve entry.
  */
 export declare const assertProductionSessionSecret: (env?: NodeJS.ProcessEnv) => void;
 
@@ -45,9 +45,9 @@ export declare interface KeyedSecret {
     readonly secret: string;
 }
 
-/** Minimum length we accept for a production session secret. 32 bytes of
- *  entropy is the floor for HMAC-SHA256; shorter values are almost always
- *  hand-typed placeholders, not real secrets. */
+/** Minimum length we accept for a session secret. 32 bytes of entropy is the
+ *  floor for HMAC-SHA256; shorter values are almost always hand-typed
+ *  placeholders, not real secrets. */
 export declare const MIN_SESSION_SECRET_LENGTH: 32;
 
 /**
@@ -56,14 +56,27 @@ export declare const MIN_SESSION_SECRET_LENGTH: 32;
  */
 export declare const readCookie: (header: string | undefined, name: string) => string | undefined;
 
-/** Resolve the HMAC session secret with the dev fallback applied. */
+/**
+ * The same resolution as `resolveSessionSecrets`, but yielding `undefined`
+ * instead of throwing when `VOLTRO_SESSION_SECRET` is unset.
+ *
+ * This exists for callers that were GIVEN a secret explicitly and consult the
+ * environment only for adornment — the `kid` to stamp, and any `previous` key
+ * to also accept during a rotation. For them an unconfigured environment is
+ * simply "no rotation set up", not an error: they already hold everything
+ * needed to sign and verify. Making them go through the throwing resolver
+ * would turn a working explicit-secret setup into a boot failure.
+ */
+export declare const resolveOptionalSessionSecrets: () => SessionSecrets | undefined;
+
+/** Resolve the HMAC session secret. Throws when unset — there is no fallback. */
 export declare const resolveSessionSecret: () => string;
 
 /**
  * Resolve the keyed session-secret set for multi-key rotation.
  *
- *   - `current` is built from `VOLTRO_SESSION_SECRET` (dev fallback
- *     applied), keyed `VOLTRO_SESSION_KID` (defaults to `'k0'`).
+ *   - `current` is built from `VOLTRO_SESSION_SECRET` (required — throws
+ *     when unset), keyed `VOLTRO_SESSION_KID` (defaults to `'k0'`).
  *   - `previous` is built from `VOLTRO_SESSION_SECRET_PREVIOUS`, keyed
  *     `VOLTRO_SESSION_KID_PREVIOUS` (defaults to `'k-previous'` — the kid
  *     is a non-secret label, so rotation needs only the secret var).
@@ -257,6 +270,4 @@ export declare const verifySession: (cookieValue: string, secret: string) => Sub
  */
 export declare const verifySessionKeyed: (cookieValue: string, secrets: SessionSecrets, options?: VerifyOptions) => VerifyResult | null;
 
-export declare const VOLTRO_DEV_SESSION_SECRET: "voltro-dev-session-secret-32b-DO-NOT-USE-IN-PROD";
-
 export { }

package/dist/session.js

@@ -7,65 +7,70 @@ var i = t.Struct({
 	exp: t.Number,
 	iat: t.Number,
 	kid: t.optional(t.String)
-}), a = "k0", o = "k-previous", s = "voltro-dev-session-secret-32b-DO-NOT-USE-IN-PROD", c = () => process.env.VOLTRO_SESSION_SECRET ?? "voltro-dev-session-secret-32b-DO-NOT-USE-IN-PROD", l = () => {
-	let e = {
-		kid: process.env.VOLTRO_SESSION_KID ?? "k0",
-		secret: process.env.VOLTRO_SESSION_SECRET ?? "voltro-dev-session-secret-32b-DO-NOT-USE-IN-PROD"
-	}, t = process.env.VOLTRO_SESSION_SECRET_PREVIOUS;
-	return t ? {
-		current: e,
+}), a = "k0", o = "k-previous", s = () => {
+	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 = () => {
+	let e = process.env.VOLTRO_SESSION_SECRET;
+	if (e === void 0 || e === "") return;
+	let t = {
+		kid: u(),
+		secret: e
+	}, n = process.env.VOLTRO_SESSION_SECRET_PREVIOUS;
+	return n ? {
+		current: t,
 		previous: {
 			kid: process.env.VOLTRO_SESSION_KID_PREVIOUS ?? "k-previous",
-			secret: t
+			secret: n
 		}
-	} : { current: e };
-}, u = 32, d = (e = process.env) => {
-	if (e.NODE_ENV !== "production") return;
+	} : { current: t };
+}, f = 32, p = (e = process.env) => {
 	let t = e.VOLTRO_SESSION_SECRET;
-	if (t === void 0 || t === "") throw Error("VOLTRO_SESSION_SECRET is not set. In production the framework refuses to boot rather than sign session cookies with the PUBLIC dev fallback secret (which would let anyone forge any user's session). Set VOLTRO_SESSION_SECRET to a high-entropy value (>= 32 chars). Generate one with `voltro secret generate session`.");
-	if (t === "voltro-dev-session-secret-32b-DO-NOT-USE-IN-PROD") throw Error("VOLTRO_SESSION_SECRET is set to the built-in dev fallback secret, which is PUBLIC in the framework source. Set a real, high-entropy secret in production. Generate one with `voltro secret generate session`.");
-	if (t.length < 32) throw Error(`VOLTRO_SESSION_SECRET is only ${t.length} chars — too short for a production session secret (need >= 32). This looks like a placeholder. Generate a real one with \`voltro secret generate session\`.`);
-}, f = t.encodeSync(i), p = t.decodeUnknownSync(i), m = (e) => (typeof e == "string" ? Buffer.from(e, "utf8") : e).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""), h = (e) => {
+	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) => {
 	let t = e.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - e.length % 4) % 4);
 	return Buffer.from(t, "base64");
-}, g = 3600 * 24 * 7, _ = .7, v = (e, t) => m(n("sha256", t).update(e).digest()), y = (e) => typeof e == "string" ? {
+}, v = 3600 * 24 * 7, y = .7, b = (e, t) => g(n("sha256", t).update(e).digest()), x = (e) => typeof e == "string" ? {
 	kid: "k0",
 	secret: e
-} : e, b = (e, t, n = {}) => {
-	let r = y(t);
+} : 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 ?? g, a = Math.floor((n.now ?? Date.now)() / 1e3), o = {
+	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 = m(JSON.stringify(f(o)));
-	return `${s}.${v(s, r.secret)}`;
-}, x = (e, t, i, a) => {
-	let o = n("sha256", i).update(e).digest(), s = h(t);
+	}, 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;
 	try {
-		let t = h(e).toString("utf8"), n = p(JSON.parse(t));
+		let t = _(e).toString("utf8"), n = h(JSON.parse(t));
 		return n.exp < Math.floor(a() / 1e3) ? null : n;
 	} catch {
 		return null;
 	}
-}, S = (e, t) => {
+}, w = (e, t) => {
 	if (!e || !t) return null;
 	let n = e.indexOf(".");
 	if (n <= 0 || n === e.length - 1) return null;
-	let r = x(e.slice(0, n), e.slice(n + 1), t, Date.now);
+	let r = C(e.slice(0, n), e.slice(n + 1), t, Date.now);
 	return r ? r.subject : null;
-}, C = (e, t, n = {}) => {
+}, T = (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 = x(i, a, e.secret, s);
+		let t = C(i, a, e.secret, s);
 		if (!t) continue;
-		let r = n.renewFraction ?? _, o = Math.floor(s() / 1e3), c = t.exp - t.iat, l = t.iat + c * r;
+		let r = n.renewFraction ?? y, o = Math.floor(s() / 1e3), c = t.exp - t.iat, l = t.iat + c * r;
 		return {
 			subject: t.subject,
 			renew: o >= l,
@@ -75,14 +80,14 @@ var i = t.Struct({
 		};
 	}
 	return null;
-}, w = (e, t) => {
+}, E = (e, t) => {
 	let n = Buffer.from(e, "utf8"), i = Buffer.from(t, "utf8");
 	return n.length === i.length && r(n, i);
-}, T = (e, t) => {
+}, D = (e, t) => {
 	if (!t || t.length === 0) return !0;
 	let n = e.authorization ?? e.Authorization;
-	return !n || !n.startsWith("Bearer ") ? !1 : w(n.slice(7).trim(), t);
-}, E = (e, t) => {
+	return !n || !n.startsWith("Bearer ") ? !1 : E(n.slice(7).trim(), t);
+}, O = (e, t) => {
 	if (e) for (let n of e.split(";")) {
 		let e = n.indexOf("=");
 		if (e < 0 || n.slice(0, e).trim() !== t) continue;
@@ -94,7 +99,7 @@ var i = t.Struct({
 			return r;
 		}
 	}
-}, D = (e, t, n = {}) => {
+}, k = (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");
@@ -103,4 +108,4 @@ var i = t.Struct({
 	return r.push(`SameSite=${n.sameSite ?? "Lax"}`), (n.secure ?? !0) && r.push("Secure"), n.domain && r.push(`Domain=${n.domain}`), r.join("; ");
 };
 //#endregion
-export { o as DEFAULT_PREVIOUS_SESSION_KID, a as DEFAULT_SESSION_KID, u as MIN_SESSION_SECRET_LENGTH, s as VOLTRO_DEV_SESSION_SECRET, d as assertProductionSessionSecret, D as buildSetCookie, T as checkBearer, E as readCookie, c as resolveSessionSecret, l as resolveSessionSecrets, b as signSession, w as timingSafeStringEqual, S as verifySession, C as verifySessionKeyed };
+export { o as DEFAULT_PREVIOUS_SESSION_KID, a as DEFAULT_SESSION_KID, f as MIN_SESSION_SECRET_LENGTH, p as assertProductionSessionSecret, k as buildSetCookie, D as checkBearer, O as readCookie, d as resolveOptionalSessionSecrets, c as resolveSessionSecret, l as resolveSessionSecrets, S as signSession, E as timingSafeStringEqual, w as verifySession, T as verifySessionKeyed };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The Voltro wire + plugin contract — defineQuery/Mutation/Action/Stream, definePlugin, sessions / JWT / API-keys, and the RPC protocol.",
   "keywords": [
     "voltro",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@effect/sql": "^0.51.1",
-    "@voltro/database": "0.4.0",
+    "@voltro/database": "0.6.0",
     "jose": "^6.2.3"
   },
   "peerDependencies": {