@dudousxd/nestjs-telescope-ui 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @dudousxd/nestjs-telescope-ui
 
+## 1.16.0
+
+### Minor Changes
+
+- [`46f6bd4`](https://github.com/DavideCarvalho/nestjs-telescope/commit/46f6bd491c962f694ed41066f47da4da29671c3f) - First-class `guards` (+ `imports`) options for the Telescope console, mirroring `@dudousxd/nestjs-agent`'s dashboard module: `TelescopeModule.forRoot`/`forRootAsync` and `TelescopeUiModule.forRoot`/`forRootAsync` now accept `guards: Array<Type<CanActivate> | CanActivate>` fronting the console's controllers, plus `imports` resolving a class guard's own dependencies.
+
+  This closes the auth seam for hosts with header-only auth: a full-page navigation to the dashboard carries no `Authorization` header, so there was previously no way to hang a cookie/session guard on the page itself. Pass the SAME `guards` (and `imports`) to both modules — they're independent options in separate packages. On core, `guards` **appends** to (never replaces) the existing `TelescopeGuard` gate (`authorizer` / `dashboardAuth` / dev-open-prod-closed default); on `-ui`, `TelescopeUiController` had no guard of its own, so it's a plain replace. See the new "Securing the console with your own guards" docs section.
+
 ## 1.15.0
 
 ### Minor Changes

package/dist/server/telescope-ui.module.d.ts

@@ -1,4 +1,5 @@
-import { type DynamicModule, type InjectionToken, type OptionalFactoryDependency } from '@nestjs/common';
+import 'reflect-metadata';
+import { type CanActivate, type DynamicModule, type InjectionToken, type OptionalFactoryDependency, type Type } from '@nestjs/common';
 import { type TelescopeUiModuleOptions } from './telescope-ui.options.js';
 export declare class TelescopeUiModule {
     static forRoot(options?: TelescopeUiModuleOptions): DynamicModule;
@@ -13,6 +14,15 @@ export declare class TelescopeUiModule {
          * `'telescope'` and must match the core module's path.
          */
         path?: string;
+        /**
+         * Guard classes (or instances) fronting the dashboard's page/asset
+         * controller. Must be passed HERE (not inside the async-resolved options)
+         * because guard stamping happens at module-build time, synchronously —
+         * the SAME constraint as `path` above. See
+         * {@link TelescopeUiModuleOptions.guards}. A class guard's dependencies
+         * resolve from `imports` above.
+         */
+        guards?: Array<Type<CanActivate> | CanActivate>;
     }): DynamicModule;
 }
 //# sourceMappingURL=telescope-ui.module.d.ts.map

