@dudousxd/nestjs-durable-dashboard 0.55.1 → 0.57.0

package/dist/server/index.d.cts

@@ -1,3 +1,5 @@
+import { HttpException, ExecutionContext, Type, ExceptionFilter, ArgumentsHost, CanActivate, Logger, DynamicModule, StreamableFile } from '@nestjs/common';
+import { HttpAdapterHost, ModuleRef } from '@nestjs/core';
 import * as _dudousxd_nestjs_durable_core from '@dudousxd/nestjs-durable-core';
 import { RunGateway, StateStore, WorkflowEngine, ScheduleListQuery, ScheduleDescription, RunResult, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, DurableTopology, GroupHealth, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RepublishLifecycleResult, WorkflowLifecycleLinks, UpdateResult, EngineEvent, AttributeFilter } from '@dudousxd/nestjs-durable-core';
 export { RunDetail } from '@dudousxd/nestjs-durable-core';
@@ -5,7 +7,108 @@ import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
 import * as _dudousxd_nestjs_filter from '@dudousxd/nestjs-filter';
 import { FilterRunner } from '@dudousxd/nestjs-filter';
-import { DynamicModule, StreamableFile } from '@nestjs/common';
+
+type ConsoleAuthorizeResult = boolean | {
+    allowed: true;
+} | {
+    allowed: false;
+    reason?: 'unauthenticated' | 'forbidden';
+} | {
+    redirectTo: string;
+};
+/** Class form: an `@Injectable()` provider (constructor injection works). */
+interface ConsoleAuthorizer {
+    authorize(context: ExecutionContext): ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>;
+}
+type ConsoleAuthorizerClass = Type<ConsoleAuthorizer>;
+/** An `@nestjs/authorization` policy check: `policy[ability](user)`. */
+interface ConsolePolicyCheck {
+    policy: Type<unknown>;
+    ability: string;
+}
+type ConsoleAuthorize = ((context: ExecutionContext) => ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>) | ConsoleAuthorizerClass | (() => Promise<{
+    default: ConsoleAuthorizerClass;
+}>) | ConsolePolicyCheck | string;
+type ConsoleDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: 'unauthenticated' | 'forbidden';
+    redirectTo?: string;
+};
+/** What a resolved `authorize` is: called once per request, never throws. */
+type ConsoleDecide = (context: ExecutionContext) => Promise<ConsoleDecision>;
+/**
+ * The provider `@dudousxd/nestjs-authz` registers to resolve gate names (`authorize: 'console.x'`).
+ * A registry symbol, so it is found without depending on that package.
+ */
+declare const CONSOLE_GATE: unique symbol;
+interface ConsoleGate {
+    allows(name: string, context: ExecutionContext): Promise<ConsoleAuthorizeResult>;
+}
+/** The one boot warning for a console with no `authorize`. Same wording in every Aviary console. */
+declare const CONSOLE_AUTHORIZE_MISSING_WARNING = "[@dudousxd/nestjs-durable-dashboard] console has no `authorize` configured: it is open outside production and denies every request in production. Set `authorize` in DurableDashboardModule.forRoot().";
+/** Turns any {@link ConsoleAuthorizeResult} into a {@link ConsoleDecision}. */
+declare function normalizeConsoleResult(result: unknown): ConsoleDecision;
+/**
+ * Resolves `authorize` into one function the guard calls per request. Resolution errors that are
+ * configuration mistakes (a gate name without nestjs-authz, a policy without @nestjs/authorization)
+ * throw here, so call it at boot. The returned function never throws: an error is a `forbidden`.
+ *
+ * `authorize` omitted: open outside production, `forbidden` for every request in production (read
+ * when this runs), and one warning logged (unless `warnIfMissing: false`).
+ */
+declare function resolveConsoleAuthorize(authorize: ConsoleAuthorize | undefined, moduleRef: ModuleRef, options?: {
+    logger?: Logger;
+    warnIfMissing?: boolean;
+}): Promise<ConsoleDecide>;
+/**
+ * Allows a request carrying `Authorization: Bearer <token>` (compared timing-safe); anything else
+ * is `unauthenticated`. Header only: no query string, no custom header. Throws when `token` is
+ * empty, so a missing env var fails at config time instead of opening the console.
+ */
+declare function authorizeByToken(options: {
+    token: string | undefined;
+}): ConsoleAuthorize;
+/** DI token of the resolved {@link ConsoleDecide} the guard runs. */
+declare const CONSOLE_AUTHORIZE_DECIDE: unique symbol;
+/** Marks a controller as serving pages: a denied `GET` that accepts HTML gets a page, not JSON. */
+declare const CONSOLE_PAGE_METADATA = "@dudousxd/nestjs-durable-dashboard:console-page";
+declare const ConsolePage: () => ClassDecorator;
+/**
+ * The denial the guard throws. An `HttpException` with the JSON body, so it still answers correctly
+ * where {@link ConsoleAuthorizeFilter} is not applied; the filter adds the page answers.
+ */
+declare class ConsoleAccessDenied extends HttpException {
+    readonly decision: Extract<ConsoleDecision, {
+        allowed: false;
+    }>;
+    readonly page: boolean;
+    constructor(decision: Extract<ConsoleDecision, {
+        allowed: false;
+    }>, page: boolean);
+}
+/**
+ * Marks a console route that is not part of the console: `authorize` does not apply to it. Used on
+ * the `ctx.webhook()` callback, which third parties call with the token as the secret.
+ */
+declare const CONSOLE_PUBLIC_METADATA = "@dudousxd/nestjs-durable-dashboard:console-public";
+declare const ConsolePublic: () => MethodDecorator;
+declare class ConsoleAuthorizeGuard implements CanActivate {
+    private readonly decide;
+    constructor(decide: ConsoleDecide);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+declare class ConsoleAuthorizeFilter implements ExceptionFilter {
+    private readonly adapterHost;
+    constructor(adapterHost: HttpAdapterHost);
+    catch(exception: ConsoleAccessDenied, host: ArgumentsHost): void;
+}
+/**
+ * The guard and its filter as one class decorator, for a console you mount yourself
+ * (`routes: false`). List it ABOVE your authentication guards, so it runs after them.
+ */
+declare const UseConsoleAuthorize: () => ClassDecorator & MethodDecorator;
 
 /**
  * Read-model and actions backing the control-plane UI. Run-facing ops (list/detail/retry/cancel/
@@ -325,9 +428,9 @@ declare class DurableApiControllerBase {
     }>;
     /**
      * Public callback endpoint for `ctx.webhook()`: a third party POSTs here (the url handed to it),
-     * and the body resumes the waiting run. NOTE: this is reachable by external systems — protect it
-     * by treating the token as a secret (it embeds runId:seq) and/or fronting it with signature
-     * verification in your own middleware.
+     * and the body resumes the waiting run. Not a console route: the console's `authorize` does not
+     * apply, the token is the secret. The app's `decorators` still do. Treat the token as a secret
+     * and/or front it with signature verification in your own middleware.
      */
     webhook(token: string, body: unknown): Promise<_dudousxd_nestjs_durable_core.RunResult>;
     /** Live query: the latest value a run published for `key` via `ctx.setEvent` (no side effect). */
@@ -345,6 +448,25 @@ declare class DurableApiController extends DurableApiControllerBase {
 }
 
 interface DurableDashboardOptions {
+    /**
+     * Who may use the console (the SPA, its JSON API and the run stream). Not the `ctx.webhook()`
+     * callback (`POST <apiBasePath>/webhooks/:token`), which third parties call with the token as the
+     * secret; {@link decorators} still apply to it. One of:
+     *
+     * - a function `(context) => boolean | { allowed } | { redirectTo }` (may be async);
+     * - an `@Injectable()` class implementing {@link ConsoleAuthorizer} (constructor injection works;
+     *   its dependencies resolve from {@link imports} or global modules);
+     * - a lazy import `() => import('./console-access.js')` whose default export is such a class;
+     * - `{ policy, ability }`, checked with `@nestjs/authorization`'s `AuthorizationService`;
+     * - a gate name, resolved by `@dudousxd/nestjs-authz`'s `AuthzModule`.
+     *
+     * `authorizeByToken({ token })` builds one for a bearer token. It runs after the guards in
+     * {@link decorators}, so `request.user` is already set.
+     *
+     * Omitted: the console is open outside production and answers `403` to every request when
+     * `NODE_ENV=production`, and one warning is logged at boot.
+     */
+    authorize?: ConsoleAuthorize;
     /**
      * Where the SPA (UI) is served. Default `/durable`. This is a page route — keep it out of an
      * `/api` prefix so it reads as a UI, not an endpoint.
@@ -372,26 +494,26 @@ interface DurableDashboardOptions {
      * another registration or onto the exported classes. A guard named in `UseGuards(...)` resolves
      * its dependencies from {@link imports} (or a global module).
      *
-     * A non-empty `decorators` is how a mounted console states its protection. With
-     * `NODE_ENV=production`, a mounted console with no (or an empty) `decorators` fails the boot; see
-     * {@link DurableDashboardModule}. The module cannot tell a `Can(...)` from a decorator that
-     * protects nothing, so passing one is your statement that the console is protected.
+     * `decorators` is not access control on its own: {@link authorize} decides who gets in, and runs
+     * after these. Use `decorators` for what must run first, typically authentication.
      *
-     * Default: none. Outside production the console is then served open, and the controllers are
-     * marked `Can.Anyone()` for `@nestjs/authorization`, whose global guard otherwise refuses every
-     * route that declares no `@Can()`. A `@Can()` passed here is still enforced.
+     * The controllers are marked `Can.Anyone()` for `@nestjs/authorization`, whose global guard
+     * otherwise refuses every route that declares no `@Can()`. A `@Can()` passed here is still
+     * enforced.
      */
     decorators?: ClassDecorator[];
     /**
      * `false` mounts NO controllers: the SPA and its JSON API are not registered,
      * while every provider still is (the run read/action service, the run filter, the SPA's base
-     * paths). Serve the console from controllers of your own instead, protected with ordinary Nest
-     * decorators, by extending {@link DurableUiControllerBase} and {@link DurableApiControllerBase}:
+     * paths). Serve the console from controllers of your own instead, by extending
+     * {@link DurableUiControllerBase} and {@link DurableApiControllerBase}. Apply `authorize` to them
+     * with `@UseConsoleAuthorize()` (listed above your authentication guards, so it runs after them),
+     * or protect them with ordinary Nest decorators:
      *
      * ```ts
-     * @Controller('ops/durable') @UseGuards(AuthenticationGuard) @Can(ConsolePolicy, 'view')
+     * @Controller('ops/durable') @UseConsoleAuthorize() @UseGuards(AuthenticationGuard)
      * class ConsoleUi extends DurableUiControllerBase {}
-     * @Controller('ops/durable/api') @UseGuards(AuthenticationGuard) @Can(ConsolePolicy, 'view')
+     * @Controller('ops/durable/api') @UseConsoleAuthorize() @UseGuards(AuthenticationGuard)
      * class ConsoleApi extends DurableApiControllerBase {}
      * // in the module that declares them:
      * imports: [DurableDashboardModule.forRoot({ routes: false, basePath: '/ops/durable', apiBasePath: '/ops/durable/api' })]
@@ -400,8 +522,9 @@ interface DurableDashboardOptions {
      * `basePath`/`apiBasePath` still matter here: they are where you mounted the two controllers, and
      * the SPA is told to load its assets from `basePath` and fetch from `apiBasePath`.
      *
-     * The production rule does not apply: this module mounts nothing, and the routes are yours,
-     * protected by what you put on them like any other route you write. The `*Base` classes carry no
+     * `authorize` omitted works as for mounted routes: `@UseConsoleAuthorize()` lets every request
+     * through outside production and answers `403` in production, and the boot warning is logged.
+     * The `*Base` classes carry no
      * guards and no `Can.Anyone()` mark, so under `@nestjs/authorization`'s global guard a subclass
      * without a `@Can()` is denied. `decorators` throws when combined with `routes: false` rather than
      * being silently ignored.
@@ -411,10 +534,6 @@ interface DurableDashboardOptions {
      */
     routes?: boolean;
 }
-/** DI token of the boot-time check that refuses an unprotected console in production. */
-declare const DASHBOARD_PROTECTION_CHECK: unique symbol;
-/** The boot error for a mounted console with no `decorators` under `NODE_ENV=production`. */
-declare const UNPROTECTED_CONSOLE_IN_PRODUCTION: string;
 /**
  * Holds the JSON API controller + its read service, mounted on its own path by `forRoot`. Its own
  * dynamic module because enhancers (a guard from `decorators`) DI-instantiate from their
@@ -427,34 +546,19 @@ declare class DurableApiModule {
         routes?: boolean;
         /** See {@link DurableDashboardOptions.decorators}. */
         decorators?: ClassDecorator[];
+        /** See {@link DurableDashboardOptions.authorize}. */
+        authorize?: ConsoleAuthorize;
     }): DynamicModule;
 }
