@voltro/protocol 0.11.3 → 0.12.0

package/dist/apikey.js

@@ -1,28 +1,34 @@
 import { createHash as e } from "node:crypto";
 //#region src/apiKeyStrategy.ts
 var t = (t) => e("sha256").update(t, "utf8").digest("hex"), n = (e) => {
-	let n = e.id ?? "voltro-apikey";
+	let t = {};
+	for (let [n, r] of Object.entries(e)) r !== void 0 && (t[n] = r);
+	return t;
+}, r = (e) => {
+	let r = e.id ?? "voltro-apikey";
 	return {
-		id: n,
-		resolve: async (r) => {
-			let i = r.headers.authorization ?? r.headers.Authorization;
-			if (!i) return { kind: "skip" };
-			let a = /^Bearer\s+(.+)$/i.exec(i.trim());
+		id: r,
+		resolve: async (i) => {
+			let a = i.headers.authorization ?? i.headers.Authorization;
 			if (!a) return { kind: "skip" };
-			let o = a[1].trim(), s = e.prefix ?? "";
-			if (s && !o.startsWith(s)) return { kind: "skip" };
-			let c = await e.resolveKey(t(o));
-			return c ? {
+			let o = /^Bearer\s+(.+)$/i.exec(a.trim());
+			if (!o) return { kind: "skip" };
+			let s = o[1].trim(), c = e.prefix ?? "";
+			if (c && !s.startsWith(c)) return { kind: "skip" };
+			let l = await e.resolveKey(t(s));
+			return l ? {
 				kind: "matched",
 				subject: {
 					type: "apiKey",
-					id: c.id,
-					tenantId: c.tenantId,
-					scopes: c.scopes,
-					metadata: c.createdBy == null ? { provider: n } : {
-						provider: n,
-						userId: c.createdBy
-					}
+					id: l.id,
+					tenantId: l.tenantId,
+					scopes: l.scopes,
+					metadata: n({
+						...l.metadata ?? {},
+						provider: r,
+						userId: l.onBehalfOf ?? void 0,
+						createdBy: l.createdBy ?? void 0
+					})
 				}
 			} : {
 				kind: "failed",
@@ -32,4 +38,4 @@ var t = (t) => e("sha256").update(t, "utf8").digest("hex"), n = (e) => {
 	};
 };
 //#endregion
-export { n as apiKeyStrategy };
+export { r as apiKeyStrategy };

package/dist/{auth-DCE6m7Bo.js → auth-S3cnL6Tz.js}

@@ -41,7 +41,16 @@ var r = t.Record({
 	id: e,
 	tenantId: null,
 	scopes: t
-}), p = (e) => e.type === "system", m = class extends e.Tag("@voltro/Subject")() {}, h = class extends e.Tag("@voltro/ConnectionInfo")() {}, g = class extends n.Tag()("@voltro/AuthMiddleware", { provides: m }) {}, _ = class extends n.Tag()("@voltro/ConnectionInfoMiddleware", { provides: h }) {}, v = (e) => typeof e.mountRoutes == "function", y = (e, t) => async (n) => {
+}), p = (e, t) => {
+	let n = e;
+	return {
+		type: "serviceAccount",
+		id: e.id ?? "system",
+		tenantId: t,
+		scopes: n.scopes ?? ["admin:full"],
+		...n.metadata === void 0 ? {} : { metadata: n.metadata }
+	};
+}, m = (e) => e.type === "system", h = class extends e.Tag("@voltro/Subject")() {}, g = class extends e.Tag("@voltro/ConnectionInfo")() {}, _ = class extends n.Tag()("@voltro/AuthMiddleware", { provides: h }) {}, v = class extends n.Tag()("@voltro/ConnectionInfoMiddleware", { provides: g }) {}, y = (e) => typeof e.mountRoutes == "function", b = (e, t) => async (n) => {
 	for (let r of e) {
 		let e = await r.resolve(n);
 		if (e.kind === "matched") return e.subject;
@@ -55,10 +64,10 @@ var r = t.Record({
 	}
 	if (t?.fallback) return t.fallback(n);
 	let r = n.headers["x-tenant"] ?? null;
-	if (r === null && t?.anonymousTenantRequired === !0) throw new b({ reason: "tenant required (x-tenant header missing)" });
+	if (r === null && t?.anonymousTenantRequired === !0) throw new x({ reason: "tenant required (x-tenant header missing)" });
 	return d(r);
-}, b = class extends t.TaggedError()("Unauthenticated", { reason: t.optional(t.String) }) {}, x = (e, t) => {
-	if (e.type === "anonymous") throw new b(t === void 0 ? {} : { reason: t });
+}, x = class extends t.TaggedError()("Unauthenticated", { reason: t.optional(t.String) }) {}, S = (e, t) => {
+	if (e.type === "anonymous") throw new x(t === void 0 ? {} : { reason: t });
 };
 //#endregion
-export { m as a, x as c, p as d, f, u as i, y as l, h as n, b as o, _ as r, d as s, g as t, v as u };
+export { h as a, S as c, m as d, f, u as i, b as l, g as n, x as o, p, v as r, d as s, _ as t, y as u };

package/dist/index.d.ts

@@ -39,6 +39,37 @@ export declare type AnyCheckSpec = GuardCheckSpec | PolicyCheckSpec;
 /** A guard is either a scope check or a relationship check. */
 export declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input>;
 
+export declare const APIKEY_ISSUE_ORG_SCOPE = "apikeys:issue:org";
+
+export declare const APIKEY_ISSUE_OTHER_SCOPE = "apikeys:issue:other";
+
+/**
+ * API-key issuance rights.
+ *
+ * One `admin:full` gate for all key minting was too coarse to express what
+ * products actually need: it means only a full admin can ever mint a key, so a
+ * normal user cannot create their own even narrowly-scoped credential, and an
+ * admin minting one FOR someone is indistinguishable from minting one for
+ * themselves.
+ *
+ * Three separable capabilities instead:
+ *
+ *   `apikeys:issue:self`  - mint a key that acts as ME. The common self-service
+ *                           case; the key can never exceed the holder's own
+ *                           scopes.
+ *   `apikeys:issue:org`   - mint an ORG key: acts as no person, belongs to the
+ *                           organization. A CI credential. Separate because
+ *                           "may create a personal token" and "may create a
+ *                           credential that outlives my account" are genuinely
+ *                           different levels of trust.
+ *   `apikeys:issue:other` - mint a key ON BEHALF OF another user. Admin
+ *                           territory: it is the ability to act as someone
+ *                           else, so it is never implied by the other two.
+ *
+ * `admin:full` satisfies all three, as it does every scope.
+ */
+export declare const APIKEY_ISSUE_SELF_SCOPE = "apikeys:issue:self";
+
 /**
  * Apply a `RowPatch` to `prev`, producing `next`. Exact inverse of
  * `diffRows`: `applyRowPatch(prev, diffRows(prev, next))` deep-equals
@@ -1257,6 +1288,27 @@ export declare interface PluginHttpRouteResult {
     readonly body?: string | Uint8Array;
     readonly contentType?: string;
     readonly headers?: Record<string, string>;
+    /** Stream the response (SSE) instead of sending `body`. See
+     *  {@link PluginHttpRouteStream}. */
+    readonly stream?: PluginHttpRouteStream;
+}
+
+/**
+ * A long-lived Server-Sent-Events body. When a route result carries this, the
+ * serve layer streams the response until the client disconnects instead of
+ * sending a buffered body — `body` is ignored.
+ *
+ * `subscribe` receives an `emit` that takes ONE already-SSE-framed chunk (e.g.
+ * `` `event: snapshot\ndata: ${json}\n\n` ``) and MUST return an unsubscribe
+ * function. The serve layer runs that unsubscribe when the client goes away, so
+ * whatever the route opened (a dispatcher subscription, an interval) is released
+ * — a stream route that leaks its subscription leaks it per connection.
+ */
+export declare interface PluginHttpRouteStream {
+    readonly subscribe: (emit: (chunk: string) => void) => () => void;
+    /** Keep-alive comment interval in ms (default 15000; `0` disables). Without
+     *  it an idle SSE connection is dropped by proxies after ~30–60s. */
+    readonly keepAliveMs?: number;
 }
 
 export declare interface PluginInspectEndpoint {
@@ -2201,6 +2253,25 @@ export declare type Target<Input = unknown, Row = unknown> = TargetSpec<Input, R
 
 export declare type TargetSpec<Input = unknown, Row = unknown> = InsertTarget<Input, Row> | UpdateTarget<Input, Row> | DeleteTarget<Input>;
 
+/**
+ * The subject a `storeForTenant(id)` view runs as — the caller's identity,
+ * re-pointed at ONE explicit tenant.
+ *
+ * Lives here, next to the other subject constructors, because BOTH the serve
+ * context builder (`@voltro/cli`) and the test harness (`@voltro/testing`)
+ * must produce the identical subject. When it lived in the CLI, the harness
+ * could not reach it, and `ctx.storeForTenant` was simply absent under test —
+ * a handler that used it had no way to be tested at all.
+ *
+ * The narrowed return type is the point, not decoration: it states at the type
+ * level that this can never hand back a `system` subject, which is the variant
+ * whose null tenant means "all tenants". Producing one here would silently
+ * widen a deliberately narrow view back to every tenant.
+ */
+export declare const tenantScopedSubject: (subject: Subject, tenantId: string) => Extract<Subject, {
+    readonly type: "serviceAccount";
+}>;
+
 export declare const toRpc: <Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: QueryProcedureDescriptor<Name, Input, Output, Err> | MutationProcedureDescriptor<Name, Input, Output, Err> | ActionProcedureDescriptor<Name, Input, Output, Err> | StreamProcedureDescriptor<Name, Input, Output, Err>) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Schema.Union<[Schema.Struct<{
     _tag: Schema.Literal<["snapshot"]>;
     revision: typeof Schema.Number;
@@ -2428,6 +2499,24 @@ export declare interface VoltroPlugin {
      * dashboard Env panel. Mirror exactly what the plugin reads.
      */
     readonly declaredEnv?: ReadonlyArray<PluginEnvVar>;
+    /**
+     * The authorization scopes this plugin DEFINES for the app — its scope
+     * vocabulary. Distinct from `permissions` above, which is what the plugin
+     * itself asks to be granted.
+     *
+     * `@voltro/plugin-rbac` fills this with every scope its `roles` map grants,
+     * because that map already IS the app's declared vocabulary. The capability
+     * manifest unions these, and `voltro check` compares each handler's required
+     * scopes against the union: a guard demanding a scope no role can grant (a
+     * typo, a rename) makes that procedure permanently uncallable, silently.
+     *
+     * Only declare this when the list is EXHAUSTIVE. A plugin that also grants
+     * scopes from a dynamic source (a custom resolver, per-row ACLs) must leave
+     * it undefined — the check treats "no declared scopes" as "cannot conclude"
+     * and stays dormant, which is the honest outcome. A partial list would flag
+     * correct code, and a check that cries wolf gets ignored.
+     */
+    readonly declaredScopes?: ReadonlyArray<string>;
     /**
      * Optional `effect/Schema` describing the plugin's user-supplied
      * config. When present the framework decodes the operator's config