@voltro/protocol 0.1.0

package/dist/jwt.js

@@ -0,0 +1,142 @@
+import { readCookie as e } from "./session.js";
+import { createRemoteJWKSet as t, errors as n, jwtVerify as r } from "jose";
+//#region src/jwt.ts
+var i = 3600 * 1e3, a = /* @__PURE__ */ new Map(), o = (e, n) => {
+	let r = a.get(e);
+	if (r && Date.now() - r.fetchedAt < r.ttlMs) return r.fetcher;
+	let i = t(new URL(e), {
+		cacheMaxAge: n,
+		cooldownDuration: 3e4
+	});
+	return a.set(e, {
+		fetcher: i,
+		fetchedAt: Date.now(),
+		ttlMs: n
+	}), i;
+}, s = () => {
+	a.clear();
+}, c = class extends Error {
+	code;
+	constructor(e, t) {
+		super(e), this.code = t, this.name = "JwtVerifyError";
+	}
+}, l = ["ES256", "RS256"], u = async (e, t, n = {}) => {
+	let a = o(t, n.jwksCacheTtlMs ?? i);
+	try {
+		let { payload: t } = await r(e, a, {
+			...n.issuer === void 0 ? {} : { issuer: n.issuer },
+			...n.audience === void 0 ? {} : { audience: n.audience },
+			clockTolerance: n.clockToleranceS ?? 60,
+			algorithms: [...n.algorithms ?? l]
+		});
+		return t;
+	} catch (e) {
+		throw _(e);
+	}
+}, d = ["HS256"], f = async (e, t, n = {}) => {
+	let i = new TextEncoder().encode(t);
+	try {
+		let { payload: t } = await r(e, i, {
+			...n.issuer === void 0 ? {} : { issuer: n.issuer },
+			...n.audience === void 0 ? {} : { audience: n.audience },
+			clockTolerance: n.clockToleranceS ?? 60,
+			algorithms: [...n.algorithms ?? d]
+		});
+		return t;
+	} catch (e) {
+		throw _(e);
+	}
+}, p = (e, t) => {
+	let n = e;
+	for (let e of t.split(".")) {
+		if (typeof n != "object" || !n) return;
+		n = n[e];
+	}
+	return n;
+}, m = /* @__PURE__ */ new Map(), h = async (e) => {
+	let t = m.get(e);
+	if (t) return t;
+	let n = fetch(e).then(async (t) => {
+		if (!t.ok) throw Error(`OIDC discovery fetch failed: ${t.status} ${t.statusText}`);
+		let n = await t.json();
+		if (typeof n.jwks_uri != "string") throw Error(`OIDC discovery document missing jwks_uri at ${e}`);
+		return n;
+	}).catch((t) => {
+		throw m.delete(e), t;
+	});
+	return m.set(e, n), n;
+}, g = () => {
+	m.clear();
+}, _ = (e) => {
+	if (e instanceof n.JWTExpired) return new c("jwt expired", "expired");
+	if (e instanceof n.JWTClaimValidationFailed) {
+		let t = e.claim;
+		return t === "iss" ? new c("issuer mismatch", "issuer_mismatch") : t === "aud" ? new c("audience mismatch", "audience_mismatch") : t === "nbf" ? new c("not yet valid", "not_yet_valid") : new c(`claim '${t ?? "?"}' failed`, "other");
+	}
+	if (e instanceof n.JWSSignatureVerificationFailed) return new c("signature verification failed", "signature_mismatch");
+	if (e instanceof n.JWSInvalid || e instanceof n.JWTInvalid) return new c("malformed jwt", "malformed");
+	if (e instanceof n.JOSEAlgNotAllowed) return new c("jwt algorithm not allowed", "unsupported_algorithm");
+	let t = e?.message ?? String(e);
+	return /fetch|network|enotfound|econnrefused/i.test(t) ? new c(`jwks unreachable: ${t}`, "jwks_unreachable") : new c(`jwt verify failed: ${t}`, "other");
+}, v = (t, n) => {
+	let r = t.authorization ?? t.Authorization;
+	if (r?.startsWith("Bearer ")) {
+		let e = r.slice(7).trim();
+		if (e) return e;
+	}
+	if (n) {
+		let r = e(t.cookie, n);
+		if (r) return r;
+	}
+}, y = (e) => {
+	let t = e.cookieName === void 0 ? null : e.cookieName;
+	return {
+		id: e.id,
+		resolve: async (n) => {
+			let r = v(n.headers, t);
+			if (!r) return { kind: "skip" };
+			try {
+				let t = e.jwtSecret === void 0 ? await u(r, e.jwksUrl, {
+					...e.issuer === void 0 ? {} : { issuer: e.issuer },
+					...e.audience === void 0 ? {} : { audience: e.audience },
+					...e.algorithms === void 0 ? {} : { algorithms: e.algorithms }
+				}) : await f(r, e.jwtSecret, {
+					...e.issuer === void 0 ? {} : { issuer: e.issuer },
+					...e.audience === void 0 ? {} : { audience: e.audience },
+					...e.algorithms === void 0 ? {} : { algorithms: e.algorithms }
+				}), n = e.tenantIdFromClaims(t);
+				if (!n) return {
+					kind: "failed",
+					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
+						}
+					}
+				} : {
+					kind: "failed",
+					reason: `${e.id} token has no sub claim`
+				};
+			} catch (t) {
+				return t instanceof c ? {
+					kind: "failed",
+					reason: `${e.id} jwt ${t.code}: ${t.message}`
+				} : {
+					kind: "failed",
+					reason: `${e.id} verify error: ${t.message}`
+				};
+			}
+		}
+	};
+};
+//#endregion
+export { c as JwtVerifyError, s as _resetJwksCache, g as _resetOidcDiscoveryCache, h as discoverOidc, v as extractBearerOrCookie, y as jwtBearerStrategy, p as readClaimPath, e as readCookie, u as verifyJwt, f as verifyJwtWithSecret };

