@dudousxd/nestjs-durable-dashboard 0.51.1 → 0.52.0

package/dist/server/index.d.cts

@@ -5,7 +5,7 @@ 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, Type, CanActivate, Provider, InjectionToken, OptionalFactoryDependency, ExecutionContext, StreamableFile } from '@nestjs/common';
+import { CanActivate, ExecutionContext, Provider, Logger, DynamicModule, Type, InjectionToken, OptionalFactoryDependency, StreamableFile } from '@nestjs/common';
 
 /** The session user the host `login` hook returns to mint a cookie. */
 interface DashboardSessionUser {
@@ -416,6 +416,68 @@ declare class DurableAuthController {
     private runHook;
 }
 
+/** The env var the token gate reads when no `token` option is given. */
+declare const DURABLE_DASHBOARD_TOKEN_ENV = "DURABLE_DASHBOARD_TOKEN";
+/** DI token carrying the resolved {@link DashboardGate} (one per dashboard mount). */
+declare const DASHBOARD_GATE: unique symbol;
+/**
+ * What the module knows about how the console is protected, captured at `forRoot`/`forRootAsync`
+ * time. Everything that can change between module definition and boot (env vars, the async
+ * `dashboardAuth` factory) is read later, in {@link resolveDashboardGate}.
+ */
+interface DashboardGateOptions {
+    /** Host `guards` were passed (non-empty). */
+    hasGuards: boolean;
+    /** `allowUnauthenticated` as passed. */
+    allowUnauthenticated?: boolean;
+    /** `token` as passed (else `DURABLE_DASHBOARD_TOKEN` is read at boot). */
+    token?: string;
+}
+/**
+ * How the gate treats every console request:
+ *
+ * - `delegated`: `guards` or `dashboardAuth` protect the console; the gate passes everything.
+ * - `open`: `allowUnauthenticated: true`; the gate passes everything (warned at boot).
+ * - `token`: a request must carry the token (`Authorization: Bearer`, `x-durable-token`, or
+ *   `?token=` on GET/HEAD).
+ * - `unconfigured`: nothing was configured outside production; the gate passes everything
+ *   (warned at boot, because production will deny).
+ * - `deny`: nothing was configured and `NODE_ENV=production`; every request is refused.
+ */
+type DashboardGateMode = 'delegated' | 'open' | 'token' | 'unconfigured' | 'deny';
+interface DashboardGate {
+    mode: DashboardGateMode;
+    /** Set only when `mode === 'token'`. */
+    token?: string;
+}
+/**
+ * Decide the gate mode. Precedence: `guards`/`dashboardAuth` (they are the gate) > a token > the
+ * `allowUnauthenticated` opt-out > the environment default. A token beats `allowUnauthenticated`
+ * because a configured secret is never silently ignored.
+ */
+declare function resolveDashboardGate(options: DashboardGateOptions, auth: ResolvedDashboardAuth | null): DashboardGate;
+/** Log the one boot line the resolved gate calls for (nothing for a properly configured console). */
+declare function reportDashboardGate(gate: DashboardGate, options: DashboardGateOptions, logger?: Pick<Logger, 'warn' | 'error'>): void;
+/** The `DASHBOARD_GATE` provider: resolves once, after `DASHBOARD_AUTH`, and logs once. */
+declare function dashboardGateProvider(options: DashboardGateOptions): Provider;
+/**
+ * Read the token from `Authorization: Bearer <token>`, `x-durable-token`, or (GET/HEAD only) a
+ * `token` query param. The query channel is read-only on purpose: a `?token=` URL ends up in access
+ * logs, `Referer` headers and browser history, and must never authorize a mutation.
+ */
+declare function readDashboardToken(request: unknown): string | undefined;
+/**
+ * The fail-closed default gate, stamped on `DurableUiController` and `DurableApiController` (after
+ * the built-in session guard, before host `guards`) whenever the module can't prove at definition
+ * time that something else protects the console. It never gates `DurableAuthController`, so the
+ * login/session/logout routes stay reachable. See {@link DashboardGateMode} for what each mode does.
+ */
+declare class DurableDashboardGateGuard implements CanActivate {
+    private readonly gate;
+    constructor(gate: DashboardGate);
+    canActivate(context: ExecutionContext): boolean;
+}
+
 interface DurableDashboardOptions {
     /**
      * Where the SPA (UI) is served. Default `/durable`. This is a page route — keep it out of an
@@ -432,8 +494,10 @@ interface DurableDashboardOptions {
      * Guard classes fronting BOTH dashboard controllers (the SPA at `basePath` and its JSON API at
      * `apiBasePath`). Stamped onto each controller via `@nestjs/common`'s own `@UseGuards` metadata key
      * — REPLACE semantics, so a second `forRoot(...)` call overwrites (not appends to) whatever a prior
-     * call stamped, same as re-applying `@UseGuards` by hand. Omit to leave the routes unguarded (the
-     * host fronts them another way, e.g. a global guard or reverse-proxy auth).
+     * call stamped, same as re-applying `@UseGuards` by hand. A non-empty `guards` counts as the
+     * console's authentication, so the fail-closed default gate steps aside (see
+     * {@link allowUnauthenticated}). If the host fronts the routes another way (a global guard,
+     * reverse-proxy auth), say so with `allowUnauthenticated: true` instead.
      *
      * A guard's own DEPENDENCIES resolve from this module's `imports` (see {@link imports}) — the
      * dashboard module has no application context of its own to pull them from otherwise.
@@ -494,15 +558,36 @@ interface DurableDashboardOptions {
      *
      * Composes with {@link guards}: when both are set, a request must pass the built-in session check
      * AND every guard in `guards` — the SAME logical-AND semantics `@UseGuards` already gives multiple
-     * guards, since the built-in guard is simply prepended to whatever `guards` you pass. Omit to leave
-     * the console open (today's behavior, unchanged byte-for-byte) — front it with `guards`, a global
-     * guard, or a reverse proxy instead.
+     * guards, since the built-in guard is simply prepended to whatever `guards` you pass. Setting it
+     * counts as the console's authentication (the fail-closed default gate steps aside). Omit it and
+     * configure `guards`, a {@link token}, or {@link allowUnauthenticated} instead.
      *
      * See {@link DashboardAuthOptions} for the `secret`/`ttl`/`session`/`login`/`revalidate` shape,
      * and `forRootAsync` / {@link DurableDashboardAsyncOptions.useDashboardAuth} when a hook needs DI
      * (e.g. an `EntityManager` to look up an admin user).
      */
     dashboardAuth?: DashboardAuthOptions;
+    /**
+     * Explicitly serve the console with NO authentication from this module. Use it only when
+     * something outside the module already protects it: a global guard, a reverse proxy / SSO in
+     * front of the mount, a private network. Logs a boot warning.
+     *
+     * Without it, an unconfigured console (no `guards`, no `dashboardAuth`, no token) is DENIED when
+     * `NODE_ENV=production` (every UI and API request answers `403`, and one boot error explains how
+     * to configure it). Outside production it is still served open, with a boot warning. Ignored when
+     * `guards`, `dashboardAuth` or a token is configured.
+     */
+    allowUnauthenticated?: boolean;
+    /**
+     * Bearer-token gate for the console. Defaults to `process.env.DURABLE_DASHBOARD_TOKEN` (read at
+     * boot). Only applies when neither `guards` nor `dashboardAuth` is configured: every UI and API
+     * request must then carry it as `Authorization: Bearer <token>`, an `x-durable-token` header, or
+     * (GET/HEAD only) a `?token=` query param, compared in constant time; anything else gets `401`.
+     *
+     * Meant for scripts and reverse proxies that inject the header: the bundled SPA does not attach
+     * the token to its own asset and API requests. Browser operators want `dashboardAuth` or `guards`.
+     */
+    token?: string;
 }
 /**
  * Async variant of {@link DurableDashboardOptions}. The mount paths and `guards` stay static (the
@@ -510,7 +595,9 @@ interface DurableDashboardOptions {
  * already has), but `dashboardAuth` is built by an injected factory, so its `session`/`login` hooks
  * can reach your DB/services — e.g. Mode A's `session` hook calling out to the same auth service
  * your host app already uses to validate the raw request. Returning `undefined` from
- * `useDashboardAuth` leaves the console open, exactly like omitting `dashboardAuth` from `forRoot`.
+ * `useDashboardAuth` is exactly like omitting `dashboardAuth` from `forRoot`: the console then
+ * falls back to `guards` / the token / `allowUnauthenticated`, and is DENIED in production when
+ * none of those is configured.
  */
 interface DurableDashboardAsyncOptions {
     basePath?: string;
@@ -519,8 +606,12 @@ interface DurableDashboardAsyncOptions {
     imports?: DynamicModule['imports'];
     /** Providers injected into `useDashboardAuth`, in order. Shared with a `guards` class's own deps. */
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
-    /** Build the `dashboardAuth` config from injected deps (or `undefined` to leave the console open). */
+    /** Build the `dashboardAuth` config from injected deps (or `undefined` for no session auth). */
     useDashboardAuth: (...deps: any[]) => DashboardAuthOptions | undefined | Promise<DashboardAuthOptions | undefined>;
+    /** See {@link DurableDashboardOptions.allowUnauthenticated}. */
+    allowUnauthenticated?: boolean;
+    /** See {@link DurableDashboardOptions.token}. */
+    token?: string;
 }
 /**
  * Holds the JSON API controller + its read service, mounted on its own path by `forRoot`. Dynamic:
@@ -540,6 +631,10 @@ declare class DurableApiModule {
          *  (true whenever `dashboardAuth` was set, or unconditionally for `forRootAsync`, where it's
          *  resolved at runtime and is a no-op if it ends up unconfigured). */
         authMayBeConfigured: boolean;
+        /** What the fail-closed gate needs; resolved into `DASHBOARD_GATE` at boot (logged once). */
+        gate: DashboardGateOptions;
+        /** Whether `DurableDashboardGateGuard` is stamped (false when guards/dashboardAuth are static). */
+        stampGate: boolean;
     }): DynamicModule;
 }
 /**
@@ -549,6 +644,8 @@ declare class DurableApiModule {
  * 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 `token` / `allowUnauthenticated`), the console fails closed when
+ * `NODE_ENV=production` — see {@link DurableDashboardOptions.allowUnauthenticated}.
  */
 declare class DurableDashboardModule {
     static forRoot(options?: DurableDashboardOptions): DynamicModule;
@@ -635,4 +732,4 @@ declare class DurableUiController {
     asset(file: string): StreamableFile;
 }
 
-export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, type DashboardAuthOptions, DashboardService, type DashboardSessionUser, DurableApiController, DurableApiModule, DurableApiSessionGuard, DurableAuthController, type DurableDashboardAsyncOptions, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiSessionGuard, type UnauthenticatedPageContext, type UnauthenticatedPageHook };
+export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DASHBOARD_GATE, DURABLE_DASHBOARD_TOKEN_ENV, type DashboardAuthOptions, type DashboardGate, type DashboardGateMode, type DashboardGateOptions, DashboardService, type DashboardSessionUser, DurableApiController, DurableApiModule, DurableApiSessionGuard, DurableAuthController, type DurableDashboardAsyncOptions, DurableDashboardGateGuard, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiSessionGuard, type UnauthenticatedPageContext, type UnauthenticatedPageHook, dashboardGateProvider, readDashboardToken, reportDashboardGate, resolveDashboardGate };

