@dudousxd/nestjs-durable-dashboard 0.51.0 → 0.52.0

package/dist/server/index.cjs

@@ -24,14 +24,21 @@ var index_exports = {};
 __export(index_exports, {
   DASHBOARD_API_PATH: () => DASHBOARD_API_PATH,
   DASHBOARD_BASE_PATH: () => DASHBOARD_BASE_PATH,
+  DASHBOARD_GATE: () => DASHBOARD_GATE,
+  DURABLE_DASHBOARD_TOKEN_ENV: () => DURABLE_DASHBOARD_TOKEN_ENV,
   DashboardService: () => DashboardService,
   DurableApiController: () => DurableApiController,
   DurableApiModule: () => DurableApiModule,
   DurableApiSessionGuard: () => DurableApiSessionGuard,
   DurableAuthController: () => DurableAuthController,
+  DurableDashboardGateGuard: () => DurableDashboardGateGuard,
   DurableDashboardModule: () => DurableDashboardModule,
   DurableUiController: () => DurableUiController,
-  DurableUiSessionGuard: () => DurableUiSessionGuard
+  DurableUiSessionGuard: () => DurableUiSessionGuard,
+  dashboardGateProvider: () => dashboardGateProvider,
+  readDashboardToken: () => readDashboardToken,
+  reportDashboardGate: () => reportDashboardGate,
+  resolveDashboardGate: () => resolveDashboardGate
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -245,11 +252,30 @@ var DashboardService = class {
   }
   /**
   * Deliver a `ctx.webhook()` callback: turn an inbound POST (token + body) into the signal the
-  * waiting run is parked on. Returns the run result, or `null` if no run waits on that token (a
-  * stale/duplicate callback) — a safe no-op the controller maps to 404. Control-plane-only.
+  * run is (or will be) parked on. A callback that arrives BEFORE the run reaches `wait()` (the url
+  * was handed out and the run is still busy or sleeping) is buffered, and `wait()` consumes it, so
+  * the result is the run's current status. Returns `null` — mapped to 404 by the controller — for a
+  * token that is not a webhook token, whose run doesn't exist or is terminal, or whose wait already
+  * resolved (a duplicate): nothing is buffered for those, so a public endpoint can't leave junk
+  * rows behind or signal non-webhook tokens. Control-plane-only.
   */
   async deliverWebhook(token, body) {
-    return this.controlPlane().engine.signal(token, body);
+    const { store, engine } = this.controlPlane();
+    const parsed = (0, import_nestjs_durable_core.parseWebhookToken)(token);
+    if (!parsed) return null;
+    const run = await store.getRun(parsed.runId);
+    if (!run || import_nestjs_durable_core.TERMINAL_RUN_STATUSES.includes(run.status)) return null;
+    const resolved = await store.getCheckpoint(parsed.runId, parsed.seq);
+    if (resolved?.status === "completed") return null;
+    const delivered = await engine.signal(token, body);
+    if (delivered) return delivered;
+    const now = await store.getCheckpoint(parsed.runId, parsed.seq);
+    if (now?.status === "completed" && await store.takeBufferedSignal(token)) return null;
+    const fresh = await store.getRun(parsed.runId);
+    return {
+      runId: run.id,
+      status: fresh?.status ?? run.status
+    };
   }
   /** Side-effect-free read of a value a run published via `ctx.setEvent` (a live query). Control-plane-only. */
   async getEvent(runId, key) {
@@ -1311,7 +1337,7 @@ var DurableApiController = class {
   */
   async webhook(token, body) {
     const result = await this.dashboard.deliverWebhook(token, body);
-    if (!result) throw new import_common5.NotFoundException(`no run is waiting on webhook ${token}`);
+    if (!result) throw new import_common5.NotFoundException(`no live run is waiting for webhook ${token}`);
     return result;
   }
   /** Live query: the latest value a run published for `key` via `ctx.setEvent` (no side effect). */
@@ -2484,13 +2510,8 @@ DurableAuthController = _ts_decorate9([
   ])
 ], DurableAuthController);
 
-// src/server/durable-dashboard.module.ts
-var import_reflect_metadata = require("reflect-metadata");
-var import_nestjs_filter3 = require("@dudousxd/nestjs-filter");
-var import_common11 = require("@nestjs/common");
-var import_core = require("@nestjs/core");
-
-// src/server/durable-session.guard.ts
+// src/server/durable-dashboard-gate.guard.ts
+var import_node_crypto2 = require("crypto");
 var import_common10 = require("@nestjs/common");
 function _ts_decorate10(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -2518,6 +2539,191 @@ function _ts_param6(paramIndex, decorator) {
   };
 }
 __name(_ts_param6, "_ts_param");
+var DURABLE_DASHBOARD_TOKEN_ENV = "DURABLE_DASHBOARD_TOKEN";
+var DASHBOARD_GATE = Symbol("DASHBOARD_GATE");
+var LOG_CONTEXT = "DurableDashboard";
+var HOW_TO_CONFIGURE = [
+  "Configure one of: `guards: [YourAuthGuard]`, `dashboardAuth: { secret, session | login }`",
+  "(or `useDashboardAuth` in forRootAsync), a bearer token via the `token` option or the",
+  `${DURABLE_DASHBOARD_TOKEN_ENV} env var, or \`allowUnauthenticated: true\` when the console is`,
+  "already protected outside this module (a global guard, a reverse proxy, a private network)."
+].join(" ");
+function isProduction() {
+  return (process.env.NODE_ENV ?? "").trim().toLowerCase() === "production";
+}
+__name(isProduction, "isProduction");
+function resolveDashboardGate(options, auth) {
+  if (options.hasGuards || auth !== null) return {
+    mode: "delegated"
+  };
+  const token = options.token ?? process.env[DURABLE_DASHBOARD_TOKEN_ENV];
+  if (typeof token === "string" && token !== "") return {
+    mode: "token",
+    token
+  };
+  if (options.allowUnauthenticated === true) return {
+    mode: "open"
+  };
+  return {
+    mode: isProduction() ? "deny" : "unconfigured"
+  };
+}
+__name(resolveDashboardGate, "resolveDashboardGate");
+function reportDashboardGate(gate, options, logger = new import_common10.Logger(LOG_CONTEXT)) {
+  switch (gate.mode) {
+    case "open":
+      logger.warn("allowUnauthenticated: true. The durable console (including retry/cancel and other mutating endpoints) is served with NO authentication from this module. Only do this when a global guard or reverse proxy already protects it.");
+      return;
+    case "token":
+      if (options.allowUnauthenticated === true) {
+        logger.warn("allowUnauthenticated: true is ignored because a dashboard token is configured; requests must carry the token.");
+      }
+      return;
+    case "unconfigured":
+      logger.warn([
+        "The durable console is UNAUTHENTICATED: no guards, dashboardAuth, token or",
+        "allowUnauthenticated were configured. It is served open because NODE_ENV is not",
+        '"production", but it WILL deny every request when NODE_ENV=production.',
+        HOW_TO_CONFIGURE
+      ].join(" "));
+      return;
+    case "deny":
+      logger.error([
+        "The durable console has no authentication configured and NODE_ENV=production, so it",
+        "is failing closed: every console request (UI and API) is denied.",
+        HOW_TO_CONFIGURE
+      ].join(" "));
+      return;
+    case "delegated":
+      return;
+  }
+}
+__name(reportDashboardGate, "reportDashboardGate");
+function dashboardGateProvider(options) {
+  return {
+    provide: DASHBOARD_GATE,
+    inject: [
+      DASHBOARD_AUTH
+    ],
+    useFactory: /* @__PURE__ */ __name((auth) => {
+      const gate = resolveDashboardGate(options, auth);
+      reportDashboardGate(gate, options);
+      return gate;
+    }, "useFactory")
+  };
+}
+__name(dashboardGateProvider, "dashboardGateProvider");
+function isRecord3(value) {
+  return typeof value === "object" && value !== null;
+}
+__name(isRecord3, "isRecord");
+function headerValue(request, name) {
+  const headers = request.headers;
+  if (!isRecord3(headers)) return void 0;
+  const value = headers[name];
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return void 0;
+}
+__name(headerValue, "headerValue");
+function readDashboardToken(request) {
+  if (!isRecord3(request)) return void 0;
+  const authorization = headerValue(request, "authorization");
+  if (authorization) {
+    const match = /^Bearer\s+(.+)$/i.exec(authorization);
+    if (match?.[1]) return match[1].trim();
+  }
+  const header = headerValue(request, "x-durable-token");
+  if (header) return header.trim();
+  const method = typeof request.method === "string" ? request.method.toUpperCase() : "";
+  if (method === "GET" || method === "HEAD") {
+    const query = request.query;
+    if (isRecord3(query)) {
+      const value = query.token;
+      if (typeof value === "string" && value !== "") return value;
+    }
+  }
+  return void 0;
+}
+__name(readDashboardToken, "readDashboardToken");
+function secretsMatch(provided, expected) {
+  const a = Buffer.from(provided);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) return false;
+  return (0, import_node_crypto2.timingSafeEqual)(a, b);
+}
+__name(secretsMatch, "secretsMatch");
+var DurableDashboardGateGuard = class {
+  static {
+    __name(this, "DurableDashboardGateGuard");
+  }
+  gate;
+  constructor(gate) {
+    this.gate = gate;
+  }
+  canActivate(context) {
+    switch (this.gate.mode) {
+      case "delegated":
+      case "open":
+      case "unconfigured":
+        return true;
+      case "deny":
+        throw new import_common10.ForbiddenException([
+          "Durable dashboard authentication is not configured, and NODE_ENV=production denies",
+          "an unauthenticated console.",
+          HOW_TO_CONFIGURE
+        ].join(" "));
+      case "token": {
+        const provided = readDashboardToken(context.switchToHttp().getRequest());
+        if (provided !== void 0 && secretsMatch(provided, this.gate.token ?? "")) return true;
+        throw new import_common10.UnauthorizedException("A valid durable dashboard token is required (Authorization: Bearer <token>, x-durable-token, or ?token= on GET).");
+      }
+    }
+  }
+};
+DurableDashboardGateGuard = _ts_decorate10([
+  (0, import_common10.Injectable)(),
+  _ts_param6(0, (0, import_common10.Inject)(DASHBOARD_GATE)),
+  _ts_metadata8("design:type", Function),
+  _ts_metadata8("design:paramtypes", [
+    typeof DashboardGate === "undefined" ? Object : DashboardGate
+  ])
+], DurableDashboardGateGuard);
+
+// src/server/durable-dashboard.module.ts
+var import_reflect_metadata = require("reflect-metadata");
+var import_nestjs_filter3 = require("@dudousxd/nestjs-filter");
+var import_common12 = require("@nestjs/common");
+var import_core = require("@nestjs/core");
+
+// src/server/durable-session.guard.ts
+var import_common11 = require("@nestjs/common");
+function _ts_decorate11(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate11, "_ts_decorate");
+function _ts_metadata9(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata9, "_ts_metadata");
+function _ts_param7(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param7, "_ts_param");
 var DurableUiSessionGuard = class {
   static {
     __name(this, "DurableUiSessionGuard");
@@ -2558,12 +2764,12 @@ var DurableUiSessionGuard = class {
     throw new DashboardLoginRedirectException(`${this.basePath}/login?returnTo=${returnTo}`);
   }
 };
-DurableUiSessionGuard = _ts_decorate10([
-  (0, import_common10.Injectable)(),
-  _ts_param6(0, (0, import_common10.Inject)(DASHBOARD_AUTH)),
-  _ts_param6(1, (0, import_common10.Inject)(DASHBOARD_BASE_PATH)),
-  _ts_metadata8("design:type", Function),
-  _ts_metadata8("design:paramtypes", [
+DurableUiSessionGuard = _ts_decorate11([
+  (0, import_common11.Injectable)(),
+  _ts_param7(0, (0, import_common11.Inject)(DASHBOARD_AUTH)),
+  _ts_param7(1, (0, import_common11.Inject)(DASHBOARD_BASE_PATH)),
+  _ts_metadata9("design:type", Function),
+  _ts_metadata9("design:paramtypes", [
     Object,
     String
   ])
@@ -2595,24 +2801,24 @@ var DurableApiSessionGuard = class {
   * 401; `DurableUiSessionGuard`'s redirect/session-required exceptions above don't reach it.
   */
   unauthorized(auth) {
-    return new import_common10.UnauthorizedException({
+    return new import_common11.UnauthorizedException({
       auth: {
         modes: auth.modes
       }
     });
   }
 };
-DurableApiSessionGuard = _ts_decorate10([
-  (0, import_common10.Injectable)(),
-  _ts_param6(0, (0, import_common10.Inject)(DASHBOARD_AUTH)),
-  _ts_metadata8("design:type", Function),
-  _ts_metadata8("design:paramtypes", [
+DurableApiSessionGuard = _ts_decorate11([
+  (0, import_common11.Injectable)(),
+  _ts_param7(0, (0, import_common11.Inject)(DASHBOARD_AUTH)),
+  _ts_metadata9("design:type", Function),
+  _ts_metadata9("design:paramtypes", [
     Object
   ])
 ], DurableApiSessionGuard);
 
 // src/server/durable-dashboard.module.ts
-function _ts_decorate11(decorators, target, key, desc) {
+function _ts_decorate12(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
     r = Reflect.decorate(decorators, target, key, desc);
@@ -2625,7 +2831,7 @@ function _ts_decorate11(decorators, target, key, desc) {
   }
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate11, "_ts_decorate");
+__name(_ts_decorate12, "_ts_decorate");
 var GUARDS_METADATA = "__guards__";
 function normalize(path) {
   return `/${path.replace(/^\/+|\/+$/g, "")}`;
@@ -2633,9 +2839,7 @@ function normalize(path) {
 __name(normalize, "normalize");
 function stampGuards(hostGuards, builtIn, controller) {
   const merged = [
-    ...builtIn ? [
-      builtIn
-    ] : [],
+    ...builtIn.filter((guard) => guard !== void 0),
     ...hostGuards ?? []
   ];
   Reflect.defineMetadata(GUARDS_METADATA, merged, controller);
@@ -2646,7 +2850,10 @@ var DurableApiModule = class _DurableApiModule {
     __name(this, "DurableApiModule");
   }
   static register(options) {
-    stampGuards(options.guards, options.authMayBeConfigured ? DurableApiSessionGuard : void 0, DurableApiController);
+    stampGuards(options.guards, [
+      options.authMayBeConfigured ? DurableApiSessionGuard : void 0,
+      options.stampGate ? DurableDashboardGateGuard : void 0
+    ], DurableApiController);
     return {
       module: _DurableApiModule,
       imports: [
@@ -2690,16 +2897,21 @@ var DurableApiModule = class _DurableApiModule {
         RunFilter,
         options.authProvider,
         DurableApiSessionGuard,
+        // Resolved ONCE here (this module is imported by the UI module, which reuses it via the
+        // export below), so the boot report is logged once per mount.
+        dashboardGateProvider(options.gate),
+        DurableDashboardGateGuard,
         ...options.guards ?? []
       ],
       exports: [
-        DashboardService
+        DashboardService,
+        DASHBOARD_GATE
       ]
     };
   }
 };
-DurableApiModule = _ts_decorate11([
-  (0, import_common11.Module)({})
+DurableApiModule = _ts_decorate12([
+  (0, import_common12.Module)({})
 ], DurableApiModule);
 var DurableDashboardModule = class _DurableDashboardModule {
   static {
@@ -2710,7 +2922,8 @@ var DurableDashboardModule = class _DurableDashboardModule {
       provide: DASHBOARD_AUTH,
       useValue: resolveDashboardAuth(options.dashboardAuth)
     };
-    return _DurableDashboardModule.build(options, authProvider, options.dashboardAuth !== void 0);
+    const authConfigured = options.dashboardAuth !== void 0;
+    return _DurableDashboardModule.build(options, authProvider, authConfigured, authConfigured);
   }
   static forRootAsync(options) {
     const authProvider = {
@@ -2718,13 +2931,27 @@ var DurableDashboardModule = class _DurableDashboardModule {
       inject: options.inject ?? [],
       useFactory: /* @__PURE__ */ __name(async (...deps) => resolveDashboardAuth(await options.useDashboardAuth(...deps)), "useFactory")
     };
-    return _DurableDashboardModule.build(options, authProvider, true);
+    return _DurableDashboardModule.build(options, authProvider, true, false);
   }
   /** Shared wiring: static routing + the API module, with `dashboardAuth` supplied by `authProvider`. */
-  static build(options, authProvider, authMayBeConfigured) {
+  static build(options, authProvider, authMayBeConfigured, authStaticallyConfigured) {
     const basePath = normalize(options.basePath ?? "/durable");
     const apiBasePath = normalize(options.apiBasePath ?? `${basePath}/api`);
-    stampGuards(options.guards, authMayBeConfigured ? DurableUiSessionGuard : void 0, DurableUiController);
+    const hasGuards = (options.guards?.length ?? 0) > 0;
+    const gate = {
+      hasGuards,
+      ...options.allowUnauthenticated !== void 0 ? {
+        allowUnauthenticated: options.allowUnauthenticated
+      } : {},
+      ...options.token !== void 0 ? {
+        token: options.token
+      } : {}
+    };
+    const stampGate = !hasGuards && !authStaticallyConfigured;
+    stampGuards(options.guards, [
+      authMayBeConfigured ? DurableUiSessionGuard : void 0,
+      stampGate ? DurableDashboardGateGuard : void 0
+    ], DurableUiController);
     return {
       module: _DurableDashboardModule,
       imports: [
@@ -2740,7 +2967,9 @@ var DurableDashboardModule = class _DurableDashboardModule {
             guards: options.guards
           } : {},
           authProvider,
-          authMayBeConfigured
+          authMayBeConfigured,
+          gate,
+          stampGate
         }),
         import_core.RouterModule.register([
           {
@@ -2773,6 +3002,8 @@ var DurableDashboardModule = class _DurableDashboardModule {
         },
         authProvider,
         DurableUiSessionGuard,
+        // `DASHBOARD_GATE` itself comes from the imported DurableApiModule (resolved once there).
+        DurableDashboardGateGuard,
         // DurableUiController (and DurableAuthController, when present) are hosted HERE, so their
         // guards DI-instantiate from this module.
         ...options.guards ?? []
@@ -2784,20 +3015,27 @@ var DurableDashboardModule = class _DurableDashboardModule {
     };
   }
 };
-DurableDashboardModule = _ts_decorate11([
-  (0, import_common11.Module)({})
+DurableDashboardModule = _ts_decorate12([
+  (0, import_common12.Module)({})
 ], DurableDashboardModule);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DASHBOARD_API_PATH,
   DASHBOARD_BASE_PATH,
+  DASHBOARD_GATE,
+  DURABLE_DASHBOARD_TOKEN_ENV,
   DashboardService,
   DurableApiController,
   DurableApiModule,
   DurableApiSessionGuard,
   DurableAuthController,
+  DurableDashboardGateGuard,
   DurableDashboardModule,
   DurableUiController,
-  DurableUiSessionGuard
+  DurableUiSessionGuard,
+  dashboardGateProvider,
+  readDashboardToken,
+  reportDashboardGate,
+  resolveDashboardGate
 });
 //# sourceMappingURL=index.cjs.map