package/dist/rest.d.ts

@@ -0,0 +1,450 @@
+import { Schema } from 'effect';
+
+declare interface ActionProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+    readonly kind: 'action';
+    readonly name: Name;
+    readonly input: Input;
+    readonly output: Output;
+    readonly error: Error;
+    /** 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;
+}
+
+/**
+ * Project every descriptor carrying a `publicApi` annotation into a REST
+ * route, in stable (path) order. The boot layer feeds these straight into
+ * `restRoutesToHttpRoutes` alongside any hand-authored `restRoutes`.
+ */
+export declare const collectPublicApiRoutes: (entries: ReadonlyArray<PublicApiEntry>) => ReadonlyArray<RestRouteDescriptor<Record<string, unknown>, unknown>>;
+
+/**
+ * Identity helper that fixes the descriptor's types (like `defineAction` /
+ * `definePlugin`). Returns its argument unchanged at runtime; exists for
+ * the type-level enforcement at the declaration site.
+ */
+export declare const defineRestRoute: <I, O>(descriptor: RestRouteDescriptor<I, O>) => RestRouteDescriptor<I, O>;
+
+declare interface DeleteTarget<Input = unknown> {
+    readonly table: string;
+    readonly op: 'delete';
+    /** Identify the row to remove. Default: `input.id`. */
+    readonly identify?: ((input: Input) => string) | undefined;
+}
+
+/** query→GET, mutation/action→POST, unless the spec overrides. */
+export declare const derivePublicMethod: (kind: PublicApiDescriptor["kind"], spec: PublicApiSpec) => RestMethod;
+
+/** `/<version>/<tag-with-dots-as-slashes>` unless the spec gives an explicit
+ *  path. `orders.create` @ v1 → `/v1/orders/create`. */
+export declare const derivePublicPath: (tag: string, spec: PublicApiSpec) => string;
+
+/**
+ * Dispatch a request across REST routes that SHARE a path. Every REST route
+ * mounts as `*` and gates its own method, returning a precise 405 BEFORE any
+ * side effect when the method isn't its own — so probing the group in order and
+ * taking the FIRST non-405 result yields the route that owns the request's
+ * method. This is what lets the standard GET + POST on one resource path
+ * coexist: the serve pipeline mounts ONE dispatcher per path (the underlying
+ * router rejects two mounts on the same `(method, path)`). A single-route group
+ * returns that route's result directly (its own 405 included); when no route in
+ * the group owns the method, the last 405 stands.
+ *
+ * `group` must be non-empty (the serve pipeline only builds a dispatcher for a
+ * path that has at least one route).
+ */
+export declare const dispatchSharedPath: (group: ReadonlyArray<PluginHttpRoute>, req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+
+/** Normalize the `exposeAsTool` shorthand. `true` is only valid when the
+ *  descriptor carries a top-level `description`; callers pass that in. */
+declare type ExposeAsTool = boolean | ExposeAsToolSpec;
+
+declare interface ExposeAsToolSpec {
+    /** Shown to the model — REQUIRED to expose (a tool with no description is
+     *  unusable). What the tool does + when to call it. */
+    readonly description: string;
+    /** Require human confirmation of the concrete call before it executes.
+     *  Default posture: writes (mutation/action) confirm, reads don't. */
+    readonly confirm?: boolean;
+    /** Cap how many times the agent may call this tool per run. */
+    readonly maxPerRun?: number;
+}
+
+declare interface IdempotencyRecord {
+    readonly scope: string;
+    readonly key: string;
+    readonly status: 'in_flight' | 'completed';
+    readonly response: IdempotencyResponse | null;
+    /** epoch ms */
+    readonly createdAt: number;
+}
+
+declare interface IdempotencyResponse {
+    readonly status: number;
+    readonly body: unknown;
+}
+
+declare interface IdempotencyStore {
+    /** Current record for (scope, key), or null. Read-side (inspect/dashboard). */
+    readonly get: (scope: string, key: string) => Promise<IdempotencyRecord | null>;
+    /**
+     * Atomically claim (scope, key) IF absent OR stale (older than `ttlMs`):
+     * write a fresh `in_flight` row and return `'claimed'`. Otherwise return the
+     * EXISTING (still-fresh) record. The atomicity here is the whole game — two
+     * concurrent same-key requests both hit this, exactly one gets `'claimed'`,
+     * the loser reads the winner's record. In SQL this is one
+     * `INSERT … ON CONFLICT DO UPDATE … WHERE existing.createdAt < now - ttl`.
+     */
+    readonly claim: (scope: string, key: string, now: number, ttlMs: number) => Promise<'claimed' | IdempotencyRecord>;
+    /** Flip the claim to `completed` and store the response. */
+    readonly complete: (scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
+    /** Drop the claim (handler errored → a retry may re-process). */
+    readonly release: (scope: string, key: string) => Promise<void>;
+}
+
+declare interface InsertTarget<Input = unknown, Row = unknown> {
+    readonly table: string;
+    readonly op: 'insert';
+    readonly order?: 'prepend' | 'append' | undefined;
+    /**
+     * Build the optimistic row from the mutation input. The framework
+     * injects `id` (from `optimisticId`) and the `optimistic: true` flag
+     * around the return — your `shape` returns ONLY the user-controllable
+     * row body. Default when omitted: `{ ...input, id, optimistic: true }`.
+     *
+     * Return type intentionally excludes `id`: it's server-generated;
+     * the optimistic id placeholder is the framework's responsibility.
+     * Excluding `optimistic` (also framework-injected) follows the same
+     * principle — `Omit<Row, 'id' | 'optimistic'>` lets you describe
+     * EVERYTHING ELSE without re-stating the bookkeeping fields.
+     *
+     * The `optimisticId` parameter is exposed for rare cases where the
+     * shape function needs to reference it (e.g., setting a foreign key
+     * on a child row spread in the same optimistic insert).
+     */
+    readonly shape?: ((input: Input, optimisticId: string) => Omit<Row, 'id' | 'optimistic'>) | undefined;
+}
+
+/** Extract `:name` path params by aligning the route PATTERN with the request
+ *  path segment-by-segment (`/projects/:project/deploy` + `/projects/acme/deploy`
+ *  → `{ project: 'acme' }`). `PluginHttpRouteRequest` carries no matched params,
+ *  so the desugar re-derives them here — without this, `input.params` is always
+ *  empty and every `:param` route 400s on decode. */
+export declare const matchPathParams: (pattern: string, path: string) => Record<string, string>;
+
+declare interface MutationProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+    readonly kind: 'mutation';
+    readonly name: Name;
+    readonly input: Input;
+    readonly output: Output;
+    readonly error: Error;
+    /** Declarative target(s) — drives auto-optimistic on the client AND
+     *  surfaces which tables this mutation touches (debug, future
+     *  query-invalidation analytics). Mutations without a target run
+     *  normally but skip auto-optimistic. */
+    readonly target: Target | 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;
+}
+
+/** A public raw-HTTP route a plugin serves on the framework listener. */
+declare interface PluginHttpRoute {
+    /** HTTP method, or `'*'` for any (the handler decides). */
+    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Absolute path prefix, e.g. `/_voltro/storage`. Matches the path AND
+     *  any sub-path (`/_voltro/storage/abc123`). */
+    readonly path: string;
+    readonly handle: (req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+}
+
+declare interface PluginHttpRouteRequest {
+    readonly method: string;
+    /** Path WITHOUT query string. */
+    readonly path: string;
+    /** Query string WITHOUT the leading `?` (empty when absent). Parse with
+     *  `new URLSearchParams(req.query)`. */
+    readonly query: string;
+    readonly headers: Record<string, string>;
+    readonly rawBody: Uint8Array;
+}
+
+/**
+ * One HTTP endpoint a plugin contributes under the framework's
+ * `/_voltro/inspect/*` introspection surface. Plugins use this to
+ * surface tooling / dashboards that don't fit the rpc wire (e.g.
+ * Server-Sent-Event streams of plugin-internal state, on-demand
+ * health probes, plugin-specific debug dumps).
+ *
+ * Path convention: `/_voltro/inspect/plugins/<plugin-slug>/<route.path>`.
+ * The plugin slug (derived from `plugin.name` with `@scope/` +
+ * `plugin-` stripped, KEBAB-CASE — `plugin-cdc-out` → `cdc-out`,
+ * instance suffix `#x` → `--x`) is prepended by the framework so
+ * plugin endpoints never collide with the framework's own inspect
+ * endpoints OR with another plugin's. Kebab (not the camelCase rpc
+ * alias) because it's a URL every dashboard fetches. The dashboard
+ * lists every plugin's endpoints grouped by plugin in the manifest.
+ *
+ * Plugin endpoints inherit the SAME auth resolver the framework's
+ * own inspect endpoints use (`VOLTRO_INSPECT_TOKEN` by default;
+ * customisable by passing an `authResolver` at the http-handler
+ * layer). The plugin can NOT bypass auth — that's the framework's
+ * job, not the plugin's.
+ */
+/** What a plugin HTTP route returns. `body` may be bytes (e.g. a served
+ *  blob) or text; `headers` carries redirects (302 `location`) + cache
+ *  policy. */
+declare interface PluginHttpRouteResult {
+    readonly status: number;
+    readonly body?: string | Uint8Array;
+    readonly contentType?: string;
+    readonly headers?: Record<string, string>;
+}
+
+/** 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>;
+
+/** A descriptor paired with its bound executor, for batch projection at boot. */
+export declare interface PublicApiEntry {
+    readonly descriptor: PublicApiDescriptor;
+    readonly invoke: PublicApiInvoke;
+}
+
+/** The bound executor a public route runs — the real rpc handler, invoked
+ *  under the request's (apiKey) subject. `ctx` carries that subject (resolved
+ *  by the REST desugar's `resolveSubject`) so the serve binding runs the
+ *  handler through the SAME AuthMiddleware/RBAC/tenant/audit as the rpc path. */
+export declare type PublicApiInvoke = (input: unknown, ctx: RestRouteContext) => Promise<unknown> | unknown;
+
+/**
+ * Synthesize the public REST route for ONE descriptor. The descriptor's input
+ * schema is wrapped into the REST `{ query }` (GET) / `{ body }` (other) shape
+ * the desugar decodes, then handed UNWRAPPED to `invoke`. Output is the
+ * descriptor's output schema verbatim (a streaming query is drained to its
+ * first snapshot by the serve layer — same as POST /rpc). `scopes` become
+ * `requireScope` guards on top of the handler's own RBAC.
+ */
+export declare const publicApiRoute: (descriptor: PublicApiDescriptor, invoke: PublicApiInvoke) => RestRouteDescriptor<Record<string, unknown>, unknown>;
+
+declare interface PublicApiSpec {
+    /** Derived by kind when omitted: query→GET, mutation/action→POST. */
+    readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Derived from the tag + version when omitted: `/<version>/<tag-as-path>`. */
+    readonly path?: string;
+    /** Path version segment; multiple versions coexist as separate descriptors. */
+    readonly version?: string;
+    /** Additional API-key scopes required ON TOP of the handler's RBAC. */
+    readonly scopes?: ReadonlyArray<string>;
+    /** Per-endpoint rate limit (rides @voltro/plugin-ratelimit when mounted). */
+    readonly rateLimit?: {
+        readonly limit: number;
+        readonly window: string;
+    };
+    /** Honor `Idempotency-Key` for mutating methods (existing HTTP idempotency). */
+    readonly idempotent?: boolean;
+    /** Replacement hint → `Deprecation: true` header. */
+    readonly deprecated?: string;
+    /** ISO date → `Sunset:` header, `410` past the date. */
+    readonly sunset?: string;
+    readonly summary?: string;
+    readonly description?: string;
+    /** Streaming queries over request/response: 'snapshot' (default — first
+     *  snapshot, like POST /rpc) | 'sse' (Server-Sent Events of snapshot+deltas). */
+    readonly stream?: 'snapshot' | 'sse';
+}
+
+/**
+ * Server-side snapshot caching for a query (see `defineQuery`). When set,
+ * the dispatcher caches the initial snapshot result and auto-invalidates it
+ * when a mutation writes any table the query depends on.
+ */
+declare interface QueryCacheConfig {
+    /** Fresh window — seconds (number) or a duration string (`'30s'`,
+     *  `'5m'`, `'1h'`). */
+    readonly ttl: number | string;
+    /** Stale-while-revalidate window past `ttl` (same units). While stale,
+     *  the cached value is served immediately and refreshed in the
+     *  background. */
+    readonly swr?: number | string | undefined;
+    /**
+     * Cross-subject safety — REQUIRED, no default, because guessing wrong
+     * leaks rows. `'subject'` keys the cache by the caller's subject id
+     * (safe for tenant- or row-filtered queries). `'global'` shares ONE
+     * entry across every caller — legal ONLY when the resolved query is
+     * subject-independent (reference data). Rubric: does the resolved
+     * predicate depend on the caller? Yes → `subject`; no → `global`.
+     */
+    readonly scope: 'subject' | 'global';
+}
+
+declare interface QueryProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+    readonly kind: 'query';
+    readonly name: Name;
+    readonly input: Input;
+    readonly output: Output;
+    readonly error: Error;
+    /** Which DataStore table(s) this query reads. Drives auto-optimistic patch
+     *  routing — mutations that target ANY of these tables patch caches keyed
+     *  to queries with a matching `source`. A computed query re-runs when ANY
+     *  listed table changes (pass an array to depend on several). Optional:
+     *  queries without a source never receive auto-patches (joins, aggregates). */
+    readonly source: string | ReadonlyArray<string> | undefined;
+    /** Server-side snapshot cache config. Absent → never cached (the
+     *  default; the dispatcher already keeps live subscriptions fresh). */
+    readonly cache: QueryCacheConfig | 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). */
+    readonly exposeAsTool: ExposeAsTool | undefined;
+}
+
+/**
+ * Guard that requires the resolved subject to carry `scope`. Anonymous /
+ * scope-less subjects are rejected with `403`. The blanket admin scope
+ * (`ADMIN_SCOPE` = `'admin:full'`) satisfies any required scope — the SAME
+ * bypass the rpc-handler `requireScope`/`hasScope` (`./scopes`) honours, so
+ * a subject granted admin is admin on both surfaces.
+ */
+export declare const requireScope: (scope: string) => RestGuard;
+
+export declare type RestGuard = (ctx: RestRouteContext) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
+
+/**
+ * A guard runs after input decode + ctx resolution, before the handler.
+ * Returning a `RestGuardRejection` short-circuits with that status; any
+ * other return (or `undefined`) lets the request proceed.
+ */
+export declare interface RestGuardRejection {
+    readonly status: number;
+    readonly message: string;
+}
+
+export declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * Per-call context handed to a REST route handler. Resolved by the serve
+ * pipeline: `subject` from the framework's auth resolver, `headers`
+ * lowercased, `store` the framework `DataStore` injected the same way
+ * plugins receive it via `bindDataStore` (kept untyped here so protocol
+ * stays free of the database dep).
+ */
+export declare interface RestRouteContext {
+    readonly subject: Subject;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Framework `DataStore`. Untyped in protocol (same discipline as
+     *  `PluginHttpRoute` / `bindDataStore`); cast to the concrete store at
+     *  the call site. `undefined` only in unit tests that don't inject one. */
+    readonly store: unknown;
+}
+
+export declare interface RestRouteDescriptor<I, O> {
+    readonly method: RestMethod;
+    /** Absolute path, e.g. `/v1/customers`. Matches that path exactly. */
+    readonly path: string;
+    /** Input schema. Shape is `{ query?, params?, body? }` — the desugar
+     *  parses the query string, path params, and JSON body into that shape
+     *  before decoding. Omit for routes that take no input. The schema's
+     *  decoded `Type` flows to the handler's `input`; its `Encoded` is left
+     *  open (`any`) so any `Schema.Struct(...)` is accepted. */
+    readonly input?: Schema.Schema<I, any, never>;
+    /** Output schema. The handler returns the decoded `Type`; the desugar
+     *  encodes it to JSON for the `200` response. */
+    readonly output: Schema.Schema<O, any, never>;
+    readonly handler: (input: I, ctx: RestRouteContext) => Promise<O> | O;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly example?: RestRouteExample;
+    /** Replacement hint. Sets a `Deprecation: true` response header. */
+    readonly deprecated?: string;
+    /** ISO date. Sets a `Sunset:` header; past the date the route returns
+     *  `410 Gone` with a replacement pointer. */
+    readonly sunset?: string;
+    readonly guards?: ReadonlyArray<RestGuard>;
+}
+
+export declare interface RestRouteExample {
+    readonly request?: unknown;
+    readonly response?: unknown;
+}
+
+/**
+ * Desugar a list of REST descriptors into `PluginHttpRoute[]` ready to
+ * spread into a plugin/app's `httpRoutes`. `bindings` is supplied by the
+ * serve pipeline (auth resolver + bound DataStore); omit it in unit tests
+ * to get an anonymous subject and an undefined store.
+ */
+export declare const restRoutesToHttpRoutes: (routes: ReadonlyArray<RestRouteDescriptor<any, any>>, bindings?: RestServeBindings) => ReadonlyArray<PluginHttpRoute>;
+
+/**
+ * Default ctx resolver used when the serve pipeline doesn't inject one
+ * (e.g. unit tests). Real mounts pass a resolver that reads the framework's
+ * auth subject + the bound DataStore.
+ */
+export declare interface RestServeBindings {
+    /** Resolve the calling subject from the request headers. */
+    readonly resolveSubject?: (headers: Readonly<Record<string, string>>) => Subject | Promise<Subject>;
+    /** The bound framework DataStore. */
+    readonly store?: unknown;
+    /**
+     * HTTP idempotency — when set, a mutating request (POST/PUT/PATCH/DELETE)
+     * carrying the `header` is deduplicated: the first call runs + caches its
+     * response; a replay within `ttlMs` returns the cached response
+     * (`Idempotency-Replayed: true`); an in-flight duplicate gets `409`. Scoped
+     * per (tenant, method, path). The serve path injects the store + config from
+     * `app.config.ts`'s `idempotency` field.
+     */
+    readonly idempotency?: {
+        readonly store: IdempotencyStore;
+        readonly header: string;
+        readonly ttlMs: number;
+    };
+}
+
+declare const Subject: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["user"]>;
+    id: typeof Schema.String;
+    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;
+    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;
+    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;
+    tenantId: typeof Schema.Null;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>]>;
+
+declare type Subject = typeof Subject.Type;
+
+declare type Target<Input = unknown, Row = unknown> = TargetSpec<Input, Row> | ReadonlyArray<TargetSpec<Input, Row>>;
+
+declare type TargetSpec<Input = unknown, Row = unknown> = InsertTarget<Input, Row> | UpdateTarget<Input, Row> | DeleteTarget<Input>;
+
+declare interface UpdateTarget<Input = unknown, Row = unknown> {
+    readonly table: string;
+    readonly op: 'update';
+    /** Identify the row to patch. Default: `input.id`. */
+    readonly identify?: ((input: Input) => string) | undefined;
+    /** Build the patch. Default: merges input over current. */
+    readonly shape?: ((input: Input, current: Row) => Row) | undefined;
+}
+
+export { }