@voltro/protocol 0.1.0

package/dist/index.js

@@ -0,0 +1,396 @@
+import { a as e, c as t, d as n, f as r, i, l as a, n as o, o as ee, r as te, s, t as ne, u as re } from "./auth-DCE6m7Bo.js";
+import { a as ie, c as ae, d as oe, f as se, i as ce, l as le, n as ue, o as de, r as fe, s as pe, t as me, u as he } from "./serverErrorBus-C1KVL0dr.js";
+import { Context as ge, Layer as _e, Schema as c } from "effect";
+import { Rpc as l } from "@effect/rpc";
+//#region src/rowPatch.ts
+var ve = c.Union(c.String, c.Number), u = c.Record({
+	key: c.String,
+	value: c.Unknown
+}).pipe(c.filter((e) => "id" in e, { message: () => "patch row must carry an id" })), d = c.Union(c.Struct({
+	op: c.Literal("add"),
+	path: c.String,
+	value: u
+}), c.Struct({
+	op: c.Literal("replace"),
+	path: c.String,
+	value: u
+}), c.Struct({
+	op: c.Literal("remove"),
+	path: c.String
+})), f = c.Struct({
+	ops: c.Array(d),
+	order: c.Array(ve)
+}), p = (e) => `/${String(e).replace(/~/g, "~0").replace(/\//g, "~1")}`, ye = (e) => (e.startsWith("/") ? e.slice(1) : e).replace(/~1/g, "/").replace(/~0/g, "~"), m = (e) => {
+	let t = Object.keys(e).sort(), n = {};
+	for (let r of t) n[r] = e[r];
+	return JSON.stringify(n);
+}, be = (e, t) => m(e) === m(t), xe = (e, t) => {
+	let n = /* @__PURE__ */ new Map();
+	for (let t of e) n.set(t.id, t);
+	let r = [], i = [], a = /* @__PURE__ */ new Set();
+	for (let e of t) {
+		i.push(e.id), a.add(e.id);
+		let t = n.get(e.id);
+		t === void 0 ? r.push({
+			op: "add",
+			path: p(e.id),
+			value: e
+		}) : be(t, e) || r.push({
+			op: "replace",
+			path: p(e.id),
+			value: e
+		});
+	}
+	for (let t of e) a.has(t.id) || r.push({
+		op: "remove",
+		path: p(t.id)
+	});
+	return {
+		ops: r,
+		order: i
+	};
+}, Se = (e) => e.every((e) => {
+	let t = e.id;
+	return typeof t == "string" || typeof t == "number";
+}), Ce = (e, t) => {
+	let n = /* @__PURE__ */ new Map();
+	for (let t of e) n.set(t.id, t);
+	for (let e of t.ops) (e.op === "add" || e.op === "replace") && n.set(e.value.id, e.value);
+	let r = [];
+	for (let e of t.order) {
+		let t = n.get(e);
+		t !== void 0 && r.push(t);
+	}
+	return r;
+}, h = (e) => c.Union(c.Struct({
+	_tag: c.Literal("snapshot"),
+	revision: c.Number,
+	data: e,
+	computed: c.optional(c.Boolean)
+}), c.Struct({
+	_tag: c.Literal("delta"),
+	revision: c.Number,
+	emittedAt: c.Number,
+	patch: f
+}), c.Struct({
+	_tag: c.Literal("error"),
+	error: c.Unknown,
+	revision: c.optional(c.Number)
+})), g = (e) => ({
+	kind: "query",
+	name: e.name,
+	input: e.input,
+	output: e.output,
+	error: e.error ?? c.Never,
+	source: e.source,
+	cache: e.cache,
+	publicApi: e.publicApi,
+	exposeAsTool: e.exposeAsTool
+}), _ = (e) => ({
+	kind: "mutation",
+	name: e.name,
+	input: e.input,
+	output: e.output,
+	error: e.error ?? c.Never,
+	target: e.target,
+	publicApi: e.publicApi,
+	exposeAsTool: e.exposeAsTool
+}), v = (e) => ({
+	kind: "action",
+	name: e.name,
+	input: e.input,
+	output: e.output,
+	error: e.error ?? c.Never,
+	publicApi: e.publicApi,
+	exposeAsTool: e.exposeAsTool
+}), we = (e) => ({
+	kind: "stream",
+	name: e.name,
+	input: e.input,
+	element: e.element,
+	error: e.error ?? c.Never
+}), y = (e, t) => t && t.length > 0 ? c.Union(e, ...t) : e, b = (e, t) => l.make(e.name, {
+	payload: e.input,
+	success: h(e.output),
+	error: y(e.error, t),
+	stream: !0
+}), x = (e, t) => l.make(e.name, {
+	payload: e.input,
+	success: e.output,
+	error: y(e.error, t)
+}), S = (e, t) => l.make(e.name, {
+	payload: e.input,
+	success: e.output,
+	error: y(e.error, t)
+}), C = (e, t) => l.make(e.name, {
+	payload: e.input,
+	success: e.element,
+	error: y(e.error, t),
+	stream: !0
+}), Te = (e) => {
+	switch (e.kind) {
+		case "query": return b(e);
+		case "mutation": return x(e);
+		case "action": return S(e);
+		case "stream": return C(e);
+	}
+}, Ee = (e) => {
+	let t = e.input, n = t === void 0 ? {} : { input: t }, r = e.output, i = r === void 0 ? {} : { output: r };
+	if (e.kind === "query") return {
+		kind: "query",
+		source: e.source,
+		...n,
+		...i
+	};
+	if (e.kind === "action") return {
+		kind: "action",
+		...n,
+		...i
+	};
+	if (e.kind === "stream") return {
+		kind: "stream",
+		...n,
+		...i
+	};
+	let a = e.target;
+	if (a === void 0) return {
+		kind: "mutation",
+		...n,
+		...i
+	};
+	let o = Array.isArray(a) ? a : [a];
+	return {
+		kind: "mutation",
+		...n,
+		...i,
+		targets: o.map((e) => ({
+			table: e.table,
+			op: e.op,
+			..."order" in e && e.order !== void 0 ? { order: e.order } : {},
+			..."shape" in e && e.shape !== void 0 ? { shape: e.shape } : {},
+			..."identify" in e && e.identify !== void 0 ? { identify: e.identify } : {}
+		}))
+	};
+}, w = (e) => e, T = (e) => e, E = (e) => {
+	if (e.length !== 0) return (t, n) => e.reduceRight((e, t) => t(e, n), t);
+}, D = (e, t) => {
+	let n = ge.GenericTag(e);
+	return {
+		Tag: n,
+		Live: _e.succeed(n, t)
+	};
+}, De = (e, t, n) => {
+	if (!t) return { ok: !0 };
+	let r = O(n);
+	if (!r) return {
+		ok: !1,
+		reason: `cannot parse runningVersion "${n}"`
+	};
+	let i = t.trim();
+	if (i === "*" || i === "") return { ok: !0 };
+	let a = i.split(/\s+/).filter((e) => e.length > 0);
+	for (let i of a) if (!Oe(i, r)) return {
+		ok: !1,
+		reason: `plugin "${e}" requires framework ${t}, running ${n}`
+	};
+	return { ok: !0 };
+}, O = (e) => {
+	let t = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9a-zA-Z.-]+))?$/.exec(e.trim());
+	return t ? {
+		major: Number(t[1]),
+		minor: Number(t[2]),
+		patch: Number(t[3]),
+		pre: t[4] ?? ""
+	} : null;
+}, k = (e, t) => e.major === t.major ? e.minor === t.minor ? e.patch === t.patch ? e.pre && !t.pre ? -1 : !e.pre && t.pre ? 1 : e.pre && t.pre ? e.pre < t.pre ? -1 : +(e.pre > t.pre) : 0 : e.patch - t.patch : e.minor - t.minor : e.major - t.major, Oe = (e, t) => {
+	if (e === "*") return !0;
+	if (e.startsWith("^")) {
+		let n = O(e.slice(1));
+		return !n || t.major !== n.major ? !1 : k(t, n) >= 0;
+	}
+	if (e.startsWith("~")) {
+		let n = O(e.slice(1));
+		return !n || t.major !== n.major || t.minor !== n.minor ? !1 : k(t, n) >= 0;
+	}
+	let n = /^(>=|<=|>|<)(.+)$/.exec(e);
+	if (n) {
+		let e = n[1], r = O(n[2]);
+		if (!r) return !1;
+		let i = k(t, r);
+		if (e === ">=") return i >= 0;
+		if (e === "<=") return i <= 0;
+		if (e === ">") return i > 0;
+		if (e === "<") return i < 0;
+	}
+	let r = O(e);
+	return r ? k(t, r) === 0 : !1;
+}, A = c.Literal("running", "succeeded", "failed", "cancelled", "suspended"), j = c.Literal("cancel", "terminate", "abandon"), ke = c.Struct({
+	id: c.String,
+	workflowName: c.String,
+	executionId: c.String,
+	status: c.Literal("running")
+}), M = c.Struct({
+	id: c.String,
+	tag: c.String,
+	executionId: c.String,
+	status: A,
+	payload: c.Unknown,
+	workflowVersion: c.NullOr(c.String),
+	workflowPatches: c.NullOr(c.Unknown),
+	output: c.NullOr(c.Unknown),
+	subject: c.NullOr(c.Unknown),
+	source: c.NullOr(c.String),
+	errorTag: c.NullOr(c.String),
+	errorMessage: c.NullOr(c.String),
+	cancelled: c.Boolean,
+	startedAt: c.Date,
+	completedAt: c.NullOr(c.Date),
+	durationMs: c.NullOr(c.Number),
+	traceId: c.NullOr(c.String),
+	parentExecutionId: c.NullOr(c.String),
+	parentClosePolicy: c.NullOr(j)
+}), N = c.Struct({
+	tag: c.optional(c.String),
+	status: c.optional(A),
+	limit: c.optional(c.Number)
+}), P = c.Struct({
+	id: c.String,
+	runId: c.String,
+	stepName: c.String,
+	attempt: c.Number,
+	status: c.Literal("running", "succeeded", "failed"),
+	input: c.NullOr(c.Unknown),
+	retryPolicy: c.NullOr(c.Unknown),
+	output: c.NullOr(c.Unknown),
+	errorTag: c.NullOr(c.String),
+	errorMessage: c.NullOr(c.String),
+	errorCause: c.NullOr(c.Unknown),
+	startedAt: c.Date,
+	completedAt: c.NullOr(c.Date),
+	durationMs: c.NullOr(c.Number)
+}), F = c.Struct({
+	id: c.String,
+	runId: c.String,
+	eventType: c.String,
+	payload: c.NullOr(c.Unknown),
+	occurredAt: c.Date,
+	stepName: c.NullOr(c.String),
+	attempt: c.NullOr(c.Number)
+}), I = c.Struct({
+	id: c.String,
+	name: c.String,
+	payload: c.Unknown,
+	source: c.String,
+	subject: c.NullOr(c.Unknown),
+	traceId: c.NullOr(c.String),
+	occurredAt: c.Date
+}), L = c.Struct({
+	id: c.String,
+	eventId: c.String,
+	eventName: c.String,
+	triggerId: c.String,
+	workflowName: c.String,
+	executionId: c.NullOr(c.String),
+	status: c.Literal("starting", "started", "skipped", "failed"),
+	idempotencyKey: c.String,
+	skipped: c.Boolean,
+	errorMessage: c.NullOr(c.String),
+	createdAt: c.Date,
+	completedAt: c.NullOr(c.Date)
+}), R = c.Struct({ id: c.String }), z = c.Struct({ runId: c.String }), B = c.Struct({
+	name: c.optional(c.String),
+	limit: c.optional(c.Number)
+}), V = c.Struct({ eventId: c.String }), H = c.Struct({
+	workflowName: c.String,
+	executionId: c.String
+}), U = c.Struct({
+	id: c.String,
+	signalName: c.String,
+	payload: c.optional(c.Unknown)
+}), W = c.Struct({
+	id: c.String,
+	updateName: c.String,
+	payload: c.optional(c.Unknown),
+	timeoutMs: c.optional(c.Number)
+}), G = c.Struct({
+	eventId: c.String,
+	updateId: c.String,
+	completedEventId: c.String,
+	result: c.Unknown
+}), Ae = g({
+	name: "__voltro.workflow.run",
+	source: "_voltro_workflow_runs",
+	input: R,
+	output: c.Array(M)
+}), je = g({
+	name: "__voltro.workflow.runs",
+	source: "_voltro_workflow_runs",
+	input: N,
+	output: c.Array(M)
+}), Me = g({
+	name: "__voltro.workflow.run.steps",
+	source: "_voltro_workflow_run_steps",
+	input: z,
+	output: c.Array(P)
+}), Ne = g({
+	name: "__voltro.workflow.run.events",
+	source: "_voltro_workflow_run_events",
+	input: z,
+	output: c.Array(F)
+}), Pe = g({
+	name: "__voltro.workflow.domainEvents",
+	source: "_voltro_workflow_events",
+	input: B,
+	output: c.Array(I)
+}), Fe = g({
+	name: "__voltro.workflow.event.deliveries",
+	source: "_voltro_workflow_event_deliveries",
+	input: V,
+	output: c.Array(L)
+}), Ie = v({
+	name: "__voltro.workflow.cancel",
+	input: H,
+	output: c.Struct({ ok: c.Boolean })
+}), Le = v({
+	name: "__voltro.workflow.resume",
+	input: H,
+	output: c.Struct({ ok: c.Boolean })
+}), Re = v({
+	name: "__voltro.workflow.signal",
+	input: U,
+	output: c.Struct({ eventId: c.String })
+}), ze = v({
+	name: "__voltro.workflow.update",
+	input: W,
+	output: G
+}), K = "__voltro.undo.log", q = "__voltro.undo.apply", J = "__voltro.undo.redo", Y = c.Struct({
+	id: c.String,
+	tag: c.String,
+	label: c.NullOr(c.String),
+	undone: c.Boolean,
+	crossesAction: c.Boolean,
+	createdAt: c.String
+}), X = class extends c.TaggedError()("UndoNotFound", { invocationId: c.String }) {}, Z = class extends c.TaggedError()("UndoForbidden", { invocationId: c.String }) {}, Q = class extends c.TaggedError()("UndoConflict", {
+	invocationId: c.String,
+	reason: c.Literal("conflict", "action")
+}) {}, $ = c.Union(X, Z, Q), Be = g({
+	name: K,
+	source: "_voltro_undo_log",
+	input: c.Struct({ limit: c.optional(c.Number) }),
+	output: c.Array(Y)
+}), Ve = _({
+	name: q,
+	input: c.Struct({ invocationId: c.String }),
+	output: c.Struct({ ok: c.Boolean }),
+	error: $
+}), He = _({
+	name: J,
+	input: c.Struct({ invocationId: c.String }),
+	output: c.Struct({ ok: c.Boolean }),
+	error: $
+}), Ue = (e) => {
+	let t = e instanceof Date ? e.getTime() : typeof e == "number" ? e : typeof e == "string" ? new Date(e).getTime() : 0;
+	return Number.isNaN(t) ? 0 : t;
+}, We = 1;
+//#endregion
+export { ae as ADMIN_SCOPE, ne as AuthMiddleware, o as ConnectionInfo, te as ConnectionInfoMiddleware, We as PROTOCOL_VERSION, le as ScopeError, i as Subject, e as SubjectService, q as UNDO_APPLY_TAG, K as UNDO_LOG_TAG, J as UNDO_REDO_TAG, ee as Unauthenticated, Q as UndoConflict, Z as UndoForbidden, Y as UndoLogEntry, X as UndoNotFound, H as WorkflowControlInputSchema, I as WorkflowDomainEventRowSchema, B as WorkflowDomainEventsInputSchema, V as WorkflowEventDeliveriesInputSchema, L as WorkflowEventDeliveryRowSchema, j as WorkflowParentClosePolicySchema, F as WorkflowRunEventRowSchema, ke as WorkflowRunHandleSchema, R as WorkflowRunRefSchema, M as WorkflowRunRowSchema, A as WorkflowRunStatusSchema, P as WorkflowRunStepRowSchema, z as WorkflowRunTableRefSchema, N as WorkflowRunsInputSchema, U as WorkflowSignalInputSchema, W as WorkflowUpdateInputSchema, G as WorkflowUpdateResultSchema, S as actionToRpc, s as anonymousSubject, Ce as applyRowPatch, t as assertAuthenticated, fe as beginIdempotent, De as checkFrameworkCompat, a as composeAuthStrategies, E as composeRpcInterceptors, v as defineAction, _ as defineMutation, w as definePlugin, T as definePluginRoute, D as definePluginService, g as defineQuery, we as defineStream, xe as diffRows, ce as failIdempotent, ie as finishIdempotent, re as hasCallbackRoutes, he as hasScope, p as idToPath, de as idempotencyScope, Se as isIdKeyed, n as isSystemSubject, pe as memoryIdempotencyStore, x as mutationToRpc, Ee as normalizeDescriptor, ye as pathToId, me as publishServerError, b as queryToRpc, oe as requireScope, d as rowPatchOpSchema, f as rowPatchSchema, C as streamToRpc, se as subjectScopes, ue as subscribeServerErrors, h as subscriptionEvent, r as systemSubject, Te as toRpc, Ue as tsMs, Ve as undoApplyDescriptor, Be as undoLogQueryDescriptor, He as undoRedoDescriptor, Ie as workflowCancelDescriptor, Pe as workflowDomainEventsQueryDescriptor, Fe as workflowEventDeliveriesQueryDescriptor, Le as workflowResumeDescriptor, Ne as workflowRunEventsQueryDescriptor, Ae as workflowRunQueryDescriptor, Me as workflowRunStepsQueryDescriptor, je as workflowRunsQueryDescriptor, Re as workflowSignalDescriptor, ze as workflowUpdateDescriptor };