-/**
- * Mounts the control plane: the bundled React SPA at `basePath` and its JSON API at `apiBasePath`
- * (default `<basePath>/api`). Import via `DurableDashboardModule.forRoot(...)` (or `forRootAsync`
- * when `dashboardAuth`'s `login` hook needs injected services) alongside `DurableModule` (global),
- * so it resolves the engine and store. Front the routes with the first-class `guards` option
- * (plus `imports` for the guards' own dependencies) — see {@link DurableDashboardOptions.guards} —
- * or with the built-in `dashboardAuth` cookie login, or both.
- * With none of those (and no `decorators` / `token` / `allowUnauthenticated`), the console fails
- * closed when `NODE_ENV=production` — see {@link DurableDashboardOptions.allowUnauthenticated}.
- * `routes: false` mounts nothing and leaves serving the console to the host's own controllers — see
- * {@link DurableDashboardOptions.routes}.
- */
 /**
  * Mounts the control plane: the bundled React SPA at `basePath` and its JSON API at `apiBasePath`
  * (default `<basePath>/api`). Import via `DurableDashboardModule.forRoot(...)` alongside
  * `DurableModule` (global), so it resolves the engine and store.
  *
- * Protect the console with the first-party NestJS tools (`@nestjs/authentication`,
- * `@nestjs/authorization`), one of two ways:
- *
- * 1. `decorators` on the mounted controllers (see {@link DurableDashboardOptions.decorators});
- * 2. `routes: false`, and mount it yourself by extending `DurableUiControllerBase` /
- *    `DurableApiControllerBase` (see {@link DurableDashboardOptions.routes}).
- *
- * With `NODE_ENV=production`, a mounted console with no `decorators` fails the boot with
- * {@link UNPROTECTED_CONSOLE_IN_PRODUCTION}. Outside production it is served open, with a warning.
+ * Access is decided by {@link DurableDashboardOptions.authorize}. Without it the console is open
+ * outside production and denies every request in production, with one warning at boot.
+ * `routes: false` mounts nothing and leaves serving the console to the host's own controllers (see
+ * {@link DurableDashboardOptions.routes}).
  */
 declare class DurableDashboardModule {
     static forRoot(options?: DurableDashboardOptions): DynamicModule;
@@ -492,4 +596,4 @@ declare class DurableUiControllerBase {
 declare class DurableUiController extends DurableUiControllerBase {
 }
 
-export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DASHBOARD_PROTECTION_CHECK, DashboardService, DurableApiController, DurableApiControllerBase, DurableApiModule, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiControllerBase, UNPROTECTED_CONSOLE_IN_PRODUCTION, type WorkflowLifecyclePage };
+export { CONSOLE_AUTHORIZE_DECIDE, CONSOLE_AUTHORIZE_MISSING_WARNING, CONSOLE_GATE, CONSOLE_PAGE_METADATA, CONSOLE_PUBLIC_METADATA, ConsoleAccessDenied, type ConsoleAuthorize, ConsoleAuthorizeFilter, ConsoleAuthorizeGuard, type ConsoleAuthorizeResult, type ConsoleAuthorizer, type ConsoleAuthorizerClass, type ConsoleDecide, type ConsoleDecision, type ConsoleGate, ConsolePage, type ConsolePolicyCheck, ConsolePublic, DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DashboardService, DurableApiController, DurableApiControllerBase, DurableApiModule, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiControllerBase, UseConsoleAuthorize, type WorkflowLifecyclePage, authorizeByToken, normalizeConsoleResult, resolveConsoleAuthorize };

package/dist/server/index.d.ts

@@ -1,3 +1,5 @@
+import { HttpException, ExecutionContext, Type, ExceptionFilter, ArgumentsHost, CanActivate, Logger, DynamicModule, StreamableFile } from '@nestjs/common';
+import { HttpAdapterHost, ModuleRef } from '@nestjs/core';
 import * as _dudousxd_nestjs_durable_core from '@dudousxd/nestjs-durable-core';
 import { RunGateway, StateStore, WorkflowEngine, ScheduleListQuery, ScheduleDescription, RunResult, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, DurableTopology, GroupHealth, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RepublishLifecycleResult, WorkflowLifecycleLinks, UpdateResult, EngineEvent, AttributeFilter } from '@dudousxd/nestjs-durable-core';
 export { RunDetail } from '@dudousxd/nestjs-durable-core';
@@ -5,7 +7,108 @@ import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
 import * as _dudousxd_nestjs_filter from '@dudousxd/nestjs-filter';
 import { FilterRunner } from '@dudousxd/nestjs-filter';
-import { DynamicModule, StreamableFile } from '@nestjs/common';
+
+type ConsoleAuthorizeResult = boolean | {
+    allowed: true;
+} | {
+    allowed: false;
+    reason?: 'unauthenticated' | 'forbidden';
+} | {
+    redirectTo: string;
+};
+/** Class form: an `@Injectable()` provider (constructor injection works). */
+interface ConsoleAuthorizer {
+    authorize(context: ExecutionContext): ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>;
+}
+type ConsoleAuthorizerClass = Type<ConsoleAuthorizer>;
+/** An `@nestjs/authorization` policy check: `policy[ability](user)`. */
+interface ConsolePolicyCheck {
+    policy: Type<unknown>;
+    ability: string;
+}
+type ConsoleAuthorize = ((context: ExecutionContext) => ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>) | ConsoleAuthorizerClass | (() => Promise<{
+    default: ConsoleAuthorizerClass;
+}>) | ConsolePolicyCheck | string;
+type ConsoleDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: 'unauthenticated' | 'forbidden';
+    redirectTo?: string;
+};
+/** What a resolved `authorize` is: called once per request, never throws. */
+type ConsoleDecide = (context: ExecutionContext) => Promise<ConsoleDecision>;
+/**
+ * The provider `@dudousxd/nestjs-authz` registers to resolve gate names (`authorize: 'console.x'`).
+ * A registry symbol, so it is found without depending on that package.
+ */
+declare const CONSOLE_GATE: unique symbol;
+interface ConsoleGate {
+    allows(name: string, context: ExecutionContext): Promise<ConsoleAuthorizeResult>;
+}
+/** The one boot warning for a console with no `authorize`. Same wording in every Aviary console. */
+declare const CONSOLE_AUTHORIZE_MISSING_WARNING = "[@dudousxd/nestjs-durable-dashboard] console has no `authorize` configured: it is open outside production and denies every request in production. Set `authorize` in DurableDashboardModule.forRoot().";
+/** Turns any {@link ConsoleAuthorizeResult} into a {@link ConsoleDecision}. */
+declare function normalizeConsoleResult(result: unknown): ConsoleDecision;
+/**
+ * Resolves `authorize` into one function the guard calls per request. Resolution errors that are
+ * configuration mistakes (a gate name without nestjs-authz, a policy without @nestjs/authorization)
+ * throw here, so call it at boot. The returned function never throws: an error is a `forbidden`.
+ *
+ * `authorize` omitted: open outside production, `forbidden` for every request in production (read
+ * when this runs), and one warning logged (unless `warnIfMissing: false`).
+ */
+declare function resolveConsoleAuthorize(authorize: ConsoleAuthorize | undefined, moduleRef: ModuleRef, options?: {
+    logger?: Logger;
+    warnIfMissing?: boolean;
+}): Promise<ConsoleDecide>;
+/**
+ * Allows a request carrying `Authorization: Bearer <token>` (compared timing-safe); anything else
+ * is `unauthenticated`. Header only: no query string, no custom header. Throws when `token` is
+ * empty, so a missing env var fails at config time instead of opening the console.
+ */
+declare function authorizeByToken(options: {
+    token: string | undefined;
+}): ConsoleAuthorize;
+/** DI token of the resolved {@link ConsoleDecide} the guard runs. */
+declare const CONSOLE_AUTHORIZE_DECIDE: unique symbol;
+/** Marks a controller as serving pages: a denied `GET` that accepts HTML gets a page, not JSON. */
+declare const CONSOLE_PAGE_METADATA = "@dudousxd/nestjs-durable-dashboard:console-page";
+declare const ConsolePage: () => ClassDecorator;
+/**
+ * The denial the guard throws. An `HttpException` with the JSON body, so it still answers correctly
+ * where {@link ConsoleAuthorizeFilter} is not applied; the filter adds the page answers.
+ */
+declare class ConsoleAccessDenied extends HttpException {
+    readonly decision: Extract<ConsoleDecision, {
+        allowed: false;
+    }>;
+    readonly page: boolean;
+    constructor(decision: Extract<ConsoleDecision, {
+        allowed: false;
+    }>, page: boolean);
+}
+/**
+ * Marks a console route that is not part of the console: `authorize` does not apply to it. Used on
+ * the `ctx.webhook()` callback, which third parties call with the token as the secret.
+ */
+declare const CONSOLE_PUBLIC_METADATA = "@dudousxd/nestjs-durable-dashboard:console-public";
+declare const ConsolePublic: () => MethodDecorator;
+declare class ConsoleAuthorizeGuard implements CanActivate {
+    private readonly decide;
+    constructor(decide: ConsoleDecide);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+declare class ConsoleAuthorizeFilter implements ExceptionFilter {
+    private readonly adapterHost;
+    constructor(adapterHost: HttpAdapterHost);
+    catch(exception: ConsoleAccessDenied, host: ArgumentsHost): void;
+}
+/**
+ * The guard and its filter as one class decorator, for a console you mount yourself
+ * (`routes: false`). List it ABOVE your authentication guards, so it runs after them.
+ */
+declare const UseConsoleAuthorize: () => ClassDecorator & MethodDecorator;
 
 /**
  * Read-model and actions backing the control-plane UI. Run-facing ops (list/detail/retry/cancel/
@@ -325,9 +428,9 @@ declare class DurableApiControllerBase {
     }>;
     /**
      * Public callback endpoint for `ctx.webhook()`: a third party POSTs here (the url handed to it),
-     * and the body resumes the waiting run. NOTE: this is reachable by external systems — protect it
-     * by treating the token as a secret (it embeds runId:seq) and/or fronting it with signature
-     * verification in your own middleware.
+     * and the body resumes the waiting run. Not a console route: the console's `authorize` does not
+     * apply, the token is the secret. The app's `decorators` still do. Treat the token as a secret
+     * and/or front it with signature verification in your own middleware.
      */
     webhook(token: string, body: unknown): Promise<_dudousxd_nestjs_durable_core.RunResult>;
     /** Live query: the latest value a run published for `key` via `ctx.setEvent` (no side effect). */
@@ -345,6 +448,25 @@ declare class DurableApiController extends DurableApiControllerBase {
 }
 
 interface DurableDashboardOptions {
+    /**
+     * Who may use the console (the SPA, its JSON API and the run stream). Not the `ctx.webhook()`
+     * callback (`POST <apiBasePath>/webhooks/:token`), which third parties call with the token as the
+     * secret; {@link decorators} still apply to it. One of:
+     *
+     * - a function `(context) => boolean | { allowed } | { redirectTo }` (may be async);
+     * - an `@Injectable()` class implementing {@link ConsoleAuthorizer} (constructor injection works;
+     *   its dependencies resolve from {@link imports} or global modules);
+     * - a lazy import `() => import('./console-access.js')` whose default export is such a class;
+     * - `{ policy, ability }`, checked with `@nestjs/authorization`'s `AuthorizationService`;
+     * - a gate name, resolved by `@dudousxd/nestjs-authz`'s `AuthzModule`.
+     *
+     * `authorizeByToken({ token })` builds one for a bearer token. It runs after the guards in
+     * {@link decorators}, so `request.user` is already set.
+     *
+     * Omitted: the console is open outside production and answers `403` to every request when
+     * `NODE_ENV=production`, and one warning is logged at boot.
+     */
+    authorize?: ConsoleAuthorize;
     /**
      * Where the SPA (UI) is served. Default `/durable`. This is a page route — keep it out of an
      * `/api` prefix so it reads as a UI, not an endpoint.
@@ -372,26 +494,26 @@ interface DurableDashboardOptions {
      * another registration or onto the exported classes. A guard named in `UseGuards(...)` resolves
      * its dependencies from {@link imports} (or a global module).
      *
-     * A non-empty `decorators` is how a mounted console states its protection. With
-     * `NODE_ENV=production`, a mounted console with no (or an empty) `decorators` fails the boot; see
-     * {@link DurableDashboardModule}. The module cannot tell a `Can(...)` from a decorator that
-     * protects nothing, so passing one is your statement that the console is protected.
+     * `decorators` is not access control on its own: {@link authorize} decides who gets in, and runs
+     * after these. Use `decorators` for what must run first, typically authentication.
      *
-     * Default: none. Outside production the console is then served open, and the controllers are
-     * marked `Can.Anyone()` for `@nestjs/authorization`, whose global guard otherwise refuses every
-     * route that declares no `@Can()`. A `@Can()` passed here is still enforced.
+     * The controllers are marked `Can.Anyone()` for `@nestjs/authorization`, whose global guard
+     * otherwise refuses every route that declares no `@Can()`. A `@Can()` passed here is still
+     * enforced.
      */
     decorators?: ClassDecorator[];
     /**
      * `false` mounts NO controllers: the SPA and its JSON API are not registered,
      * while every provider still is (the run read/action service, the run filter, the SPA's base
-     * paths). Serve the console from controllers of your own instead, protected with ordinary Nest
-     * decorators, by extending {@link DurableUiControllerBase} and {@link DurableApiControllerBase}:
+     * paths). Serve the console from controllers of your own instead, by extending
+     * {@link DurableUiControllerBase} and {@link DurableApiControllerBase}. Apply `authorize` to them
+     * with `@UseConsoleAuthorize()` (listed above your authentication guards, so it runs after them),
+     * or protect them with ordinary Nest decorators:
      *
      * ```ts
-     * @Controller('ops/durable') @UseGuards(AuthenticationGuard) @Can(ConsolePolicy, 'view')
+     * @Controller('ops/durable') @UseConsoleAuthorize() @UseGuards(AuthenticationGuard)
      * class ConsoleUi extends DurableUiControllerBase {}
-     * @Controller('ops/durable/api') @UseGuards(AuthenticationGuard) @Can(ConsolePolicy, 'view')
+     * @Controller('ops/durable/api') @UseConsoleAuthorize() @UseGuards(AuthenticationGuard)
      * class ConsoleApi extends DurableApiControllerBase {}
      * // in the module that declares them:
      * imports: [DurableDashboardModule.forRoot({ routes: false, basePath: '/ops/durable', apiBasePath: '/ops/durable/api' })]
@@ -400,8 +522,9 @@ interface DurableDashboardOptions {
      * `basePath`/`apiBasePath` still matter here: they are where you mounted the two controllers, and
      * the SPA is told to load its assets from `basePath` and fetch from `apiBasePath`.
      *
-     * The production rule does not apply: this module mounts nothing, and the routes are yours,
-     * protected by what you put on them like any other route you write. The `*Base` classes carry no
+     * `authorize` omitted works as for mounted routes: `@UseConsoleAuthorize()` lets every request
+     * through outside production and answers `403` in production, and the boot warning is logged.
+     * The `*Base` classes carry no
      * guards and no `Can.Anyone()` mark, so under `@nestjs/authorization`'s global guard a subclass
      * without a `@Can()` is denied. `decorators` throws when combined with `routes: false` rather than
      * being silently ignored.
@@ -411,10 +534,6 @@ interface DurableDashboardOptions {
      */
     routes?: boolean;
 }
-/** DI token of the boot-time check that refuses an unprotected console in production. */
-declare const DASHBOARD_PROTECTION_CHECK: unique symbol;
-/** The boot error for a mounted console with no `decorators` under `NODE_ENV=production`. */
-declare const UNPROTECTED_CONSOLE_IN_PRODUCTION: string;
 /**
  * Holds the JSON API controller + its read service, mounted on its own path by `forRoot`. Its own
  * dynamic module because enhancers (a guard from `decorators`) DI-instantiate from their
@@ -427,34 +546,19 @@ declare class DurableApiModule {
         routes?: boolean;
         /** See {@link DurableDashboardOptions.decorators}. */
         decorators?: ClassDecorator[];
+        /** See {@link DurableDashboardOptions.authorize}. */
+        authorize?: ConsoleAuthorize;
     }): DynamicModule;
 }