package/dist/server/index.d.ts

@@ -5,7 +5,7 @@ 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, Type, CanActivate, Provider, InjectionToken, OptionalFactoryDependency, ExecutionContext, StreamableFile } from '@nestjs/common';
+import { CanActivate, ExecutionContext, Provider, Logger, DynamicModule, Type, InjectionToken, OptionalFactoryDependency, StreamableFile } from '@nestjs/common';
 
 /** The session user the host `login` hook returns to mint a cookie. */
 interface DashboardSessionUser {
@@ -416,6 +416,68 @@ declare class DurableAuthController {
     private runHook;
 }
 
+/** The env var the token gate reads when no `token` option is given. */
+declare const DURABLE_DASHBOARD_TOKEN_ENV = "DURABLE_DASHBOARD_TOKEN";
+/** DI token carrying the resolved {@link DashboardGate} (one per dashboard mount). */
+declare const DASHBOARD_GATE: unique symbol;
+/**
+ * What the module knows about how the console is protected, captured at `forRoot`/`forRootAsync`
+ * time. Everything that can change between module definition and boot (env vars, the async
+ * `dashboardAuth` factory) is read later, in {@link resolveDashboardGate}.
+ */
+interface DashboardGateOptions {
+    /** Host `guards` were passed (non-empty). */
+    hasGuards: boolean;
+    /** `allowUnauthenticated` as passed. */
+    allowUnauthenticated?: boolean;
+    /** `token` as passed (else `DURABLE_DASHBOARD_TOKEN` is read at boot). */
+    token?: string;
+}
+/**
+ * How the gate treats every console request:
+ *
+ * - `delegated`: `guards` or `dashboardAuth` protect the console; the gate passes everything.
+ * - `open`: `allowUnauthenticated: true`; the gate passes everything (warned at boot).
+ * - `token`: a request must carry the token (`Authorization: Bearer`, `x-durable-token`, or
+ *   `?token=` on GET/HEAD).
+ * - `unconfigured`: nothing was configured outside production; the gate passes everything
+ *   (warned at boot, because production will deny).
+ * - `deny`: nothing was configured and `NODE_ENV=production`; every request is refused.
+ */
+type DashboardGateMode = 'delegated' | 'open' | 'token' | 'unconfigured' | 'deny';
+interface DashboardGate {
+    mode: DashboardGateMode;
+    /** Set only when `mode === 'token'`. */
+    token?: string;
+}
+/**
+ * Decide the gate mode. Precedence: `guards`/`dashboardAuth` (they are the gate) > a token > the
+ * `allowUnauthenticated` opt-out > the environment default. A token beats `allowUnauthenticated`
+ * because a configured secret is never silently ignored.
+ */
+declare function resolveDashboardGate(options: DashboardGateOptions, auth: ResolvedDashboardAuth | null): DashboardGate;
+/** Log the one boot line the resolved gate calls for (nothing for a properly configured console). */
+declare function reportDashboardGate(gate: DashboardGate, options: DashboardGateOptions, logger?: Pick<Logger, 'warn' | 'error'>): void;
+/** The `DASHBOARD_GATE` provider: resolves once, after `DASHBOARD_AUTH`, and logs once. */
+declare function dashboardGateProvider(options: DashboardGateOptions): Provider;
+/**
+ * Read the token from `Authorization: Bearer <token>`, `x-durable-token`, or (GET/HEAD only) a
+ * `token` query param. The query channel is read-only on purpose: a `?token=` URL ends up in access
+ * logs, `Referer` headers and browser history, and must never authorize a mutation.
+ */
+declare function readDashboardToken(request: unknown): string | undefined;
+/**
+ * The fail-closed default gate, stamped on `DurableUiController` and `DurableApiController` (after
+ * the built-in session guard, before host `guards`) whenever the module can't prove at definition
+ * time that something else protects the console. It never gates `DurableAuthController`, so the
+ * login/session/logout routes stay reachable. See {@link DashboardGateMode} for what each mode does.
+ */
+declare class DurableDashboardGateGuard implements CanActivate {
+    private readonly gate;
+    constructor(gate: DashboardGate);
+    canActivate(context: ExecutionContext): boolean;
+}
+
 interface DurableDashboardOptions {
     /**
      * Where the SPA (UI) is served. Default `/durable`. This is a page route — keep it out of an
@@ -432,8 +494,10 @@ interface DurableDashboardOptions {
      * Guard classes fronting BOTH dashboard controllers (the SPA at `basePath` and its JSON API at
      * `apiBasePath`). Stamped onto each controller via `@nestjs/common`'s own `@UseGuards` metadata key
      * — REPLACE semantics, so a second `forRoot(...)` call overwrites (not appends to) whatever a prior
-     * call stamped, same as re-applying `@UseGuards` by hand. Omit to leave the routes unguarded (the
-     * host fronts them another way, e.g. a global guard or reverse-proxy auth).
+     * call stamped, same as re-applying `@UseGuards` by hand. A non-empty `guards` counts as the
+     * console's authentication, so the fail-closed default gate steps aside (see
+     * {@link allowUnauthenticated}). If the host fronts the routes another way (a global guard,
+     * reverse-proxy auth), say so with `allowUnauthenticated: true` instead.
      *
      * A guard's own DEPENDENCIES resolve from this module's `imports` (see {@link imports}) — the
      * dashboard module has no application context of its own to pull them from otherwise.
@@ -494,15 +558,36 @@ interface DurableDashboardOptions {
      *
      * Composes with {@link guards}: when both are set, a request must pass the built-in session check
      * AND every guard in `guards` — the SAME logical-AND semantics `@UseGuards` already gives multiple
-     * guards, since the built-in guard is simply prepended to whatever `guards` you pass. Omit to leave
-     * the console open (today's behavior, unchanged byte-for-byte) — front it with `guards`, a global
-     * guard, or a reverse proxy instead.
+     * guards, since the built-in guard is simply prepended to whatever `guards` you pass. Setting it
+     * counts as the console's authentication (the fail-closed default gate steps aside). Omit it and
+     * configure `guards`, a {@link token}, or {@link allowUnauthenticated} instead.
      *
      * See {@link DashboardAuthOptions} for the `secret`/`ttl`/`session`/`login`/`revalidate` shape,
      * and `forRootAsync` / {@link DurableDashboardAsyncOptions.useDashboardAuth} when a hook needs DI
      * (e.g. an `EntityManager` to look up an admin user).
      */
     dashboardAuth?: DashboardAuthOptions;
+    /**
+     * Explicitly serve the console with NO authentication from this module. Use it only when
+     * something outside the module already protects it: a global guard, a reverse proxy / SSO in
+     * front of the mount, a private network. Logs a boot warning.
+     *
+     * Without it, an unconfigured console (no `guards`, no `dashboardAuth`, no token) is DENIED when
+     * `NODE_ENV=production` (every UI and API request answers `403`, and one boot error explains how
+     * to configure it). Outside production it is still served open, with a boot warning. Ignored when
+     * `guards`, `dashboardAuth` or a token is configured.
+     */
+    allowUnauthenticated?: boolean;
+    /**
+     * Bearer-token gate for the console. Defaults to `process.env.DURABLE_DASHBOARD_TOKEN` (read at
+     * boot). Only applies when neither `guards` nor `dashboardAuth` is configured: every UI and API
+     * request must then carry it as `Authorization: Bearer <token>`, an `x-durable-token` header, or
+     * (GET/HEAD only) a `?token=` query param, compared in constant time; anything else gets `401`.
+     *
+     * Meant for scripts and reverse proxies that inject the header: the bundled SPA does not attach
+     * the token to its own asset and API requests. Browser operators want `dashboardAuth` or `guards`.
+     */
+    token?: string;
 }
 /**
  * Async variant of {@link DurableDashboardOptions}. The mount paths and `guards` stay static (the
@@ -510,7 +595,9 @@ interface DurableDashboardOptions {
  * already has), but `dashboardAuth` is built by an injected factory, so its `session`/`login` hooks
  * can reach your DB/services — e.g. Mode A's `session` hook calling out to the same auth service
  * your host app already uses to validate the raw request. Returning `undefined` from
- * `useDashboardAuth` leaves the console open, exactly like omitting `dashboardAuth` from `forRoot`.
+ * `useDashboardAuth` is exactly like omitting `dashboardAuth` from `forRoot`: the console then
+ * falls back to `guards` / the token / `allowUnauthenticated`, and is DENIED in production when
+ * none of those is configured.
  */
 interface DurableDashboardAsyncOptions {
     basePath?: string;
@@ -519,8 +606,12 @@ interface DurableDashboardAsyncOptions {
     imports?: DynamicModule['imports'];
     /** Providers injected into `useDashboardAuth`, in order. Shared with a `guards` class's own deps. */
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
-    /** Build the `dashboardAuth` config from injected deps (or `undefined` to leave the console open). */
+    /** Build the `dashboardAuth` config from injected deps (or `undefined` for no session auth). */
     useDashboardAuth: (...deps: any[]) => DashboardAuthOptions | undefined | Promise<DashboardAuthOptions | undefined>;
+    /** See {@link DurableDashboardOptions.allowUnauthenticated}. */
+    allowUnauthenticated?: boolean;
+    /** See {@link DurableDashboardOptions.token}. */
+    token?: string;
 }
 /**
  * Holds the JSON API controller + its read service, mounted on its own path by `forRoot`. Dynamic:
@@ -540,6 +631,10 @@ declare class DurableApiModule {
          *  (true whenever `dashboardAuth` was set, or unconditionally for `forRootAsync`, where it's
          *  resolved at runtime and is a no-op if it ends up unconfigured). */
         authMayBeConfigured: boolean;
+        /** What the fail-closed gate needs; resolved into `DASHBOARD_GATE` at boot (logged once). */
+        gate: DashboardGateOptions;
+        /** Whether `DurableDashboardGateGuard` is stamped (false when guards/dashboardAuth are static). */
+        stampGate: boolean;
     }): DynamicModule;
 }
 /**
@@ -549,6 +644,8 @@ declare class DurableApiModule {
  * 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 `token` / `allowUnauthenticated`), the console fails closed when
+ * `NODE_ENV=production` — see {@link DurableDashboardOptions.allowUnauthenticated}.
  */
 declare class DurableDashboardModule {
     static forRoot(options?: DurableDashboardOptions): DynamicModule;
@@ -635,4 +732,4 @@ declare class DurableUiController {
     asset(file: string): StreamableFile;
 }
 
-export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, type DashboardAuthOptions, DashboardService, type DashboardSessionUser, DurableApiController, DurableApiModule, DurableApiSessionGuard, DurableAuthController, type DurableDashboardAsyncOptions, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiSessionGuard, type UnauthenticatedPageContext, type UnauthenticatedPageHook };
+export { DASHBOARD_API_PATH, DASHBOARD_BASE_PATH, DASHBOARD_GATE, DURABLE_DASHBOARD_TOKEN_ENV, type DashboardAuthOptions, type DashboardGate, type DashboardGateMode, type DashboardGateOptions, DashboardService, type DashboardSessionUser, DurableApiController, DurableApiModule, DurableApiSessionGuard, DurableAuthController, type DurableDashboardAsyncOptions, DurableDashboardGateGuard, DurableDashboardModule, type DurableDashboardOptions, DurableUiController, DurableUiSessionGuard, type UnauthenticatedPageContext, type UnauthenticatedPageHook, dashboardGateProvider, readDashboardToken, reportDashboardGate, resolveDashboardGate };