package/dist/jwt.d.ts

@@ -0,0 +1,230 @@
+import { Schema } from 'effect';
+
+/** Pluggable auth strategy. Strategies are SYNC-fast on no-match
+ *  (cookie-name lookup) and cache any JWKS / DB roundtrips on match
+ *  so steady-state verification stays CPU-local. */
+declare interface AuthStrategy {
+    /** Stable id (`'voltro-password'`, `'workos'`, `'kinde'`, …). Used
+     *  in logs + `Subject.metadata.provider`. */
+    readonly id: string;
+    readonly resolve: (input: AuthStrategyInput) => Promise<StrategyResolution> | StrategyResolution;
+}
+
+/** Per-call input the framework hands every strategy. */
+declare interface AuthStrategyInput {
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    readonly clientId: number;
+}
+
+/**
+ * Fetch (and per-URL cache) an OIDC discovery document — the
+ * `.well-known/openid-configuration` an IdP publishes so consumers can
+ * resolve `jwks_uri` without hard-coding it. One shared cached fetcher for
+ * every `@voltro/plugin-auth-*` adapter that does OIDC discovery, so the
+ * `Map<url, Promise>` lives once at this layer instead of being re-rolled per
+ * adapter. Successful lookups are cached for the process lifetime; FAILED
+ * lookups are evicted so the next call retries (transient DNS / 5xx). Pure
+ * `fetch` — browser-safe, no Node deps.
+ */
+export declare const discoverOidc: (url: string) => Promise<OidcDiscoveryDocument>;
+
+/** Pull a JWT from either `Authorization: Bearer …` or the named cookie.
+ *  Returns undefined when neither is present (strategy returns `skip`). */
+export declare const extractBearerOrCookie: (headers: Readonly<Record<string, string | undefined>>, cookieName: string | null) => string | undefined;
+
+/**
+ * JWKS-backed verification (asymmetric: ES256/RS256/PS256/EdDSA) — the
+ * default for hosted IdPs that publish a JWKS endpoint. Tokens are
+ * verified against the fetched public keys; HMAC algorithms are rejected.
+ */
+export declare interface JwtBearerJwksConfig extends JwtBearerStrategyBase {
+    /** JWKS endpoint URL. Plugin sets the provider-specific default. */
+    readonly jwksUrl: string;
+    readonly jwtSecret?: never;
+    /** JWT algorithm allowlist. Defaults to `['ES256', 'RS256']`. Plugins
+     *  override when their IdP signs with PS256/EdDSA. */
+    readonly algorithms?: ReadonlyArray<'ES256' | 'RS256' | 'PS256' | 'EdDSA'>;
+}
+
+/**
+ * Shared-secret verification (symmetric HMAC: HS256/384/512) — for IdPs
+ * that sign tokens with a shared secret and expose no JWKS, e.g. legacy /
+ * self-hosted Supabase (`JWT_SECRET`). The secret is a SERVER-side value
+ * and must never reach the browser bundle.
+ */
+export declare interface JwtBearerSecretConfig extends JwtBearerStrategyBase {
+    /** Shared HMAC secret the IdP signs its tokens with. */
+    readonly jwtSecret: string;
+    readonly jwksUrl?: never;
+    /** JWT algorithm allowlist. Defaults to `['HS256']`. */
+    readonly algorithms?: ReadonlyArray<'HS256' | 'HS384' | 'HS512'>;
+}
+
+export declare const jwtBearerStrategy: (config: JwtBearerStrategyConfig) => AuthStrategy;
+
+declare interface JwtBearerStrategyBase {
+    /** Stable id — `'workos' | 'kinde' | 'clerk' | …`. Used in logs and
+     *  stamped onto `Subject.metadata.provider`. */
+    readonly id: string;
+    /** Expected issuer claim(s). Passed straight to the verifier. */
+    readonly issuer?: string | ReadonlyArray<string>;
+    /** Expected audience claim(s). */
+    readonly audience?: string | ReadonlyArray<string>;
+    /** Cookie name when the JWT travels as a cookie. Pass `null` to
+     *  disable cookie fallback (header-only mode). */
+    readonly cookieName?: string | null;
+    /** Map verified JWT claims to a Voltro tenantId. Most IdPs put an
+     *  org reference somewhere in the claims; plugins wire it here.
+     *  Returning `null` is treated as `failed` — the strategy IS the
+     *  request's owner but it can't satisfy the tenant invariant. */
+    readonly tenantIdFromClaims: (claims: Record<string, unknown>) => string | null;
+    /** Override how the Subject's `id` is derived from the claims.
+     *  Defaults to `claims.sub`. Plugins set this when an IdP uses a
+     *  custom subject identifier. */
+    readonly subjectIdFromClaims?: (claims: Record<string, unknown>) => string;
+    /**
+     * Map verified JWT claims to the subject's permission scopes. The
+     * returned list lands on `Subject.scopes`, so `requireScope` /
+     * `hasScope` (`@voltro/protocol`) gate handlers off the IdP's claims
+     * with NO second lookup. Typical shapes: a space-delimited OAuth
+     * `scope` string (`(c) => String(c.scope ?? '').split(' ').filter(Boolean)`),
+     * an Auth0 `permissions` array, a Kinde `roles[].key` list. Omitted →
+     * `Subject.scopes` stays undefined (the unchanged default; a
+     * handler-side scope gate then denies). Return `[]` to grant none.
+     */
+    readonly scopesFromClaims?: (claims: Record<string, unknown>) => ReadonlyArray<string>;
+}
+
+/** JWT-based strategy config — verified EITHER via a JWKS endpoint
+ *  (`jwksUrl`, asymmetric) OR a shared HMAC secret (`jwtSecret`,
+ *  symmetric). The two are mutually exclusive. */
+export declare type JwtBearerStrategyConfig = JwtBearerJwksConfig | JwtBearerSecretConfig;
+
+/** Thrown by `verifyJwt` on signature mismatch / expiry / claim
+ *  mismatch / unsupported algorithm. Strategies catch + downgrade
+ *  to `StrategyResolution.failed`. */
+export declare class JwtVerifyError extends Error {
+    readonly code: 'signature_mismatch' | 'expired' | 'not_yet_valid' | 'issuer_mismatch' | 'audience_mismatch' | 'unsupported_algorithm' | 'malformed' | 'jwks_unreachable' | 'other';
+    constructor(message: string, code: 'signature_mismatch' | 'expired' | 'not_yet_valid' | 'issuer_mismatch' | 'audience_mismatch' | 'unsupported_algorithm' | 'malformed' | 'jwks_unreachable' | 'other');
+}
+
+/** The subset of an OIDC discovery document the framework reads. Providers
+ *  ship many more fields; only `jwks_uri` is load-bearing for verification. */
+export declare interface OidcDiscoveryDocument {
+    readonly issuer: string;
+    readonly jwks_uri: string;
+    readonly [key: string]: unknown;
+}
+
+/**
+ * Read a nested claim by dot-path (`'app_metadata.tenant_id'`,
+ * `'https://acme/tenant'`, `'org.id'`). Every IdP adapter that resolves a
+ * tenant / scope from a NESTED claim needs the same safe walk — this is the
+ * one shared implementation so they don't each re-derive it (and subtly
+ * diverge on the null-guard). Pure + browser-safe: no IO, no deps.
+ *
+ * A path with no `.` is a plain top-level key lookup. Any missing / non-object
+ * segment short-circuits to `undefined` (never throws on `null`/primitive
+ * intermediates). The returned value is untyped — callers narrow it.
+ */
+export declare const readClaimPath: (claims: Record<string, unknown>, path: string) => unknown;
+
+/**
+ * Read a cookie value by name from a `Cookie:` header string.
+ * Returns undefined if the cookie isn't present.
+ */
+export declare const readCookie: (header: string | undefined, name: string) => string | undefined;
+
+/** Test-only: clear the cache. Lets tests + dev-mode hot-reload skip
+ *  the per-process global cache between runs. */
+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;
+} | {
+    readonly kind: 'skip';
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+
+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;
+
+/** Verify a JWT against a remote JWKS. Returns the decoded claims on
+ *  success. Throws `JwtVerifyError` on any verification failure. */
+export declare const verifyJwt: (jwt: string, jwksUrl: string, options?: VerifyJwtOptions) => Promise<Record<string, unknown>>;
+
+export declare interface VerifyJwtOptions {
+    /** Expected `iss` claim. String or list of acceptable issuers. */
+    readonly issuer?: string | ReadonlyArray<string>;
+    /** Expected `aud` claim. Most IdPs set audience = your `clientId`. */
+    readonly audience?: string | ReadonlyArray<string>;
+    /** Clock skew tolerance in seconds. Default: 60s. */
+    readonly clockToleranceS?: number;
+    /** Algorithm allowlist. Default: ['ES256', 'RS256']. */
+    readonly algorithms?: ReadonlyArray<'ES256' | 'RS256' | 'PS256' | 'EdDSA'>;
+    /** Override the per-JWKS cache TTL. Default 1h. */
+    readonly jwksCacheTtlMs?: number;
+}
+
+/** Verify a JWT against a shared HMAC secret (HS256/384/512). For IdPs
+ *  that sign tokens SYMMETRICALLY and expose no JWKS endpoint — e.g.
+ *  legacy / self-hosted Supabase (the project's `JWT_SECRET`). The
+ *  asymmetric `verifyJwt` (JWKS) intentionally rejects HMAC algorithms;
+ *  this is its symmetric counterpart. The secret is a server-side value
+ *  — it must never reach the browser bundle. Returns the decoded claims
+ *  on success; throws `JwtVerifyError` (same shape as `verifyJwt`). */
+export declare const verifyJwtWithSecret: (jwt: string, secret: string, options?: VerifyJwtWithSecretOptions) => Promise<Record<string, unknown>>;
+
+export declare interface VerifyJwtWithSecretOptions {
+    /** Expected `iss` claim. String or list of acceptable issuers. */
+    readonly issuer?: string | ReadonlyArray<string>;
+    /** Expected `aud` claim. */
+    readonly audience?: string | ReadonlyArray<string>;
+    /** Clock skew tolerance in seconds. Default: 60s. */
+    readonly clockToleranceS?: number;
+    /** Algorithm allowlist. Default: ['HS256']. */
+    readonly algorithms?: ReadonlyArray<'HS256' | 'HS384' | 'HS512'>;
+}
+
+export { }