@voltro/protocol 0.25.0 → 0.27.0

package/dist/apikey.d.ts

@@ -150,15 +150,28 @@ declare interface AuthStrategyInput {
     readonly store?: DataStore;
 }
 
-/** A strategy's verdict on a request.
- *  - `matched`: this strategy claims the request; here's the Subject.
- *  - `skip`: not my request (e.g. cookie absent); try next strategy.
- *  - `failed`: this IS my request BUT validation failed (signature
- *    mismatch, expired JWT). Composer bails to anonymous + logs;
- *    silently falling through would mask attacks. */
 declare type StrategyResolution = {
     readonly kind: 'matched';
     readonly subject: Subject;
+    /**
+     * When this credential expires, in unix SECONDS — if the strategy knows.
+     *
+     * The strategy is the ONLY place in the system that has verified the token
+     * and holds its `exp`, and until now it could not say so. The credential
+     * bound therefore read one source: the `voltro:session` cookie. For an app
+     * authenticating with Bearer JWTs — six of our own catalog strategies do,
+     * and every one of them verifies an `exp` — it was silently `undefined`,
+     * so "a subscription can no longer outlive the credential that authorized
+     * it" was a no-op that read as a guarantee.
+     *
+     * A reporter found it by expecting black screens an hour after a deploy
+     * and getting none. Their conclusion is the one to keep: the guarantee was
+     * not false, it was scoped to an auth shape the sentence did not name.
+     *
+     * Optional, and absent still means no bound — the failure direction is the
+     * behaviour that already existed.
+     */
+    readonly credentialExpiresAt?: number;
 } | {
     readonly kind: 'skip';
 } | {

package/dist/{auth-BPdyOBsd.js → auth-CXMrvPyX.js}

@@ -64,7 +64,13 @@ var r = t.Record({
 	};
 	for (let n of e) {
 		let e = await n.resolve(i);
-		if (e.kind === "matched") return t?.resolveScopes === void 0 ? e.subject : b(e.subject, await t.resolveScopes(e.subject, i));
+		if (e.kind === "matched") {
+			let n = t?.resolveScopes === void 0 ? e.subject : b(e.subject, await t.resolveScopes(e.subject, i));
+			return e.credentialExpiresAt === void 0 ? { subject: n } : {
+				subject: n,
+				credentialExpiresAt: e.credentialExpiresAt
+			};
+		}
 		if (e.kind === "failed") {
 			t?.onStrategyFailed?.({
 				strategyId: n.id,
@@ -73,10 +79,10 @@ var r = t.Record({
 			break;
 		}
 	}
-	if (t?.fallback) return t.fallback(i);
+	if (t?.fallback) return { subject: await t.fallback(i) };
 	let a = i.headers["x-tenant"] ?? null;
 	if (a === null && t?.anonymousTenantRequired === !0) throw new S({ reason: "tenant required (x-tenant header missing)" });
-	return d(a);
+	return { subject: d(a) };
 }, S = class extends t.TaggedError()("Unauthenticated", { reason: t.optional(t.String) }) {}, C = (e, t) => {
 	if (e.type === "anonymous") throw new S(t === void 0 ? {} : { reason: t });
 };

package/dist/index.d.ts

@@ -38,6 +38,28 @@ export declare interface ActionProcedureDescriptor<Name extends string, Input ex
     readonly exposeAsTool: ExposeAsTool | 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. */
+    /**
+     * Replace a PLUGIN route that answers to this same tag.
+     *
+     * Without it, a user route and a plugin route sharing a tag is a hard error,
+     * and correctly so — two handlers behind one name is not a thing a caller can
+     * reason about. But refusing is the wrong answer when the app deliberately
+     * wants its own version: the two escapes available otherwise are to rename
+     * your procedure (so the split runs along "who built it" rather than along a
+     * domain boundary) or to `alias` the whole plugin away (same, one level up).
+     * For a frontend developer that is the worst possible partition.
+     *
+     * A reporter wanted exactly this: adopt `@voltro/plugin-notifications`, whose
+     * surface is richer than theirs, add `archive`/`unarchive` beside it — which
+     * already composes, since the collision check compares FULL tags and not
+     * prefixes — and replace `markRead`, because theirs maintains archive state.
+     *
+     * Explicit, never inferred. Silently letting the app win would mean a plugin
+     * upgrade that adds a route could shadow an app procedure with no diff to
+     * read; declaring it makes the intent reviewable and puts the override in the
+     * file that performs it.
+     */
+    readonly overridesPlugin: boolean | undefined;
     readonly internal: boolean | undefined;
 }
 
@@ -414,7 +436,7 @@ export declare const composeAuthStrategies: (strategies: ReadonlyArray<AuthStrat
      * class this repo has been bitten by most.
      */
     readonly getStore?: () => unknown;
-}) => ((input: AuthStrategyInput) => Promise<Subject>);
+}) => ((input: AuthStrategyInput) => Promise<SubjectResolution>);
 
 /**
  * Compose a list of Effect-native interceptors into ONE function the
@@ -488,6 +510,28 @@ export declare interface ConnectionInfoValue {
      *  (every `useMutation` call does). Read by `bindMutation` to dedupe a retried
      *  mutation. Absent for callers that don't send it. */
     readonly idempotencyKey?: string;
+    /**
+     * Unix-SECONDS expiry of the credential that authorized this call, when it
+     * has one. Absent for credentials with no expiry (anonymous, a non-expiring
+     * strategy) — and absent means "no bound", so the failure direction is the
+     * behaviour that already existed.
+     *
+     * It exists for LONG-LIVED work. A request is checked once and is over in
+     * milliseconds, so expiry never mattered; an event subscription is a
+     * standing state that reconnects forever by design, so one opened a minute
+     * before the token dies would otherwise keep delivering for days on a
+     * credential that is long gone. `bindEvent` ends the stream here, and
+     * `useEvent`'s existing reconnect immediately re-opens it — which is a NEW
+     * request, so it re-resolves the subject and re-runs the guards for real.
+     * That is what makes the bound seamless rather than a disconnection the app
+     * has to handle: still entitled, it continues; no longer entitled, it fails
+     * loudly instead of quietly continuing.
+     *
+     * This bounds EXPIRY, not revocation. A role revoked mid-session is not
+     * observed until the credential runs out — do not let this field grow a
+     * doc comment that claims otherwise.
+     */
+    readonly credentialExpiresAt?: number;
 }
 
 /** The two credential shapes a connection can hold. `oauth2` = an
@@ -694,6 +738,9 @@ export declare const defineAction: <const Name extends string, Input extends Sch
      * need to check who is asking.
      */
     readonly internal?: boolean;