package/dist/server/telescope-ui.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telescope-ui.module.d.ts","sourceRoot":"","sources":["../../src/server/telescope-ui.module.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,yBAAyB,EAC/B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAwB,KAAK,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAEhG,qBACa,iBAAiB;IAC5B,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,wBAA6B,GAAG,aAAa;IASrE,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE;QAC1B,UAAU,EAAE,CACV,GAAG,IAAI,EAAE,OAAO,EAAE,KACf,OAAO,CAAC,wBAAwB,CAAC,GAAG,wBAAwB,CAAC;QAClE,MAAM,CAAC,EAAE,CAAC,cAAc,GAAG,yBAAyB,CAAC,EAAE,CAAC;QACxD,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;QACnC;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,aAAa;CAuBlB"}
+{"version":3,"file":"telescope-ui.module.d.ts","sourceRoot":"","sources":["../../src/server/telescope-ui.module.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,yBAAyB,EAC9B,KAAK,IAAI,EACV,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAwB,KAAK,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAgChG,qBACa,iBAAiB;IAC5B,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,wBAA6B,GAAG,aAAa;IAerE,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE;QAC1B,UAAU,EAAE,CACV,GAAG,IAAI,EAAE,OAAO,EAAE,KACf,OAAO,CAAC,wBAAwB,CAAC,GAAG,wBAAwB,CAAC;QAClE,MAAM,CAAC,EAAE,CAAC,cAAc,GAAG,yBAAyB,CAAC,EAAE,CAAC;QACxD,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;QACnC;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;QACd;;;;;;;WAOG;QACH,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC,CAAC;KACjD,GAAG,aAAa;CA0BlB"}

package/dist/server/telescope-ui.module.js

@@ -5,26 +5,60 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var TelescopeUiModule_1;
+import 'reflect-metadata';
 import { dynamicController, normalizeTelescopePath } from '@dudousxd/nestjs-telescope';
 import { Module, } from '@nestjs/common';
 import { TelescopeUiController } from './telescope-ui.controller.js';
 import { TELESCOPE_UI_OPTIONS } from './telescope-ui.options.js';
+/**
+ * `@nestjs/common`'s own `GUARDS_METADATA` key, INLINED rather than deep-imported
+ * from '@nestjs/common/constants' — that subpath has no extension and a strict
+ * ESM resolver 404s on it (same convention used by core's `TelescopeModule` and
+ * `@dudousxd/nestjs-agent`'s `agent-dashboard.module.ts`). A drift spec asserts
+ * this literal stays byte-identical to the real constant.
+ */
+const GUARDS_METADATA = '__guards__';
+/** Narrows a `guards` entry to a class (constructor), not an already-built instance. */
+function isGuardClass(guard) {
+    return typeof guard === 'function';
+}
+/**
+ * Stamp host guards onto the dashboard's page/asset controller. `TelescopeUiController`
+ * carries no guard of its own, so — unlike core's `stampGuards` — there is nothing to
+ * preserve: this is a plain REPLACE of whatever (nothing) was there before. A no-op
+ * when `guards` is omitted/empty, leaving the controller unguarded exactly as before.
+ */
+function stampGuards(guards, ...controllers) {
+    if (guards === undefined || guards.length === 0)
+        return;
+    for (const controller of controllers) {
+        Reflect.defineMetadata(GUARDS_METADATA, guards, controller);
+    }
+}
 let TelescopeUiModule = TelescopeUiModule_1 = class TelescopeUiModule {
     static forRoot(options = {}) {
         const path = normalizeTelescopePath(options.path);
+        const uiController = dynamicController(TelescopeUiController, path);
+        stampGuards(options.guards, uiController);
         return {
             module: TelescopeUiModule_1,
-            controllers: [dynamicController(TelescopeUiController, path)],
-            providers: [{ provide: TELESCOPE_UI_OPTIONS, useValue: options }],
+            imports: options.imports ?? [],
+            controllers: [uiController],
+            providers: [
+                { provide: TELESCOPE_UI_OPTIONS, useValue: options },
+                ...(options.guards ?? []).filter(isGuardClass),
+            ],
         };
     }
     static forRootAsync(config) {
         const path = normalizeTelescopePath(config.path);
+        const uiController = dynamicController(TelescopeUiController, path);
+        stampGuards(config.guards, uiController);
         const { useFactory } = config;
         return {
             module: TelescopeUiModule_1,
             imports: config.imports ?? [],
-            controllers: [dynamicController(TelescopeUiController, path)],
+            controllers: [uiController],
             providers: [
                 {
                     provide: TELESCOPE_UI_OPTIONS,
@@ -38,6 +72,7 @@ let TelescopeUiModule = TelescopeUiModule_1 = class TelescopeUiModule {
                     }),
                     inject: config.inject ?? [],
                 },
+                ...(config.guards ?? []).filter(isGuardClass),
             ],
         };
     }

package/dist/server/telescope-ui.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"telescope-ui.module.js","sourceRoot":"","sources":["../../src/server/telescope-ui.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,EAGL,MAAM,GAEP,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAiC,MAAM,2BAA2B,CAAC;AAGzF,IAAM,iBAAiB,yBAAvB,MAAM,iBAAiB;IAC5B,MAAM,CAAC,OAAO,CAAC,UAAoC,EAAE;QACnD,MAAM,IAAI,GAAG,sBAAsB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO;YACL,MAAM,EAAE,mBAAiB;YACzB,WAAW,EAAE,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;YAC7D,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;SAClE,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,MAanB;QACC,MAAM,IAAI,GAAG,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;QAC9B,OAAO;YACL,MAAM,EAAE,mBAAiB;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;YAC7B,WAAW,EAAE,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;YAC7D,SAAS,EAAE;gBACT;oBACE,OAAO,EAAE,oBAAoB;oBAC7B,wEAAwE;oBACxE,sEAAsE;oBACtE,iEAAiE;oBACjE,+DAA+D;oBAC/D,UAAU,EAAE,KAAK,EAAE,GAAG,IAAe,EAAqC,EAAE,CAAC,CAAC;wBAC5E,GAAG,CAAC,MAAM,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;wBAC9B,IAAI;qBACL,CAAC;oBACF,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;iBAC5B;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AA9CY,iBAAiB;IAD7B,MAAM,CAAC,EAAE,CAAC;GACE,iBAAiB,CA8C7B"}
+{"version":3,"file":"telescope-ui.module.js","sourceRoot":"","sources":["../../src/server/telescope-ui.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,EAIL,MAAM,GAGP,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAiC,MAAM,2BAA2B,CAAC;AAEhG;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,YAAY,CAAC;AAErC,wFAAwF;AACxF,SAAS,YAAY,CAAC,KAAsC;IAC1D,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAClB,MAA0D,EAC1D,GAAG,WAAmB;IAEtB,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACxD,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,OAAO,CAAC,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAGM,IAAM,iBAAiB,yBAAvB,MAAM,iBAAiB;IAC5B,MAAM,CAAC,OAAO,CAAC,UAAoC,EAAE;QACnD,MAAM,IAAI,GAAG,sBAAsB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,iBAAiB,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;QACpE,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC1C,OAAO;YACL,MAAM,EAAE,mBAAiB;YACzB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE;YAC9B,WAAW,EAAE,CAAC,YAAY,CAAC;YAC3B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,OAAO,EAAE;gBACpD,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;aAC/C;SACF,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,MAsBnB;QACC,MAAM,IAAI,GAAG,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,YAAY,GAAG,iBAAiB,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;QACpE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACzC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;QAC9B,OAAO;YACL,MAAM,EAAE,mBAAiB;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;YAC7B,WAAW,EAAE,CAAC,YAAY,CAAC;YAC3B,SAAS,EAAE;gBACT;oBACE,OAAO,EAAE,oBAAoB;oBAC7B,wEAAwE;oBACxE,sEAAsE;oBACtE,iEAAiE;oBACjE,+DAA+D;oBAC/D,UAAU,EAAE,KAAK,EAAE,GAAG,IAAe,EAAqC,EAAE,CAAC,CAAC;wBAC5E,GAAG,CAAC,MAAM,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;wBAC9B,IAAI;qBACL,CAAC;oBACF,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;iBAC5B;gBACD,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;aAC9C;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AAhEY,iBAAiB;IAD7B,MAAM,CAAC,EAAE,CAAC;GACE,iBAAiB,CAgE7B"}

package/dist/server/telescope-ui.options.d.ts

@@ -1,3 +1,4 @@
+import type { CanActivate, DynamicModule, Type } from '@nestjs/common';
 export declare const TELESCOPE_UI_OPTIONS: unique symbol;
 export interface TelescopeUiModuleOptions {
     /** Directory of the built SPA (index.html + assets/). Defaults to the bundled dist/spa. */
@@ -8,5 +9,32 @@ export interface TelescopeUiModuleOptions {
      * before. Must match the core `TelescopeModule.forRoot({ path })`.
      */
     path?: string;
+    /**
+     * Guard classes (or already-instantiated `CanActivate`s) fronting the
+     * dashboard's page + static-asset controller (`TelescopeUiController`) — the
+     * full-page HTML shell and its hashed JS/CSS bundle. See
+     * `TelescopeModuleOptions.guards` (`@dudousxd/nestjs-telescope`) for the full
+     * rationale: full-page navigations carry no `Authorization` header, so a
+     * header-only auth scheme can't gate this controller — a guard here must be
+     * able to authenticate from a COOKIE (falling back to a header for XHR/fetch
+     * callers if useful). See the "Securing the console" guide.
+     *
+     * These two `guards` options are INDEPENDENT — different package, different
+     * module — so pass the SAME `guards` (and matching `imports`) to BOTH
+     * `TelescopeModule.forRoot` (core) and this module. Setting it here alone
+     * still leaves the API reachable; setting it only on core still leaves the
+     * page itself (HTML shell + assets) reachable by an anonymous browser.
+     *
+     * Unlike core's console API controllers, `TelescopeUiController` ships with
+     * NO guard of its own by default (the page + assets are considered public —
+     * no data lives there), so setting `guards` here is a plain REPLACE: the
+     * listed guard(s) become the controller's entire gate.
+     */
+    guards?: Array<Type<CanActivate> | CanActivate>;
+    /**
+     * Extra `imports` merged into `TelescopeUiModule`'s own dynamic module — the
+     * DI resolution path for a class passed to {@link guards}.
+     */
+    imports?: DynamicModule['imports'];
 }
 //# sourceMappingURL=telescope-ui.options.d.ts.map

package/dist/server/telescope-ui.options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telescope-ui.options.d.ts","sourceRoot":"","sources":["../../src/server/telescope-ui.options.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE,MAAM,WAAW,wBAAwB;IACvC,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"telescope-ui.options.d.ts","sourceRoot":"","sources":["../../src/server/telescope-ui.options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEvE,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE,MAAM,WAAW,wBAAwB;IACvC,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC,CAAC;IAChD;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CACpC"}

package/dist/server/telescope-ui.options.js.map

@@ -1 +1 @@
-{"version":3,"file":"telescope-ui.options.js","sourceRoot":"","sources":["../../src/server/telescope-ui.options.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC"}
+{"version":3,"file":"telescope-ui.options.js","sourceRoot":"","sources":["../../src/server/telescope-ui.options.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-telescope-ui",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Bundled dashboard + composable React components for @dudousxd/nestjs-telescope.",
   "license": "MIT",
   "repository": {
@@ -42,7 +42,7 @@
   "peerDependencies": {
     "@nestjs/common": ">=11.0.0",
     "@nestjs/core": ">=11.0.0",
-    "@dudousxd/nestjs-telescope": "^1.18.0"
+    "@dudousxd/nestjs-telescope": "^1.19.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -81,7 +81,7 @@
     "typescript": "^5.4.0",
     "vite": "^5.4.0",
     "vitest": "^3.0.0",
-    "@dudousxd/nestjs-telescope": "1.18.0"
+    "@dudousxd/nestjs-telescope": "1.19.0"
   },
   "engines": {
     "node": ">=20"