@voltro/runtime 0.11.4 → 0.12.0

package/dist/index.d.ts

@@ -673,6 +673,11 @@ export declare interface ApiKeyRow {
     readonly keyPrefix: string;
     readonly scopes: ReadonlyArray<string> | null;
     readonly lastUsedAt: number | null;
+    /** WHO THE KEY ACTS AS — null for an org key. Distinct from `createdBy`. */
+    readonly onBehalfOf?: string | null;
+    /** Coarse usage counter, buffered — see `apiKeyUsage.ts`. Optional on the type
+     *  because a row written before the column existed reads back without it. */
+    readonly requestCount?: number;
     readonly expiresAt: number | null;
     readonly revokedAt: number | null;
     readonly createdBy: string | null;
@@ -692,10 +697,28 @@ export declare interface ApiKeyServiceShape {
     readonly resolveByHash: (hash: string, now?: number) => Promise<ResolvedApiKey | null>;
     /** Verify a raw token (hashes then resolves). */
     readonly verify: (token: string, now?: number) => Promise<ResolvedApiKey | null>;
-    /** Revoke a key (irreversible). */
-    readonly revoke: (id: string, now?: number) => Promise<boolean>;
-    /** Rotate: revoke the old key + issue a replacement with the same name/scopes/tenant. */
-    readonly rotate: (id: string, now?: number) => Promise<IssuedApiKey | null>;
+    /**
+     * Revoke a key (irreversible).
+     *
+     * `tenantId` is the CALLER's tenant and is REQUIRED, not optional: a key id is
+     * the only thing needed to revoke, and ids leak (logs, support tickets, an
+     * error message). Without this check an admin of tenant A could revoke tenant
+     * B's key by id — the guard on the route asks "is an admin", never "an admin
+     * of THIS key's tenant". Returns `false` for a key belonging to anyone else,
+     * indistinguishable from "no such key", so it cannot be used to probe.
+     *
+     * Pass `null` only for the tenant-less system key space. There is deliberately
+     * no "skip the check" value: an optional scope on a destructive operation is a
+     * scope somebody forgets.
+     */
+    readonly revoke: (id: string, tenantId: string | null, now?: number) => Promise<boolean>;
+    /**
+     * Rotate: revoke the old key + issue a replacement with the same
+     * name/scopes/tenant. Same required tenant scope as `revoke`, and here it
+     * matters more — rotate RETURNS A USABLE TOKEN, so an unscoped version would
+     * hand the caller a working credential for another tenant.
+     */
+    readonly rotate: (id: string, tenantId: string | null, now?: number) => Promise<IssuedApiKey | null>;
     /** List a tenant's keys (no secrets). */
     readonly list: (tenantId: string | null) => Promise<ReadonlyArray<PublicApiKey>>;
 }
@@ -708,6 +731,38 @@ export declare interface ApiKeyStore {
     readonly patch: (id: string, fields: Partial<ApiKeyRow>) => Promise<void>;
 }
 
+export declare interface ApiKeyUsageBuffer {
+    /** Record one use. Synchronous, no I/O. */
+    readonly touch: (id: string, at?: number) => void;
+    /** Write everything pending now. */
+    readonly flushNow: () => Promise<void>;
+    /** Flush and stop the timer. Idempotent. */
+    readonly shutdown: () => Promise<void>;
+    /** Pending key count — for tests and the inspect surface. */
+    readonly pending: () => number;
+}
+
+export declare interface ApiKeyUsageBufferOptions {
+    /** Apply one key's accumulated window. Must ADD `requests` to the stored
+     *  count and move `lastUsedAt` forward — never assign either, or a second
+     *  replica's window overwrites this one. */
+    readonly flush: (id: string, delta: ApiKeyUsageDelta) => Promise<void>;
+    /** Flush cadence. Default 30s. */
+    readonly intervalMs?: number;
+    /** Flush early once this many distinct keys are pending, so a burst across
+     *  many keys doesn't sit unbounded in memory for a whole window. Default 500. */
+    readonly maxPending?: number;
+    /** Injectable for tests. */
+    readonly now?: () => number;
+}
+
+export declare interface ApiKeyUsageDelta {
+    /** Requests counted for this key in the flushed window. Always ≥ 1. */
+    readonly requests: number;
+    /** The latest use observed in the window (epoch ms). */
+    readonly lastUsedAt: number;
+}
+
 /**
  * Typed authorization slice on `ctx.access` — the ergonomic, cast-free face of
  * the caller's EFFECTIVE scope set (raw subject scopes ∪ rbac role-derived
@@ -731,6 +786,28 @@ export declare interface AppAccess {
 
 export declare interface AppContext {
     readonly store: FluentStore;
+    /**
+     * The same store, scoped to ONE tenant.
+     *
+     * For non-request work — a schedule, a subscriber, a workflow step — whose
+     * subject is `system` with `tenantId: null`. Reads there see every tenant and
+     * a write to a `tenant()` table fails with `TenantScopeViolation`, so a
+     * per-tenant cron has to say which tenant it means. Every fan-out cron is
+     * literally a loop doing this by hand, and doing it by hand means each
+     * `.where('tenantId', t.id)` is one forgotten call away from reading the whole
+     * table:
+     *
+     *   for (const t of await ctx.store.select('tenants').all()) {
+     *     const scoped = ctx.storeForTenant(t.id)
+     *     await scoped.insert('digests', { … })   // tenantId stamped, not passed
+     *   }
+     *
+     * Inside a REQUEST this is almost always the wrong tool: the subject already
+     * carries a tenant, and reaching for another one is a cross-tenant read with
+     * extra steps. It exists because the system subject has no tenant to infer,
+     * not to let a request pick a different one.
+     */
+    readonly storeForTenant: (tenantId: string) => FluentStore;
     readonly request: RuntimeContext;
     /** Typed authorization slice — the caller's effective scopes. Use
      *  `ctx.access.has(scope)` / `yield* ctx.access.require(scope)` instead of
@@ -1560,7 +1637,7 @@ export declare const crud: {
      *
      *     export default crud.count('absenceRequests', { filter: (i) => ({ status: i.status }) })
      */
-    count: (table: string, options?: Pick<CrudListOptions, "filter">) => (input: unknown, ctx: AppContext) => Promise<number>;
+    count: (table: string, options?: Pick<CrudListOptions, "filter" | "scope">) => (input: unknown, ctx: AppContext) => Promise<number>;
     /** Delete a row by id; returns `{ deleted }`. Guard the DESCRIPTOR. */
     remove: (table: string) => (input: {
         readonly id: string;
@@ -1586,8 +1663,33 @@ export declare interface CrudListOptions extends CrudReadOptions {
      * is simply ignored (`{ employeeId: input.employeeId, status: input.status }`).
      * The descriptor's `input` schema declares those fields; this maps them to a
      * scoped `.where(column, value)` on the store query.
+     *
+     * Request input ONLY, on purpose — see `scope` for the caller-derived half.
      */
     readonly filter?: (input: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>;
+    /**
+     * The caller-derived WHERE — what this subject may SEE, as opposed to what it
+     * asked for. Merged into the same query as `filter`, and it WINS on a key
+     * collision, so a caller cannot widen its own scope by sending that field.
+     *
+     *   scope: (ctx) => ({ ownerId: ctx.request.subject.id })
+     *
+     * Why this is a SEPARATE option rather than a second argument to `filter`:
+     * the two answer different questions, and only one of them is a security
+     * boundary. Kept apart, "does this list declare a `scope`?" is a question a
+     * reviewer — or a future boot audit — can actually ask. Folded into `filter`,
+     * it becomes "does this filter happen to read ctx somewhere in its body?",
+     * which nothing can check.
+     *
+     * The gap this closes: tenant scope is applied automatically, but anything
+     * narrower — owner, team, role — was not expressible at all. Replacing a
+     * hand-written handler that carried such a narrowing with `crud.list`
+     * therefore WIDENED the result set, silently and with no error. One app lost
+     * exactly that across eight list views.
+     *
+     * Pass the same `scope` to `crud.count`, or the total contradicts the pages.
+     */
+    readonly scope?: (ctx: AppContext) => Readonly<Record<string, unknown>>;
     /**
      * Page the result from the request. BOTH styles are accepted, so a caller uses
      * whichever its UI thinks in:
@@ -1683,7 +1785,6 @@ export declare interface DataLoader {
 
 export { DataStore }
 
-/** DataStore-backed store over `_voltro_api_keys`. */
 export declare const dataStoreApiKeyStore: (store: DataStore) => ApiKeyStore;
 
 export declare const dataStoreIdempotencyStore: (store: DataStore) => IdempotencyStore;
@@ -1761,7 +1862,7 @@ export declare const defineEventTrigger: <EventPayload = unknown, WorkflowPayloa
  * Runtime identity — returns `fn` unchanged; the whole value is the compile-time
  * check. See the module header for the failure it prevents.
  */
-export declare const defineExecutor: <D extends ExecutorDescriptor, E = never, R = never>(_descriptor: D, fn: (input: ExecutorInput<D>, ctx: AppContext) => ExecutorReturn<D, E, R>) => ((input: ExecutorInput<D>, ctx: AppContext) => ExecutorReturn<D, E, R>);
+export declare const defineExecutor: <D extends ExecutorDescriptor, F extends (input: ExecutorInput<D>, ctx: AppContext) => ExecutorReturn<D, unknown, unknown>>(_descriptor: D, fn: F) => ((input: ExecutorInput<D>, ctx: AppContext) => ReturnType<F>);
 
 /**
  * Declare who delivers an effect. One per `*.outbox.ts` file.
@@ -2026,6 +2127,10 @@ export declare interface EffectStoreOps {
  *  discovered tables. */
 export declare const emptySchemaRegistry: SchemaRegistry;
 
+/** Turn recording on from code. Idempotent. Must run BEFORE the stores that
+ *  should be observed are constructed — `observeStore` decides once, per store. */
+export declare const enableGraphObservation: () => void;
+
 /** Encrypt a value with the registered field cipher (same one `.encrypted()`
  *  columns use). Throws if no cipher is registered. */
 export declare const encryptField: (plaintext: string) => string;
@@ -2545,6 +2650,8 @@ export declare const isIdleNow: (opts: IdleCheckOptions) => Promise<boolean>;
 
 export declare const isInfraError: (e: unknown) => boolean;
 
+export declare const isObservingGraph: () => boolean;
+
 /**
  * A subject that AUTHENTICATED but resolved with NO active org — a `user` (not
  * `anonymous`/`system`) carrying the empty-string tenant sentinel. Every
@@ -2585,7 +2692,12 @@ export declare interface IssueInput {
     readonly name: string;
     readonly scopes?: ReadonlyArray<string>;
     readonly expiresAt?: Date | number | null;
+    /** WHO MINTED IT. Provenance — set it always, including for an org key. */
     readonly createdBy?: string | null;
+    /** WHO IT ACTS AS. Omit for an ORG key (acts as no person); set it for a
+     *  personal key, which may be the minter or — when an admin mints for a
+     *  colleague — someone else entirely. */
+    readonly onBehalfOf?: string | null;
 }
 
 export declare const isWorkflowEventTriggerDefinition: (value: unknown) => value is WorkflowEventTriggerDefinition;
@@ -2808,8 +2920,30 @@ export declare const makeAesCipher: (key: Buffer) => FieldCipher;
 
 export declare const makeApiKeyService: (store: ApiKeyStore, opts?: {
     prefix?: string;
+    /** Buffers `lastUsedAt` + `requestCount` instead of writing a row per auth
+     *  check. Omit to keep the synchronous stamp (see `resolveByHash`). */
+    usage?: ApiKeyUsageBuffer;
 }) => ApiKeyServiceShape;
 
+export declare const makeApiKeyUsageBuffer: (options: ApiKeyUsageBufferOptions) => ApiKeyUsageBuffer;
+
+/**
+ * The flusher a buffered `ApiKeyUsageBuffer` is built with: read-modify-write of
+ * `requestCount` + `lastUsedAt` for one key, once per window.
+ *
+ * Not atomic across replicas, and that is a deliberate limit rather than an
+ * oversight. Two pods flushing the same key in the same instant can lose one
+ * window's delta. Making it exact would need a dialect-specific
+ * `SET requestCount = requestCount + ?`, which is real complexity in service of
+ * a field whose stated purpose is "is this key still in use, and roughly how
+ * much". If this number ever needs to be exact, that is the signal it is being
+ * used for something it was not built for (billing), not a signal to add locking.
+ */
+export declare const makeApiKeyUsageFlusher: (store: ApiKeyStore) => (id: string, delta: {
+    readonly requests: number;
+    readonly lastUsedAt: number;
+}) => Promise<void>;
+
 /** Build the `ctx.access` slice for a subject. Reads the effective-scope seam
  *  LIVE (via getters/closures) so a scope rbac resolves after context
  *  construction is still reflected. Used by the shared AppContext builder AND
@@ -3371,6 +3505,50 @@ export declare interface OAuth2ConnectionDefinition extends ConnectionDefinition
     readonly identify?: (tokens: ConnectionTokens) => Promise<ConnectionAccount>;
 }
 
+/** One recorded `(procedure → table, op)` edge. */
+export declare interface ObservedEdge {
+    readonly tag: string;
+    readonly kind: ObservedProcedure['kind'];
+    readonly table: string;
+    readonly op: ObservedOp;
+}
+
+export declare interface ObservedGraph {
+    /** Schema version of this file's shape, so `check` can refuse an old one
+     *  loudly instead of silently diffing against a different meaning. */
+    readonly version: 1;
+    readonly edges: ReadonlyArray<ObservedEdge>;
+    /** Tags seen entering the recorder at all — the difference between "this
+     *  procedure touched no table" and "this procedure never ran", which is the
+     *  distinction the whole feature stands on. */
+    readonly exercised: ReadonlyArray<string>;
+}
+
+/** Snapshot everything recorded so far. */
+export declare const observedGraph: () => ObservedGraph;
+
+/** What a procedure did to a table. `read` covers every query path. */
+export declare type ObservedOp = 'read' | 'insert' | 'update' | 'delete' | 'upsert';
+
+export declare interface ObservedProcedure {
+    /** The procedure's effective rpc tag (`notes.create`). */
+    readonly tag: string;
+    readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'schedule' | 'workflow';
+}
+
+/**
+ * Wrap a `DataStore` so every operation is recorded. Returns the store unchanged
+ * when recording is off, so the production path keeps the exact same object
+ * (no added indirection, no added allocation).
+ *
+ * Wrapping the store BENEATH the mixin middleware rather than instrumenting the
+ * middleware's ~20 public methods is deliberate: those methods delegate to each
+ * other (`one`/`first`/`maybeOne` all go through `query`), so instrumenting them
+ * individually would double-count some paths and miss any new one. Underneath,
+ * each operation passes exactly once.
+ */
+export declare const observeStore: <S extends object>(store: S) => S;
+
 /**
  * Listen for re-bind events. Returns an unsubscribe function. Used by
  * the dispatcher to re-scope active subscriptions when a connection's
@@ -3565,6 +3743,24 @@ export declare interface PatConnectionDefinition extends ConnectionDefinitionCom
     readonly validate?: (token: string) => Promise<ConnectionAccount>;
 }
 
+/**
+ * TOP-LEVEL property names of a struct-ish schema, split by optionality.
+ *
+ * Deliberately not `schemaPropertyNames` (`./serverOnlyAudit`), which answers a
+ * DIFFERENT question: that one walks the whole schema recursively and flattens
+ * every name at any depth, because a leak check cares whether a column name
+ * appears anywhere in an output. This one asks "what does this payload require
+ * at its top level", so depth would be wrong and optionality is the point.
+ *
+ * Best effort — at runtime it only makes an error readable and never decides
+ * validity — but `voltro doctor`'s static `workflows.start` audit calls the same
+ * function, so the two cannot disagree about what a payload requires.
+ */
+export declare const payloadPropertyNames: (schema: Schema.Schema.Any) => {
+    readonly required: ReadonlyArray<string>;
+    readonly optional: ReadonlyArray<string>;
+};
+
 /** The 3-arg signature a plugin sees on its bind-ctx. */
 export declare type PluginScheduleCoordinated = (name: string, intervalMs: number, effect: () => void | Promise<void>) => CoordinatedScheduleHandle;
 
@@ -3855,6 +4051,14 @@ export declare const recordSubscriptionActive: (label: string, delta: number) =>
  *  latency + a delivery counter. Rides the framework's existing per-delivery tap. */
 export declare const recordSubscriptionDelivery: (d: SubscriptionDeliveryRecord) => void;
 
+/**
+ * Record one table access against the procedure on the current fiber. Silently
+ * ignored outside a procedure scope — background work (migrations, the
+ * scheduler's own bookkeeping, plugin boot) is not a procedure and must not
+ * invent edges for one.
+ */
+export declare const recordTableAccess: (table: string, op: ObservedOp) => void;
+
 /** Feed a committed change into the process recorder (gated + loop-safe). The
  *  serve paths call this from their `store.onChange` tap. */
 export declare const recordTimelineEvent: (change: CdcChange & {
@@ -4225,6 +4429,9 @@ export declare interface ResendOptions {
 /** Test/dev-only — clear ALL overrides. Don't call from app code. */
 export declare const _resetConnectionSubjectsForTest: () => void;
 
+/** Drop everything recorded. For tests; not called by the runtime. */
+export declare const resetObservedGraph: () => void;
+
 /** Reset to the env default (tests). */
 export declare const resetSecretsBackend: () => void;
 
@@ -4276,9 +4483,11 @@ export declare const resolveCurrentRegion: (env?: NodeJS.ProcessEnv) => string |
 export declare interface ResolvedApiKey {
     readonly id: string;
     readonly tenantId: string;
-    /** The user who created the key, when one is recorded. Null for a key minted
-     *  outside a user session (bootstrap / admin tooling). */
+    /** WHO MINTED the key. Provenance — present for org keys too. */
     readonly createdBy: string | null;
+    /** WHO THE KEY ACTS AS. `null` = an ORG key. This is the identity attribution
+     *  follows and the one the Subject carries as `metadata.userId`. */
+    readonly onBehalfOf: string | null;
     readonly scopes: ReadonlyArray<string>;
 }
 
@@ -4755,6 +4964,16 @@ export declare const runWithDeadlockRetry: <T>(work: () => Promise<T>, options?:
     readonly delay?: (attempt: number) => Promise<void>;
 }) => Promise<T>;
 
+/**
+ * Run `work` attributed to `procedure`. Every store operation performed inside
+ * (or in its async children) is recorded against that tag.
+ *
+ * A no-op when recording is off, including the ALS entry itself — an
+ * AsyncLocalStorage `run` on every rpc call is not free, and a disabled feature
+ * should cost nothing.
+ */
+export declare const runWithObservedProcedure: <T>(procedure: ObservedProcedure, work: () => T) => T;
+
 /**
  * Run `work` inside a routing scope. Every `query()` call against a
  * `ReplicatedDataStore` from inside `work` (or its async children)
@@ -5381,6 +5600,51 @@ export declare const snapshotMetrics: Effect.Effect<ReadonlyArray<MetricSample>>
 /** Eager snapshot for sync callers (the inspect endpoint). */
 export declare const snapshotMetricsSync: () => ReadonlyArray<MetricSample>;
 
+/** Thrown (as a typed defect) when a request targets a blocked address. */
+export declare class SsrfBlockedError extends Error {
+    readonly url: string;
+    readonly reason: string;
+    readonly _tag = "SsrfBlockedError";
+    constructor(url: string, reason: string);
+}
+
+/**
+ * Decorator layer: consumes a base `HttpClient` and re-provides one that blocks
+ * SSRF targets on the initial request AND on every redirect hop.
+ *
+ * Compose it BELOW the tracing layer and above the base fetch client:
+ *
+ *   ssrfGuardHttpClientLayer(policy).pipe(Layer.provide(FetchHttpClient.layer))
+ */
+export declare const ssrfGuardHttpClientLayer: (policy?: SsrfPolicy) => Layer.Layer<HttpClient.HttpClient, never, HttpClient.HttpClient>;
+
+export declare interface SsrfPolicy {
+    /**
+     * Hosts that bypass the guard. An entry may be an exact hostname
+     * (`billing.internal`), a suffix wildcard (`*.svc.cluster.local`), or a
+     * host:port (`127.0.0.1:8787`) when only one port should be reachable.
+     *
+     * This is the one escape hatch, and it is deliberately per-HOST rather than a
+     * boolean: "we call one internal service" and "we do not check URLs" are very
+     * different postures, and a boolean cannot tell them apart six months later.
+     */
+    readonly allowHosts?: ReadonlyArray<string>;
+    /** Max redirect hops to follow. Each one is revalidated. Default 5. */
+    readonly maxRedirects?: number;
+}
+
+/**
+ * Decide whether a URL may be fetched. Returns `null` when allowed, else the
+ * reason. Fails CLOSED: a URL that will not parse is blocked.
+ *
+ * DNS is deliberately NOT resolved — this is a synchronous check on the literal
+ * target, so a hostname that RESOLVES to a private address (DNS rebinding) is not
+ * caught here. Blocking the direct-IP vector is the high-severity, cheap half;
+ * rebinding needs network-layer egress control and is called out in the docs
+ * rather than silently implied.
+ */
+export declare const ssrfReason: (rawUrl: string, policy?: SsrfPolicy) => string | null;
+
 /**
  * Start the rpc-based runtime server on Node. Composes:
  *   - NodeHttpServer + NodeContext at the platform layer
@@ -5388,10 +5652,15 @@ export declare const snapshotMetricsSync: () => ReadonlyArray<MetricSample>;
  *   - RpcServer.layerHttpRouter (websocket protocol) consuming
  *     RpcSerialization.layerJson and the user's handlers layer
  *
- * Hands the result to NodeRuntime.runMain via Layer.launch so the Node event
- * loop stays alive for the lifetime of the layer's scope.
- */
-export declare const startRpcServer: <Rpcs extends Rpc.Any>(options: RpcServerOptions<Rpcs>) => ReturnType<typeof createServer>;
+ * Forks `Layer.launch` so the Node event loop stays alive for the lifetime of the
+ * layer's scope, and returns that scope's `shutdown` alongside the node server —
+ * so a programmatic close releases the layer, not just the socket. SIGINT/SIGTERM
+ * are wired once per process (not once per call) and drain every live launch.
+ */
+export declare const startRpcServer: <Rpcs extends Rpc.Any>(options: RpcServerOptions<Rpcs>) => {
+    server: ReturnType<typeof createServer>;
+    shutdown: () => Promise<void>;
+};
 
 export declare const startScheduler: (schedules: ReadonlyArray<BrandedScheduleDefinition>, deps: SchedulerDeps) => Promise<SchedulerHandle>;
 
@@ -6555,6 +6824,6 @@ export declare interface WorkflowWaitOptions {
  */
 export declare const wrapCaptureStore: (tx: DataStore, collect: (c: ForwardChange) => void) => DataStore;
 
-export declare const wrapStoreWithMixinBehaviour: (underlying: DataStore, ctx: StoreMiddlewareContext) => FluentStore;
+export declare const wrapStoreWithMixinBehaviour: (rawUnderlying: DataStore, ctx: StoreMiddlewareContext) => FluentStore;
 
 export { }