+    /** Replace a PLUGIN route answering to this same tag. Explicit, never
+     *  inferred — see `overridesPlugin` on the descriptor. */
+    readonly overridesPlugin?: boolean;
 }) => ActionProcedureDescriptor<Name, Input, Output, Error>;
 
 /**
@@ -825,6 +872,9 @@ export declare const defineMutation: <const Name extends string, Input extends S
      * need to check who is asking.
      */
     readonly internal?: boolean;
+    /** Replace a PLUGIN route answering to this same tag. Explicit, never
+     *  inferred — see `overridesPlugin` on the descriptor. */
+    readonly overridesPlugin?: boolean;
 }) => MutationProcedureDescriptor<Name, Input, Output, Error>;
 
 /**
@@ -919,6 +969,9 @@ export declare const defineQuery: <const Name extends string, Input extends Sche
      * need to check who is asking.
      */
     readonly internal?: boolean;
+    /** Replace a PLUGIN route answering to this same tag. Explicit, never
+     *  inferred — see `overridesPlugin` on the descriptor. */
+    readonly overridesPlugin?: boolean;
 }) => QueryProcedureDescriptor<Name, Input, Output, Error>;
 
 /**
@@ -935,6 +988,22 @@ export declare const defineStream: <const Name extends string, Input extends Sch
      *  dev or serve. Same contract as `internal` on the other definers; a stream
      *  without it would be a hole in the same boundary. */
     readonly internal?: boolean;
