@dudousxd/nestjs-durable 0.51.0 → 0.52.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
-export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
+export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, hmacTenantVerifier, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -790,6 +790,26 @@ interface DurableModuleOptions {
     /** Timeout for a thin worker's `RunGateway` round-trip over `transport` before it rejects. Defaults
      *  to 10_000ms inside `ProxyRunGateway`. Ignored for an operator (bound to `StoreRunGateway`). */
     runGatewayTimeoutMs?: number;
+    /**
+     * **Operator.** Verifies the signed tenant token a store-less tenant worker presents in the wire
+     * `tenant` field of every run request and start-run message, and DERIVES the tenant from it,
+     * discarding the wire claim. An invalid, tampered or absent token is rejected: a run request gets
+     * an `unauthorized` error reply, a start-run creates nothing. Use `hmacTenantVerifier(secret)`
+     * (tokens minted by `signTenantToken`, wire-compatible with Agora) or supply your own.
+     *
+     * Optional. Absent: the wire `tenant` is trusted verbatim (prefix/network isolation only), exactly
+     * as before. An explicit `topology: { role: 'control-plane' }` without a verifier logs a warning
+     * at boot; a plain operator (`store` + `transport`, no `topology`) boots silently.
+     */
+    verifyTenant?: TenantVerifier;
+    /**
+     * **Tenant worker.** The signed token (see `signTenantToken`) this worker presents, verbatim, in
+     * the `tenant` field of every run request (`ProxyRunGateway`) and start-run (`engine.start`), so
+     * an operator with {@link verifyTenant} can authenticate it. A string, or a function called before
+     * every request (rotation, short-lived tokens). Optional: absent, the raw {@link partition} is
+     * sent, as before. Live-tail stays keyed by the partition, never the token.
+     */
+    tenantToken?: TenantTokenSource;
     /**
      * An explicit preset that NAMES the deployment role instead of leaving it to `store`/`connection`
      * inference, and VALIDATES the axes that are otherwise only prose (see the interface doc's role
@@ -1078,6 +1098,77 @@ declare class InAppWorkerBootstrap implements OnModuleInit, OnApplicationBootstr
  */
 declare function inAppWorkerProviders(): Provider[];
 
+/**
+ * The error `code` a responder replies with for a verb it does not know, so a newer tenant can tell
+ * "this control plane is older than me" from a real failure and fall back at once. Earlier
+ * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
+ */
+declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
+/** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
+ *  correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
+ *  transports carry the run-request/reply protocol); the caller capability-checks before wiring
+ *  this up (see `durable.module.ts`). */
+interface RunRequestTransport {
+    onRunRequest(handler: (msg: RunRequest) => Promise<void>): void;
+    publishRunReply(reply: RunReply): Promise<void>;
+}
+/** Options for {@link RunRequestResponder}. */
+interface RunRequestResponderOptions {
+    /**
+     * Verifies the signed token a tenant presents in the wire `tenant` field and DERIVES the real
+     * tenant from it (see `hmacTenantVerifier`). Present: an invalid, tampered or absent token is
+     * rejected with an `unauthorized` error reply and the wire claim is discarded in favour of the
+     * verified tenant. Absent: the wire `tenant` is trusted verbatim (prefix/network isolation only).
+     */
+    verifyTenant?: TenantVerifier | undefined;
+    /**
+     * Warn at construction when no {@link verifyTenant} is set. Default `true`. `DurableModule` passes
+     * `true` only for an explicit `topology: { role: 'control-plane' }`, so a plain operator app that
+     * never serves tenants boots silently.
+     */
+    warnWithoutVerifier?: boolean | undefined;
+}
+/**
+ * Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
+ * `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
+ * verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
+ * `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
+ * verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
+ * overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
+ * sent. This is the security boundary of the tenant run gateway — do not weaken it.
+ *
+ * With {@link RunRequestResponderOptions.verifyTenant}, every request is authenticated FIRST: the
+ * wire `tenant` is treated as a signed token, the real tenant is derived from it, and an invalid
+ * token short-circuits into an `unauthorized` error reply before any run is touched. A verifier
+ * that throws becomes an error reply too.
+ */
+declare class RunRequestResponder {
+    private readonly transport;
+    private readonly gateway;
+    private readonly verifyTenant;
+    constructor(transport: RunRequestTransport, gateway: RunGateway, options?: RunRequestResponderOptions);
+    /** Register the consumer on the transport. Each request is answered independently; a handler
+     *  failure never throws back into the transport (errors are captured into an error reply). */
+    start(): void;
+    private handle;
+    private callVerb;
+}
+
+/**
+ * An error reply from the control plane. `code` carries the reply's machine-readable reason when it
+ * sent one — `unauthorized` (the tenant token was rejected), `cross-tenant` (the run belongs to
+ * another tenant), ... — so a caller can tell an authentication failure from a real one, as with
+ * Agora's proxy.
+ */
+/**
+ * The codes the run-request responder replies with. `string & {}` keeps a code from a newer control
+ * plane assignable without losing autocomplete on the known ones.
+ */
+type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
+declare class RunGatewayError extends Error {
+    readonly code: RunGatewayErrorCode | undefined;
+    constructor(message: string, code?: RunGatewayErrorCode);
+}
 /**
  * Tenant-side `RunGateway` — round-trips every verb as a `RunRequest`/`RunReply` pair over the
  * transport, correlated by a minted `requestId`, and bridges `subscribe` onto the transport's
@@ -1091,15 +1182,32 @@ declare class ProxyRunGateway implements RunGateway {
     private readonly tenant;
     private readonly timeoutMs;
     private readonly capabilityTtlMs;
+    /**
+     * The tenant's signed token (see `signTenantToken`), presented VERBATIM in the `tenant` field of
+     * every {@link RunRequest} so an operator with `verifyTenant` can authenticate it and derive the
+     * tenant from it. A function is called before every request (rotation / short-lived tokens).
+     * Omit to send the raw `tenant` (prefix/network isolation only). The live-tail channel always
+     * stays keyed by `tenant`, never the token: the operator republishes by the run's namespace.
+     */
+    private readonly tenantToken?;
     private readonly pending;
     /** Verb → when to ask the control plane for it again, after it answered that it does not know it.
      *  During a rolling upgrade the control plane is several pods of mixed versions behind one queue,
      *  and a reply does not say which pod sent it, so the whole control plane is assumed old until the
      *  entry expires. */
     private readonly unsupportedUntil;
-    constructor(transport: Transport, tenant: string, timeoutMs?: number, capabilityTtlMs?: number);
+    constructor(transport: Transport, tenant: string, timeoutMs?: number, capabilityTtlMs?: number, 
+    /**
+     * The tenant's signed token (see `signTenantToken`), presented VERBATIM in the `tenant` field of
+     * every {@link RunRequest} so an operator with `verifyTenant` can authenticate it and derive the
+     * tenant from it. A function is called before every request (rotation / short-lived tokens).
+     * Omit to send the raw `tenant` (prefix/network isolation only). The live-tail channel always
+     * stays keyed by `tenant`, never the token: the operator republishes by the run's namespace.
+     */
+    tenantToken?: TenantTokenSource | undefined);
     private handleReply;
     private request;
+    private send;
     topology(): DurableTopology;
     /**
      * A control plane that predates {@link RunDetailOptions} ignores them and sends the full detail;
@@ -1151,40 +1259,6 @@ declare function isOperatorRole(options: DurableModuleOptions): boolean;
  */
 declare function isDrivingOperator(options: DurableModuleOptions): boolean;
 
-/**
- * The error `code` a responder replies with for a verb it does not know, so a newer tenant can tell
- * "this control plane is older than me" from a real failure and fall back at once. Earlier
- * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
- */
-declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
-/** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
- *  correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
- *  transports carry the run-request/reply protocol); the caller capability-checks before wiring
- *  this up (see `durable.module.ts`). */
-interface RunRequestTransport {
-    onRunRequest(handler: (msg: RunRequest) => Promise<void>): void;
-    publishRunReply(reply: RunReply): Promise<void>;
-}
-/**
- * Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
- * `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
- * verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
- * `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
- * verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
- * overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
- * sent. This is the security boundary of the tenant run gateway — do not weaken it.
- */
-declare class RunRequestResponder {
-    private readonly transport;
-    private readonly gateway;
-    constructor(transport: RunRequestTransport, gateway: RunGateway);
-    /** Register the consumer on the transport. Each request is answered independently; a handler
-     *  failure never throws back into the transport (errors are captured into an error reply). */
-    start(): void;
-    private handle;
-    private callVerb;
-}
-
 declare const STEP_INTERCEPTOR_METADATA: unique symbol;
 /**
  * The shape a `@StepInterceptor()` provider must implement: `intercept(invocation, next)` wraps the
@@ -1375,4 +1449,4 @@ declare class WorkflowService {
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
-export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
+export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, hmacTenantVerifier, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -790,6 +790,26 @@ interface DurableModuleOptions {
     /** Timeout for a thin worker's `RunGateway` round-trip over `transport` before it rejects. Defaults
      *  to 10_000ms inside `ProxyRunGateway`. Ignored for an operator (bound to `StoreRunGateway`). */
     runGatewayTimeoutMs?: number;
+    /**
+     * **Operator.** Verifies the signed tenant token a store-less tenant worker presents in the wire
+     * `tenant` field of every run request and start-run message, and DERIVES the tenant from it,
+     * discarding the wire claim. An invalid, tampered or absent token is rejected: a run request gets
+     * an `unauthorized` error reply, a start-run creates nothing. Use `hmacTenantVerifier(secret)`
+     * (tokens minted by `signTenantToken`, wire-compatible with Agora) or supply your own.
+     *
+     * Optional. Absent: the wire `tenant` is trusted verbatim (prefix/network isolation only), exactly
+     * as before. An explicit `topology: { role: 'control-plane' }` without a verifier logs a warning
+     * at boot; a plain operator (`store` + `transport`, no `topology`) boots silently.
+     */
+    verifyTenant?: TenantVerifier;
+    /**
+     * **Tenant worker.** The signed token (see `signTenantToken`) this worker presents, verbatim, in
+     * the `tenant` field of every run request (`ProxyRunGateway`) and start-run (`engine.start`), so
+     * an operator with {@link verifyTenant} can authenticate it. A string, or a function called before
+     * every request (rotation, short-lived tokens). Optional: absent, the raw {@link partition} is
+     * sent, as before. Live-tail stays keyed by the partition, never the token.
+     */
+    tenantToken?: TenantTokenSource;
     /**
      * An explicit preset that NAMES the deployment role instead of leaving it to `store`/`connection`
      * inference, and VALIDATES the axes that are otherwise only prose (see the interface doc's role
@@ -1078,6 +1098,77 @@ declare class InAppWorkerBootstrap implements OnModuleInit, OnApplicationBootstr
  */
 declare function inAppWorkerProviders(): Provider[];
 
+/**
+ * The error `code` a responder replies with for a verb it does not know, so a newer tenant can tell
+ * "this control plane is older than me" from a real failure and fall back at once. Earlier
+ * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
+ */
+declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
+/** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
+ *  correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
+ *  transports carry the run-request/reply protocol); the caller capability-checks before wiring
+ *  this up (see `durable.module.ts`). */
+interface RunRequestTransport {
+    onRunRequest(handler: (msg: RunRequest) => Promise<void>): void;
+    publishRunReply(reply: RunReply): Promise<void>;
+}
+/** Options for {@link RunRequestResponder}. */
+interface RunRequestResponderOptions {
+    /**
+     * Verifies the signed token a tenant presents in the wire `tenant` field and DERIVES the real
+     * tenant from it (see `hmacTenantVerifier`). Present: an invalid, tampered or absent token is
+     * rejected with an `unauthorized` error reply and the wire claim is discarded in favour of the
+     * verified tenant. Absent: the wire `tenant` is trusted verbatim (prefix/network isolation only).
+     */
+    verifyTenant?: TenantVerifier | undefined;
+    /**
+     * Warn at construction when no {@link verifyTenant} is set. Default `true`. `DurableModule` passes
+     * `true` only for an explicit `topology: { role: 'control-plane' }`, so a plain operator app that
+     * never serves tenants boots silently.
+     */
+    warnWithoutVerifier?: boolean | undefined;
+}
+/**
+ * Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
+ * `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
+ * verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
+ * `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
+ * verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
+ * overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
+ * sent. This is the security boundary of the tenant run gateway — do not weaken it.
+ *
+ * With {@link RunRequestResponderOptions.verifyTenant}, every request is authenticated FIRST: the
+ * wire `tenant` is treated as a signed token, the real tenant is derived from it, and an invalid
+ * token short-circuits into an `unauthorized` error reply before any run is touched. A verifier
+ * that throws becomes an error reply too.
+ */
+declare class RunRequestResponder {
+    private readonly transport;
+    private readonly gateway;
+    private readonly verifyTenant;
+    constructor(transport: RunRequestTransport, gateway: RunGateway, options?: RunRequestResponderOptions);
+    /** Register the consumer on the transport. Each request is answered independently; a handler
+     *  failure never throws back into the transport (errors are captured into an error reply). */
+    start(): void;
+    private handle;
+    private callVerb;
+}
+
+/**
+ * An error reply from the control plane. `code` carries the reply's machine-readable reason when it
+ * sent one — `unauthorized` (the tenant token was rejected), `cross-tenant` (the run belongs to
+ * another tenant), ... — so a caller can tell an authentication failure from a real one, as with
+ * Agora's proxy.
+ */
+/**
+ * The codes the run-request responder replies with. `string & {}` keeps a code from a newer control
+ * plane assignable without losing autocomplete on the known ones.
+ */
+type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
+declare class RunGatewayError extends Error {
+    readonly code: RunGatewayErrorCode | undefined;
+    constructor(message: string, code?: RunGatewayErrorCode);
+}
 /**
  * Tenant-side `RunGateway` — round-trips every verb as a `RunRequest`/`RunReply` pair over the
  * transport, correlated by a minted `requestId`, and bridges `subscribe` onto the transport's
@@ -1091,15 +1182,32 @@ declare class ProxyRunGateway implements RunGateway {
     private readonly tenant;
     private readonly timeoutMs;
     private readonly capabilityTtlMs;
+    /**
+     * The tenant's signed token (see `signTenantToken`), presented VERBATIM in the `tenant` field of
+     * every {@link RunRequest} so an operator with `verifyTenant` can authenticate it and derive the
+     * tenant from it. A function is called before every request (rotation / short-lived tokens).
+     * Omit to send the raw `tenant` (prefix/network isolation only). The live-tail channel always
+     * stays keyed by `tenant`, never the token: the operator republishes by the run's namespace.
+     */
+    private readonly tenantToken?;
     private readonly pending;
     /** Verb → when to ask the control plane for it again, after it answered that it does not know it.
      *  During a rolling upgrade the control plane is several pods of mixed versions behind one queue,
      *  and a reply does not say which pod sent it, so the whole control plane is assumed old until the
      *  entry expires. */
     private readonly unsupportedUntil;
-    constructor(transport: Transport, tenant: string, timeoutMs?: number, capabilityTtlMs?: number);
+    constructor(transport: Transport, tenant: string, timeoutMs?: number, capabilityTtlMs?: number, 
+    /**
+     * The tenant's signed token (see `signTenantToken`), presented VERBATIM in the `tenant` field of
+     * every {@link RunRequest} so an operator with `verifyTenant` can authenticate it and derive the
+     * tenant from it. A function is called before every request (rotation / short-lived tokens).
+     * Omit to send the raw `tenant` (prefix/network isolation only). The live-tail channel always
+     * stays keyed by `tenant`, never the token: the operator republishes by the run's namespace.
+     */
+    tenantToken?: TenantTokenSource | undefined);
     private handleReply;
     private request;
+    private send;
     topology(): DurableTopology;
     /**
      * A control plane that predates {@link RunDetailOptions} ignores them and sends the full detail;
@@ -1151,40 +1259,6 @@ declare function isOperatorRole(options: DurableModuleOptions): boolean;
  */
 declare function isDrivingOperator(options: DurableModuleOptions): boolean;
 
-/**
- * The error `code` a responder replies with for a verb it does not know, so a newer tenant can tell
- * "this control plane is older than me" from a real failure and fall back at once. Earlier
- * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
- */
-declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
-/** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
- *  correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
- *  transports carry the run-request/reply protocol); the caller capability-checks before wiring
- *  this up (see `durable.module.ts`). */
-interface RunRequestTransport {
-    onRunRequest(handler: (msg: RunRequest) => Promise<void>): void;
-    publishRunReply(reply: RunReply): Promise<void>;
-}
-/**
- * Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
- * `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
- * verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
- * `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
- * verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
- * overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
- * sent. This is the security boundary of the tenant run gateway — do not weaken it.
- */
-declare class RunRequestResponder {
-    private readonly transport;
-    private readonly gateway;
-    constructor(transport: RunRequestTransport, gateway: RunGateway);
-    /** Register the consumer on the transport. Each request is answered independently; a handler
-     *  failure never throws back into the transport (errors are captured into an error reply). */
-    start(): void;
-    private handle;
-    private callVerb;
-}
-
 declare const STEP_INTERCEPTOR_METADATA: unique symbol;
 /**
  * The shape a `@StepInterceptor()` provider must implement: `intercept(invocation, next)` wraps the
@@ -1375,4 +1449,4 @@ declare class WorkflowService {
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };

package/dist/index.js

@@ -264,7 +264,7 @@ function attributesOf(workflow, run) {
 __name(attributesOf, "attributesOf");
 
 // src/durable-start-client.ts
-import { workflowName } from "@dudousxd/nestjs-durable-core";
+import { resolveTenantToken, workflowName } from "@dudousxd/nestjs-durable-core";
 import { Injectable } from "@nestjs/common";
 
 // src/worker-sdk.ts
@@ -322,7 +322,9 @@ var DurableStartClient = class {
   async start(workflow, input, runId = globalThis.crypto.randomUUID(), opts) {
     const name = workflowName(workflow);
     await startRun(this.options.connection, {
-      tenant: this.tenant,
+      // The signed token (when configured) rides in the `tenant` field, as on every run request; an
+      // operator with `verifyTenant` derives the run's namespace from it.
+      tenant: this.options.tenantToken !== void 0 ? await resolveTenantToken(this.options.tenantToken) : this.tenant,
       workflow: name,
       input,
       runId,
@@ -1159,10 +1161,11 @@ function inAppWorkerProviders() {
 __name(inAppWorkerProviders, "inAppWorkerProviders");
 
 // src/proxy-run-gateway.ts
-import { SUMMARY_CHILD_LIMIT, childIdsOf, pageFan, summarizeTimeline } from "@dudousxd/nestjs-durable-core";
+import { SUMMARY_CHILD_LIMIT, childIdsOf, pageFan, resolveTenantToken as resolveTenantToken2, summarizeTimeline } from "@dudousxd/nestjs-durable-core";
 import { Injectable as Injectable6 } from "@nestjs/common";
 
 // src/run-request-responder.ts
+import { resolveWireTenant } from "@dudousxd/nestjs-durable-core";
 var UNSUPPORTED_RUN_REQUEST = "unsupported-request";
 var KNOWN_KINDS = /* @__PURE__ */ new Set([
   "getRunDetail",
@@ -1184,9 +1187,14 @@ var RunRequestResponder = class {
   }
   transport;
   gateway;
-  constructor(transport, gateway) {
+  verifyTenant;
+  constructor(transport, gateway, options = {}) {
     this.transport = transport;
     this.gateway = gateway;
+    this.verifyTenant = options.verifyTenant;
+    if (!this.verifyTenant && options.warnWithoutVerifier !== false) {
+      console.warn("[nestjs-durable] run-request responder started WITHOUT a tenant verifier: the wire `tenant` claim is trusted verbatim (prefix/network isolation only). Any broker client can act as any tenant. Configure `verifyTenant` (e.g. hmacTenantVerifier(secret)) and signed tenant tokens unless your broker is fully isolated per tenant.");
+    }
   }
   /** Register the consumer on the transport. Each request is answered independently; a handler
   *  failure never throws back into the transport (errors are captured into an error reply). */
@@ -1209,7 +1217,24 @@ var RunRequestResponder = class {
       await this.transport.publishRunReply(reply);
     });
   }
-  async handle(msg) {
+  async handle(wire) {
+    const tenant = await resolveWireTenant(wire.tenant, this.verifyTenant);
+    if (tenant === null) {
+      return {
+        requestId: wire.requestId,
+        result: {
+          ok: false,
+          error: {
+            message: "invalid or unauthorized tenant token",
+            code: "unauthorized"
+          }
+        }
+      };
+    }
+    const msg = {
+      ...wire,
+      tenant
+    };
     const { body } = msg;
     if (!KNOWN_KINDS.has(body.kind)) {
       return {
@@ -1385,7 +1410,18 @@ function _ts_metadata6(metadataKey, metadataValue) {
   }
 }
 __name(_ts_metadata6, "_ts_metadata");
-var UnsupportedRunRequestError = class UnsupportedRunRequestError2 extends Error {
+var RunGatewayError = class extends Error {
+  static {
+    __name(this, "RunGatewayError");
+  }
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "RunGatewayError";
+    this.code = code;
+  }
+};
+var UnsupportedRunRequestError = class UnsupportedRunRequestError2 extends RunGatewayError {
   static {
     __name(this, "UnsupportedRunRequestError");
   }
@@ -1402,17 +1438,19 @@ var ProxyRunGateway = class {
   tenant;
   timeoutMs;
   capabilityTtlMs;
+  tenantToken;
   pending = /* @__PURE__ */ new Map();
   /** Verb → when to ask the control plane for it again, after it answered that it does not know it.
   *  During a rolling upgrade the control plane is several pods of mixed versions behind one queue,
   *  and a reply does not say which pod sent it, so the whole control plane is assumed old until the
   *  entry expires. */
   unsupportedUntil = /* @__PURE__ */ new Map();
-  constructor(transport, tenant, timeoutMs = 1e4, capabilityTtlMs = 6e4) {
+  constructor(transport, tenant, timeoutMs = 1e4, capabilityTtlMs = 6e4, tenantToken) {
     this.transport = transport;
     this.tenant = tenant;
     this.timeoutMs = timeoutMs;
     this.capabilityTtlMs = capabilityTtlMs;
+    this.tenantToken = tenantToken;
     this.transport.onRunReply?.((reply) => this.handleReply(reply));
   }
   handleReply(reply) {
@@ -1423,12 +1461,17 @@ var ProxyRunGateway = class {
     if (reply.result.ok) {
       pending.resolve(reply.result.data);
     } else if (reply.result.error.code === UNSUPPORTED_RUN_REQUEST) {
-      pending.reject(new UnsupportedRunRequestError(reply.result.error.message));
+      pending.reject(new UnsupportedRunRequestError(reply.result.error.message, UNSUPPORTED_RUN_REQUEST));
     } else {
-      pending.reject(new Error(reply.result.error.message));
+      pending.reject(new RunGatewayError(reply.result.error.message, reply.result.error.code));
     }
   }
   request(body) {
+    const source = this.tenantToken;
+    if (typeof source !== "function") return this.send(source ?? this.tenant, body);
+    return resolveTenantToken2(source).then((tenant) => this.send(tenant, body));
+  }
+  send(tenant, body) {
     return new Promise((resolve, reject) => {
       const requestId = globalThis.crypto.randomUUID();
       const timer = setTimeout(() => {
@@ -1442,9 +1485,9 @@ var ProxyRunGateway = class {
       });
       this.transport.dispatchRunRequest?.({
         requestId,
-        tenant: this.tenant,
+        tenant,
         body
-      }).catch((error) => {
+      })?.catch((error) => {
         const stillPending = this.pending.get(requestId);
         if (!stillPending) return;
         clearTimeout(stillPending.timer);
@@ -1602,7 +1645,8 @@ ProxyRunGateway = _ts_decorate6([
     typeof Transport === "undefined" ? Object : Transport,
     String,
     void 0,
-    void 0
+    void 0,
+    typeof TenantTokenSource === "undefined" ? Object : TenantTokenSource
   ])
 ], ProxyRunGateway);
 
@@ -2727,7 +2771,15 @@ var RunGatewayBootstrap = class RunGatewayBootstrap2 {
         onRunRequest: onRunRequest.bind(this.transport),
         publishRunReply: publishRunReply.bind(this.transport)
       };
-      new RunRequestResponder(runRequestTransport, this.gateway).start();
+      new RunRequestResponder(runRequestTransport, this.gateway, {
+        verifyTenant: this.options.verifyTenant,
+        // Mirrors Agora's rule (`warnWithoutVerifier: role === 'control-plane'`): only a deployment
+        // that EXPLICITLY names itself the control plane is told it runs without tenant auth. A plain
+        // operator (role inferred from `store`) is Agora's `standalone`: anyone with broker access
+        // can already enqueue steps and results there, so the warning would be noise on every boot
+        // of an app that never serves tenants.
+        warnWithoutVerifier: this.options.topology?.role === "control-plane"
+      }).start();
     }
     if (typeof publishTenantEvent === "function") {
       const republisher = new TenantEventRepublisher(store, publishTenantEvent.bind(this.transport));
@@ -2879,6 +2931,7 @@ var DurableModule = class _DurableModule {
               context,
               rehydrate: rehydrate || void 0,
               compensationRetries: options.compensationRetries,
+              verifyTenant: options.verifyTenant,
               // A non-driving (dashboard/API) operator must not run workflows: enqueue-only, leaving
               // each `pending` run in the store for a DRIVING instance's poll. A driving operator gets
               // the engine's default in-process dispatcher: for a body registered inline, it runs
@@ -2919,7 +2972,7 @@ var DurableModule = class _DurableModule {
               }
               return new StoreRunGateway(store, engine);
             }
-            return options.transport ? new ProxyRunGateway(options.transport, options.partition ?? "default", options.runGatewayTimeoutMs) : unavailableRunGateway();
+            return options.transport ? new ProxyRunGateway(options.transport, options.partition ?? "default", options.runGatewayTimeoutMs, void 0, options.tenantToken) : unavailableRunGateway();
           }, "useFactory"),
           inject: [
             DURABLE_OPTIONS_CANONICAL7,
@@ -2954,7 +3007,7 @@ DurableModule = _ts_decorate12([
 ], DurableModule);
 
 // src/index.ts
-import { prevCronFireMs, readSearchAttributes as readSearchAttributes2, RunGateway as RunGateway3, runSchedules as runSchedules2, scheduledRunId, scheduleRunIdAt, WorkflowEngine as WorkflowEngine7 } from "@dudousxd/nestjs-durable-core";
+import { hmacTenantVerifier, prevCronFireMs, readSearchAttributes as readSearchAttributes2, RunGateway as RunGateway3, runSchedules as runSchedules2, scheduledRunId, scheduleRunIdAt, signTenantToken, WorkflowEngine as WorkflowEngine7 } from "@dudousxd/nestjs-durable-core";
 export {
   CONTEXT_ACCESSOR,
   DEAD_LETTER_METADATA,
@@ -2984,6 +3037,7 @@ export {
   RUN_GATEWAY,
   RUN_REDIS_WORKER,
   RunGateway3 as RunGateway,
+  RunGatewayError,
   RunRequestResponder,
   STEP_INTERCEPTOR_METADATA,
   Step,
@@ -3004,6 +3058,7 @@ export {
   getEntityMeta,
   getOnEvents,
   getWorkflowMeta,
+  hmacTenantVerifier,
   inAppWorkerProviders,
   isDeadLetterHandler,
   isDrivingOperator,
@@ -3015,6 +3070,7 @@ export {
   runSchedules2 as runSchedules,
   scheduleRunIdAt,
   scheduledRunId,
+  signTenantToken,
   thinWorkerProviders,
   unavailableRunGateway
 };