-/**
- * Mounts the control plane: the bundled React SPA at `basePath` and its JSON API at `apiBasePath`
- * (default `<basePath>/api`). Import via `DurableDashboardModule.forRoot(...)` (or `forRootAsync`
- * when `dashboardAuth`'s `login` hook needs injected services) alongside `DurableModule` (global),
- * so it resolves the engine and store. Front the routes with the first-class `guards` option
- * (plus `imports` for the guards' own dependencies) — see {@link DurableDashboardOptions.guards} —
- * or with the built-in `dashboardAuth` cookie login, or both.
- * With none of those (and no `decorators` / `token` / `allowUnauthenticated`), the console fails
- * closed when `NODE_ENV=production` — see {@link DurableDashboardOptions.allowUnauthenticated}.
- * `routes: false` mounts nothing and leaves serving the console to the host's own controllers — see
- * {@link DurableDashboardOptions.routes}.
- */
 /**
  * Mounts the control plane: the bundled React SPA at `basePath` and its JSON API at `apiBasePath`
  * (default `<basePath>/api`). Import via `DurableDashboardModule.forRoot(...)` alongside
  * `DurableModule` (global), so it resolves the engine and store.
  *
- * Protect the console with the first-party NestJS tools (`@nestjs/authentication`,
- * `@nestjs/authorization`), one of two ways:
- *
- * 1. `decorators` on the mounted controllers (see {@link DurableDashboardOptions.decorators});
- * 2. `routes: false`, and mount it yourself by extending `DurableUiControllerBase` /
- *    `DurableApiControllerBase` (see {@link DurableDashboardOptions.routes}).
- *
- * With `NODE_ENV=production`, a mounted console with no `decorators` fails the boot with
- * {@link UNPROTECTED_CONSOLE_IN_PRODUCTION}. Outside production it is served open, with a warning.
+ * Access is decided by {@link DurableDashboardOptions.authorize}. Without it the console is open
+ * outside production and denies every request in production, with one warning at boot.
+ * `routes: false` mounts nothing and leaves serving the console to the host's own controllers (see
+ * {@link DurableDashboardOptions.routes}).
  */
 declare class DurableDashboardModule {
     static forRoot(options?: DurableDashboardOptions): DynamicModule;
@@ -492,4 +596,4 @@ declare class DurableUiControllerBase {
 declare class DurableUiController extends DurableUiControllerBase {
 }
 
-export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DASHBOARD_PROTECTION_CHECK, DashboardService, DurableApiController, DurableApiControllerBase, DurableApiModule, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiControllerBase, UNPROTECTED_CONSOLE_IN_PRODUCTION, type WorkflowLifecyclePage };
+export { CONSOLE_AUTHORIZE_DECIDE, CONSOLE_AUTHORIZE_MISSING_WARNING, CONSOLE_GATE, CONSOLE_PAGE_METADATA, CONSOLE_PUBLIC_METADATA, ConsoleAccessDenied, type ConsoleAuthorize, ConsoleAuthorizeFilter, ConsoleAuthorizeGuard, type ConsoleAuthorizeResult, type ConsoleAuthorizer, type ConsoleAuthorizerClass, type ConsoleDecide, type ConsoleDecision, type ConsoleGate, ConsolePage, type ConsolePolicyCheck, ConsolePublic, DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DashboardService, DurableApiController, DurableApiControllerBase, DurableApiModule, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiControllerBase, UseConsoleAuthorize, type WorkflowLifecyclePage, authorizeByToken, normalizeConsoleResult, resolveConsoleAuthorize };