+    /** Replace a PLUGIN route answering to this same tag. Explicit, never
+     *  inferred — see `overridesPlugin` on the descriptor. */
+    readonly overridesPlugin?: boolean;
+    /**
+     * WHO MAY LISTEN.
+     *
+     * A stream is the same long-lived grant a subscription is, and it was the one
+     * primitive that could not express authorization at all — queries, mutations
+     * and actions carry `guards:`, streams did not, so any protection lived
+     * hand-written inside an executor where nothing could verify it existed.
+     *
+     * Checked at subscribe and re-checked before every element, so a resource
+     * un-shared or a membership ended stops the stream rather than continuing to
+     * push. Same shape and same semantics as a query's.
+     */
+    readonly guards?: Guards;
 }) => StreamProcedureDescriptor<Name, Input, Element, Error>;
 
 export declare interface DeleteTarget<Input = unknown> extends NestedTargetFields<Input> {
@@ -1269,11 +1338,6 @@ export declare interface EventWebhookSpec {
     readonly description?: string;
     /** Payload schema version. Bump when subscribers must adapt. Default 1. */
     readonly version?: number;
-    /** Default retry policy for new subscriptions (`{ attempts, backoffMs }`). */
-    readonly retry?: {
-        readonly attempts?: number;
-        readonly backoffMs?: number;
-    };
     /** Shared ceiling across ALL deliveries of this event — the runaway-emit
      *  guard. Over-limit deliveries are deferred, never dropped. */
     readonly rateLimit?: {
@@ -1597,6 +1661,28 @@ export declare interface MutationProcedureDescriptor<Name extends string, Input
     readonly exposeAsTool: ExposeAsTool | 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. */
+    /**
+     * Replace a PLUGIN route that answers to this same tag.
+     *
+     * Without it, a user route and a plugin route sharing a tag is a hard error,
+     * and correctly so — two handlers behind one name is not a thing a caller can
+     * reason about. But refusing is the wrong answer when the app deliberately
+     * wants its own version: the two escapes available otherwise are to rename
+     * your procedure (so the split runs along "who built it" rather than along a
+     * domain boundary) or to `alias` the whole plugin away (same, one level up).
+     * For a frontend developer that is the worst possible partition.
+     *
+     * A reporter wanted exactly this: adopt `@voltro/plugin-notifications`, whose
+     * surface is richer than theirs, add `archive`/`unarchive` beside it — which
+     * already composes, since the collision check compares FULL tags and not
+     * prefixes — and replace `markRead`, because theirs maintains archive state.
+     *
+     * Explicit, never inferred. Silently letting the app win would mean a plugin
+     * upgrade that adds a route could shadow an app procedure with no diff to
+     * read; declaring it makes the intent reviewable and puts the override in the
+     * file that performs it.
+     */
+    readonly overridesPlugin: boolean | undefined;
     readonly internal: boolean | undefined;
 }
 
@@ -2533,6 +2619,28 @@ export declare interface QueryProcedureDescriptor<Name extends string, Input ext
     readonly exposeAsTool: ExposeAsTool | 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. */
+    /**
+     * Replace a PLUGIN route that answers to this same tag.
+     *
+     * Without it, a user route and a plugin route sharing a tag is a hard error,
+     * and correctly so — two handlers behind one name is not a thing a caller can
+     * reason about. But refusing is the wrong answer when the app deliberately
+     * wants its own version: the two escapes available otherwise are to rename
+     * your procedure (so the split runs along "who built it" rather than along a
+     * domain boundary) or to `alias` the whole plugin away (same, one level up).
+     * For a frontend developer that is the worst possible partition.
+     *
+     * A reporter wanted exactly this: adopt `@voltro/plugin-notifications`, whose
+     * surface is richer than theirs, add `archive`/`unarchive` beside it — which
+     * already composes, since the collision check compares FULL tags and not
+     * prefixes — and replace `markRead`, because theirs maintains archive state.
+     *
+     * Explicit, never inferred. Silently letting the app win would mean a plugin
+     * upgrade that adds a route could shadow an app procedure with no diff to
+     * read; declaring it makes the intent reviewable and puts the override in the
+     * file that performs it.
+     */
+    readonly overridesPlugin: boolean | undefined;
     readonly internal: boolean | undefined;
 }
 
@@ -2858,15 +2966,28 @@ export declare const setPolicyGuardResolver: (resolver: PolicyGuardResolver | un
  */
 export declare const setResourceScopeResolver: (resolver: ResourceScopeResolver | undefined) => void;
 
-/** A strategy's verdict on a request.
- *  - `matched`: this strategy claims the request; here's the Subject.
- *  - `skip`: not my request (e.g. cookie absent); try next strategy.
- *  - `failed`: this IS my request BUT validation failed (signature
- *    mismatch, expired JWT). Composer bails to anonymous + logs;
- *    silently falling through would mask attacks. */
 export declare type StrategyResolution = {
     readonly kind: 'matched';
     readonly subject: Subject;
+    /**
+     * When this credential expires, in unix SECONDS — if the strategy knows.
+     *
+     * The strategy is the ONLY place in the system that has verified the token
+     * and holds its `exp`, and until now it could not say so. The credential
+     * bound therefore read one source: the `voltro:session` cookie. For an app
+     * authenticating with Bearer JWTs — six of our own catalog strategies do,
+     * and every one of them verifies an `exp` — it was silently `undefined`,
+     * so "a subscription can no longer outlive the credential that authorized
+     * it" was a no-op that read as a guarantee.
+     *
+     * A reporter found it by expecting black screens an hour after a deploy
+     * and getting none. Their conclusion is the one to keep: the guarantee was
+     * not false, it was scoped to an auth shape the sentence did not name.
+     *
+     * Optional, and absent still means no bound — the failure direction is the
+     * behaviour that already existed.
+     */
+    readonly credentialExpiresAt?: number;
 } | {
     readonly kind: 'skip';
 } | {
@@ -2890,6 +3011,10 @@ export declare interface StreamProcedureDescriptor<Name extends string, Input ex
     /** True when the stream is kept OFF the wire — no client-group entry and no
      *  route in dev or serve. See `internal` on the definer's options. */
     readonly internal: boolean | undefined;
+    /** WHO MAY LISTEN. Checked at subscribe AND re-checked before every element,
+     *  the same as a query's — a stream is a long-lived grant and the scopes that
+     *  justified it can be withdrawn while it is still open. */
+    readonly guards: Guards | undefined;
 }
 
 export declare const streamToRpc: <Name extends string, Input extends Schema.Schema.Any, Element extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: StreamProcedureDescriptor<Name, Input, Element, Err>, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Element, Schema.Schema.All>, typeof Schema.Never, never>;
@@ -2926,6 +3051,20 @@ export declare const Subject: Schema.Union<[Schema.Struct<{
 
 export declare type Subject = typeof Subject.Type;
 
+/** A strategy's verdict on a request.
+ *  - `matched`: this strategy claims the request; here's the Subject.
+ *  - `skip`: not my request (e.g. cookie absent); try next strategy.
+ *  - `failed`: this IS my request BUT validation failed (signature
+ *    mismatch, expired JWT). Composer bails to anonymous + logs;
+ *    silently falling through would mask attacks. */
+/** What the composed chain returns: the subject, plus what it learned about the
+ *  credential's lifetime on the way. */
+export declare interface SubjectResolution {
+    readonly subject: Subject;
+    /** Unix SECONDS, when the matching strategy could tell. */
+    readonly credentialExpiresAt?: number;
+}
+
 /** The subject's scopes (empty for anonymous / unscoped). */
 export declare const subjectScopes: (subject: Subject) => ReadonlyArray<string>;
 
@@ -2934,36 +3073,36 @@ export declare class SubjectService extends SubjectService_base {
 
 declare const SubjectService_base: Context.TagClass<SubjectService, "@voltro/Subject", {
     readonly id: string;
-    readonly tenantId: string;
     readonly type: "user";
+    readonly tenantId: string;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
 } | {
     readonly id: string;
-    readonly tenantId: string;
     readonly type: "apiKey";
+    readonly tenantId: string;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
 } | {
     readonly id: string;
-    readonly tenantId: string;
     readonly type: "serviceAccount";
+    readonly tenantId: string;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
 } | {
     readonly id: null;
-    readonly tenantId: string | null;
     readonly type: "anonymous";
+    readonly tenantId: string | null;
 } | {
     readonly id: string;
-    readonly tenantId: null;
     readonly type: "system";
+    readonly tenantId: null;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { C as e, D as t, E as n, O as r, S as i, T as a, _ as o, a as ee, b as te, c as ne, d as re, f as ie, g as ae, h as oe, i as se, l as ce, m as le, n as ue, o as de, p as s, r as fe, s as pe, t as me, u as he, v as ge, w as _e, x as ve, y as ye } from "./serverErrorBus-C3JTqgIc.js";
-import { a as be, c as xe, d as Se, f as Ce, i as we, l as Te, n as Ee, o as De, p as Oe, r as ke, s as Ae, t as je, u as Me } from "./auth-BPdyOBsd.js";
+import { a as be, c as xe, d as Se, f as Ce, i as we, l as Te, n as Ee, o as De, p as Oe, r as ke, s as Ae, t as je, u as Me } from "./auth-CXMrvPyX.js";
 import { Context as Ne, Layer as Pe, Schema as c } from "effect";
 import { Rpc as l } from "@effect/rpc";
 //#region src/rowPatch.ts
@@ -77,10 +77,19 @@ var Fe = c.Union(c.String, c.Number), u = c.Record({
 	error: c.Unknown,
 	revision: c.optional(c.Number)
 })), Ve = (e) => e.internal !== !0, g = (e) => {
+	if (Array.isArray(e.guards) && e.guards.length === 0) throw Error(`${e.name}: \`guards: []\` is empty, so it enforces nothing — but it reads\n  at the call site as if this procedure were protected. Omit the field for an
+  unguarded procedure, or list the scopes required to call it.`);
+	let t = typeof e.source == "string" ? [e.source] : Array.isArray(e.source) ? e.source : void 0;
+	if (t !== void 0 && (t.length === 0 || t.some((e) => String(e).trim() === ""))) throw Error(`${e.name}: \`source\` is empty, so this query declares reactivity and\n  subscribes to nothing — it serves one snapshot and never updates again,
+  which is indistinguishable from "nothing changed". Name the table(s) it
+  reads, or omit \`source\` for a non-reactive query.`);
 	if (e.internal !== !0) return e;
-	let t = [e.publicApi === void 0 ? void 0 : "publicApi", e.exposeAsTool === void 0 ? void 0 : "exposeAsTool"].filter((e) => e !== void 0);
-	if (t.length === 0) return e;
-	throw Error(`${e.name}: \`internal: true\` cannot be combined with ${t.map((e) => `\`${e}\``).join(" or ")}. \`internal\` takes the procedure OFF the wire; those put it back ON a different one (${t.includes("publicApi") ? "a REST route" : "an agent tool"}), and that surface is projected without consulting the flag — so the procedure would be unreachable from your client and reachable from the internet. Drop \`internal: true\` if the wider surface is intended, or remove the ${t.join(" / ")} annotation if it is not.`);
+	if (e.overridesPlugin === !0) throw Error(`${e.name}: \`internal: true\` cannot be combined with \`overridesPlugin\`.\n  The override REMOVES the plugin route, and an internal procedure is not
+  wire-reachable — so the plugin's route would vanish with nothing callable
+  in its place, and callers would get a 404 for something that used to work.`);
+	let n = [e.publicApi === void 0 ? void 0 : "publicApi", e.exposeAsTool === void 0 ? void 0 : "exposeAsTool"].filter((e) => e !== void 0);
+	if (n.length === 0) return e;
+	throw Error(`${e.name}: \`internal: true\` cannot be combined with ${n.map((e) => `\`${e}\``).join(" or ")}. \`internal\` takes the procedure OFF the wire; those put it back ON a different one (${n.includes("publicApi") ? "a REST route" : "an agent tool"}), and that surface is projected without consulting the flag — so the procedure would be unreachable from your client and reachable from the internet. Drop \`internal: true\` if the wider surface is intended, or remove the ${n.join(" / ")} annotation if it is not.`);
 }, He = (e) => e.action !== void 0 && e.resourceType !== void 0, _ = (e) => g({
 	kind: "query",
 	name: e.name,
@@ -92,7 +101,8 @@ var Fe = c.Union(c.String, c.Number), u = c.Record({
 	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool,
-	internal: e.internal
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin
 }), v = (e) => g({
 	kind: "mutation",
 	name: e.name,
@@ -103,7 +113,8 @@ var Fe = c.Union(c.String, c.Number), u = c.Record({
 	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool,
-	internal: e.internal
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin
 }), y = (e) => g({
 	kind: "action",
 	name: e.name,
@@ -115,14 +126,17 @@ var Fe = c.Union(c.String, c.Number), u = c.Record({
 	target: e.target,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool,
-	internal: e.internal
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin
 }), Ue = (e) => g({
 	kind: "stream",
 	name: e.name,
 	input: e.input,
 	element: e.element,
 	error: e.error ?? c.Never,
-	internal: e.internal
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin,
+	guards: e.guards
 }), b = (e, t) => t && t.length > 0 ? c.Union(e, ...t) : e, x = (e, t) => t && t.length > 0 ? c.Union(e, s) : e, S = (e, t) => l.make(e.name, {
 	payload: e.input,
 	success: h(e.output),
@@ -195,6 +209,15 @@ var Fe = c.Union(c.String, c.Number), u = c.Record({
 	};
 }, Xe = 7500, Ze = (e) => typeof e == "object" && !!e && e.kind === "event", Qe = (e) => {
 	if (e.name.length === 0) throw Error("defineEvent: `name` must not be empty");
+	if (/\s/.test(e.name)) throw Error(`defineEvent("${e.name}"): \`name\` must not contain whitespace.\n  The name is used as a broker subject segment. NATS refuses a subject with
+  whitespace and delivers nothing — silently, and only on that broker, so an
+  app that works on Redis stops working when the transport changes.
+  Use a dot for namespacing: "orders.paid".`);
+	if (e.guards !== void 0 && e.guards.length === 0) throw Error(`defineEvent("${e.name}"): \`guards: []\` is empty, so it enforces nothing —\n  but it reads at the call site as if the event were protected. Omit the field
+  for an unguarded event, or list the scopes that may subscribe.`);
+	if (e.webhook?.rateLimit !== void 0 && e.webhook.rateLimit.perMinute < 1) throw Error(`defineEvent("${e.name}"): \`webhook.rateLimit.perMinute\` is ${e.webhook.rateLimit.perMinute}, which defers every delivery forever.\n  There is no "unlimited" spelling here — omit \`rateLimit\` for no ceiling.`);
+	if (e.webhook?.version !== void 0 && e.webhook.version < 1) throw Error(`defineEvent("${e.name}"): \`webhook.version\` must be >= 1 (default 1).\n  A subscriber pinned to 1 would read this event as BEHIND its own version,
+  which is the opposite of what a version bump is for.`);
 	if (e.delivery === "latest" && e.webhook !== void 0) throw Error(`defineEvent(${e.name}): \`delivery: 'latest'\` cannot be combined with \`webhook\`.\n  \`latest\` means a superseded delivery did not matter — but a webhook delivery is a
   durable side effect at a third party, and one already sent cannot be superseded.
   A high-rate event with an HTTP audience is also 60 deliveries per second per target;

package/dist/jwt.d.ts

@@ -231,15 +231,28 @@ export declare const _resetJwksCache: () => void;
 /** Test-only: clear the OIDC discovery-document cache between runs. */
 export declare const _resetOidcDiscoveryCache: () => void;
 
-/** A strategy's verdict on a request.
- *  - `matched`: this strategy claims the request; here's the Subject.
- *  - `skip`: not my request (e.g. cookie absent); try next strategy.
- *  - `failed`: this IS my request BUT validation failed (signature
- *    mismatch, expired JWT). Composer bails to anonymous + logs;
- *    silently falling through would mask attacks. */
 declare type StrategyResolution = {
     readonly kind: 'matched';
     readonly subject: Subject;
+    /**
+     * When this credential expires, in unix SECONDS — if the strategy knows.
+     *
+     * The strategy is the ONLY place in the system that has verified the token
+     * and holds its `exp`, and until now it could not say so. The credential
+     * bound therefore read one source: the `voltro:session` cookie. For an app
+     * authenticating with Bearer JWTs — six of our own catalog strategies do,
+     * and every one of them verifies an `exp` — it was silently `undefined`,
+     * so "a subscription can no longer outlive the credential that authorized
+     * it" was a no-op that read as a guarantee.
+     *
+     * A reporter found it by expecting black screens an hour after a deploy
+     * and getting none. Their conclusion is the one to keep: the guarantee was
+     * not false, it was scoped to an auth shape the sentence did not name.
+     *
+     * Optional, and absent still means no bound — the failure direction is the
+     * behaviour that already existed.
+     */
+    readonly credentialExpiresAt?: number;
 } | {
     readonly kind: 'skip';
 } | {

package/dist/jwt.js

@@ -110,22 +110,28 @@ var i = 3600 * 1e3, a = /* @__PURE__ */ new Map(), o = (e, n) => {
 					reason: `${e.id} token has no tenant claim and no defaultTenantId configured`
 				};
 				let i = e.subjectIdFromClaims ? e.subjectIdFromClaims(t) : String(t.sub ?? "");
-				return i ? {
-					kind: "matched",
-					subject: {
-						type: "user",
-						id: i,
-						tenantId: n,
-						...e.scopesFromClaims === void 0 ? {} : { scopes: e.scopesFromClaims(t) },
-						metadata: {
-							provider: e.id,
-							claims: t
-						}
-					}
-				} : {
+				if (!i) return {
 					kind: "failed",
 					reason: `${e.id} token has no sub claim`
 				};
+				let a = {
+					type: "user",
+					id: i,
+					tenantId: n,
+					...e.scopesFromClaims === void 0 ? {} : { scopes: e.scopesFromClaims(t) },
+					metadata: {
+						provider: e.id,
+						claims: t
+					}
+				}, o = typeof t.exp == "number" && Number.isFinite(t.exp) ? t.exp : void 0;
+				return o === void 0 ? {
+					kind: "matched",
+					subject: a
+				} : {
+					kind: "matched",
+					subject: a,
+					credentialExpiresAt: o
+				};
 			} catch (t) {
 				return t instanceof c ? {
 					kind: "failed",

package/dist/rest.d.ts

@@ -31,6 +31,28 @@ declare interface ActionProcedureDescriptor<Name extends string, Input extends S
     readonly exposeAsTool: ExposeAsTool | 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. */
+    /**
+     * Replace a PLUGIN route that answers to this same tag.
+     *
+     * Without it, a user route and a plugin route sharing a tag is a hard error,
+     * and correctly so — two handlers behind one name is not a thing a caller can
+     * reason about. But refusing is the wrong answer when the app deliberately
+     * wants its own version: the two escapes available otherwise are to rename
+     * your procedure (so the split runs along "who built it" rather than along a
+     * domain boundary) or to `alias` the whole plugin away (same, one level up).
+     * For a frontend developer that is the worst possible partition.
+     *
+     * A reporter wanted exactly this: adopt `@voltro/plugin-notifications`, whose
+     * surface is richer than theirs, add `archive`/`unarchive` beside it — which
+     * already composes, since the collision check compares FULL tags and not
+     * prefixes — and replace `markRead`, because theirs maintains archive state.
+     *
+     * Explicit, never inferred. Silently letting the app win would mean a plugin
+     * upgrade that adds a route could shadow an app procedure with no diff to
+     * read; declaring it makes the intent reviewable and puts the override in the
+     * file that performs it.
+     */
+    readonly overridesPlugin: boolean | undefined;
     readonly internal: boolean | undefined;
 }
 
@@ -209,6 +231,28 @@ declare interface MutationProcedureDescriptor<Name extends string, Input extends
     readonly exposeAsTool: ExposeAsTool | 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. */
+    /**
+     * Replace a PLUGIN route that answers to this same tag.
+     *
+     * Without it, a user route and a plugin route sharing a tag is a hard error,
+     * and correctly so — two handlers behind one name is not a thing a caller can
+     * reason about. But refusing is the wrong answer when the app deliberately
+     * wants its own version: the two escapes available otherwise are to rename
+     * your procedure (so the split runs along "who built it" rather than along a
+     * domain boundary) or to `alias` the whole plugin away (same, one level up).
+     * For a frontend developer that is the worst possible partition.
+     *
+     * A reporter wanted exactly this: adopt `@voltro/plugin-notifications`, whose
+     * surface is richer than theirs, add `archive`/`unarchive` beside it — which
+     * already composes, since the collision check compares FULL tags and not
+     * prefixes — and replace `markRead`, because theirs maintains archive state.
+     *
+     * Explicit, never inferred. Silently letting the app win would mean a plugin
+     * upgrade that adds a route could shadow an app procedure with no diff to
+     * read; declaring it makes the intent reviewable and puts the override in the
+     * file that performs it.
+     */
+    readonly overridesPlugin: boolean | undefined;
     readonly internal: boolean | undefined;
 }
 
@@ -517,6 +561,28 @@ declare interface QueryProcedureDescriptor<Name extends string, Input extends Sc
     readonly exposeAsTool: ExposeAsTool | 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. */
+    /**
+     * Replace a PLUGIN route that answers to this same tag.
+     *
+     * Without it, a user route and a plugin route sharing a tag is a hard error,
+     * and correctly so — two handlers behind one name is not a thing a caller can
+     * reason about. But refusing is the wrong answer when the app deliberately
+     * wants its own version: the two escapes available otherwise are to rename
+     * your procedure (so the split runs along "who built it" rather than along a
+     * domain boundary) or to `alias` the whole plugin away (same, one level up).
+     * For a frontend developer that is the worst possible partition.
+     *
+     * A reporter wanted exactly this: adopt `@voltro/plugin-notifications`, whose
+     * surface is richer than theirs, add `archive`/`unarchive` beside it — which
+     * already composes, since the collision check compares FULL tags and not
+     * prefixes — and replace `markRead`, because theirs maintains archive state.
+     *
+     * Explicit, never inferred. Silently letting the app win would mean a plugin
+     * upgrade that adds a route could shadow an app procedure with no diff to
+     * read; declaring it makes the intent reviewable and puts the override in the
+     * file that performs it.
+     */
+    readonly overridesPlugin: boolean | undefined;
     readonly internal: boolean | undefined;
 }
 

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-BPdyOBsd.js";
+import { s as a } from "./auth-CXMrvPyX.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) => {

package/dist/session.d.ts

@@ -108,6 +108,33 @@ export declare const resolveSessionSecret: () => string;
  */
 export declare const resolveSessionSecrets: () => SessionSecrets;
 
+/**
+ * The cookie the framework's own session strategy writes and reads.
+ *
+ * Exported and single-sourced because two readers now need it — the auth
+ * strategy in `dev.ts` and `sessionExpiryFromHeaders` below. Two copies of one
+ * env expression is the "derived twice" shape: both sites look correct and
+ * they disagree the moment someone sets the variable.
+ */
+export declare const SESSION_COOKIE_NAME: string;
+
+/**
+ * The verified expiry of the session cookie in `headers`, in unix SECONDS, or
+ * `undefined` when there is no session or it does not verify.
+ *
+ * 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
+ * that could forge a far-future `exp` would lift exactly the ceiling this
+ * exists to impose. The cost is one HMAC check on a call that already carries
+ * the cookie.
+ *
+ * A SHARED builder on purpose. `voltro dev` and `voltro serve` assemble their
+ * middleware independently, and a value derived twice is the shape this repo
+ * has been bitten by — dev and serve agreeing on a field while disagreeing on
+ * what it contains. Both call this.
+ */
+export declare const sessionExpiryFromHeaders: (headers: Record<string, string | undefined>) => number | undefined;
+
 export declare type SessionPayload = typeof SessionPayload_2.Type;
 
 declare const SessionPayload_2: Schema.Struct<{