@dudousxd/nestjs-catalog-dashboard 0.7.2 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -71,13 +71,34 @@ type UnauthenticatedPageHook = (context: UnauthenticatedPageContext) => void | P
71
71
  type AuthMode = 'session' | 'login';
72
72
  /**
73
73
  * Author-facing `dashboardAuth` option on `CatalogDashboardModule.forRoot`/`forRootAsync`. Gates
74
- * BOTH the SPA (a full-page navigation redirected to a server-rendered login page) and the JSON
75
- * API (a plain `401`) behind a signed session cookie, mirroring `@dudousxd/nestjs-telescope`'s
76
- * `dashboardAuth` mechanism (same HMAC-SHA256 cookie, same fail-closed validation). Two ways to
77
- * mint that cookie: Mode A (`session`) — the host frontend, already carrying its own auth, POSTs
78
- * to `<basePath>/session` and the host hook decides; or Mode B (`login`) — the built-in,
79
- * dependency-free server-rendered login page (`GET <basePath>/login`). At least one of the two is
80
- * required so an un-mintable gate is a boot error, not a silently-open (or silently-stuck) console.
74
+ * the SPA — a full-page navigation, redirected to a server-rendered login page — behind a signed
75
+ * session cookie, mirroring `@dudousxd/nestjs-telescope`'s `dashboardAuth` mechanism (same
76
+ * HMAC-SHA256 cookie, same fail-closed validation). Two ways to mint that cookie: Mode A
77
+ * (`session`) — the host frontend, already carrying its own auth, POSTs to `<basePath>/session`
78
+ * and the host hook decides; or Mode B (`login`) — the built-in, dependency-free server-rendered
79
+ * login page (`GET <basePath>/login`). At least one of the two is required so an un-mintable gate
80
+ * is a boot error, not a silently-open (or silently-stuck) console.
81
+ *
82
+ * IT DOES NOT GATE THE JSON API, AND CANNOT
83
+ * -----------------------------------------
84
+ * This said "gates BOTH the SPA and the JSON API (a plain 401)" for as long as it existed, and
85
+ * that was never true: this module registers `CatalogUiController` and `CatalogAuthController` and
86
+ * nothing else — there is no API controller here to guard. The catalog's HTTP surface is mounted
87
+ * by `CatalogModule`/`CatalogPipelineModule`, behind whatever the host already put in front of it,
88
+ * and a second guarded copy proxied through this console is the thing this package deliberately
89
+ * does not ship (see `CatalogDashboardOptions.apiPath`). A host that configured `auth` and stopped
90
+ * reading here therefore left rows, ad-hoc SQL and connector runs on whatever was guarding the API
91
+ * before — which was the honest state of things, described backwards at the one place a host
92
+ * configures auth.
93
+ *
94
+ * Closing it is one of two host-side moves, and the package ships both:
95
+ *
96
+ * - `readCatalogConsoleSession(auth, request)` — verify the console's cookie inside the host's
97
+ * OWN API guard, alongside its own tokens. The right shape when the host's guard already
98
+ * exists and needs the identity, not merely a yes/no. See `server/index.ts`.
99
+ * - `CatalogApiSessionGuard` — the same check as a ready-made guard the host applies to its API
100
+ * controllers with `@UseGuards`. The right shape when a console session IS the credential for
101
+ * that surface. See `catalog-session.guard.ts` for how to apply it.
81
102
  */
82
103
  interface DashboardAuthOptions {
83
104
  /** REQUIRED HMAC-SHA256 signing key. Missing/empty => boot error (fail closed). */
@@ -270,12 +291,55 @@ declare class CatalogUiSessionGuard implements CanActivate {
270
291
  private denyUnauthenticated;
271
292
  }
272
293
  /**
273
- * Gates `CatalogApiController` (the JSON API the SPA fetches) on a valid `dashboardAuth` session
274
- * cookie. A no-op (always `true`) when `dashboardAuth` was not configured. Missing/invalid/expired
275
- * session => a plain `401` (the API is called via `fetch`, never a browser navigation, so a
276
- * redirect would just fail the request anyway — the caller reads the status code, not HTML).
294
+ * The console session as a guard a HOST applies to ITS OWN API controllers.
295
+ *
296
+ * It is bound to nothing in this package, and that is not an oversight to be tidied away — it is
297
+ * the only shape this guard can have. There is no JSON API here to guard: this module registers
298
+ * the SPA shell and the session endpoints, and the catalog's HTTP surface is mounted by
299
+ * `CatalogModule`/`CatalogPipelineModule` in the host's own tree, deliberately un-proxied (see
300
+ * `CatalogDashboardOptions.apiPath`). A guard cannot be stamped from here onto a controller this
301
+ * package never sees.
302
+ *
303
+ * (Its docblock used to claim it gated `CatalogApiController`, a class that exists nowhere in the
304
+ * repo, and cited a `catalog-client.ts` that does not either. Both were written for a proxying
305
+ * design this package does not have.)
306
+ *
307
+ * WHEN TO REACH FOR IT
308
+ * --------------------
309
+ * The gap it fills is real and specific: the console SPA fetches the catalog API from a browser,
310
+ * carrying this cookie and no bearer token, so a host whose API guard understands only its own
311
+ * tokens answers 401 to every screen while the shell loads perfectly. Two ways out, and the
312
+ * difference is whether the host has a guard already:
313
+ *
314
+ * - Its own guard, needing the identity as well as the verdict: inject `DASHBOARD_AUTH` and call
315
+ * `readCatalogConsoleSession` — see `catalog-console-session.integration.spec.ts`, written from
316
+ * the host's side.
317
+ * - No guard of its own, or one for which a console session simply IS the credential: apply this
318
+ * one. Import `CatalogDashboardModule` in the module that owns those controllers — that is what
319
+ * puts `DASHBOARD_AUTH` in reach — then either stamp it per controller or hand it to the whole
320
+ * application:
321
+ *
322
+ * ```ts
323
+ * @Module({ imports: [CatalogDashboardModule.forRoot({ auth }), CatalogModule.forRoot(...)] })
324
+ * class AppModule {}
325
+ *
326
+ * @UseGuards(CatalogApiSessionGuard) // per controller, or…
327
+ * app.useGlobalGuards(app.get(CatalogApiSessionGuard)); // …the whole surface
328
+ * ```
329
+ *
330
+ * The second line is why the module provides and exports this class as well as the barrel
331
+ * re-exporting it: the decorator form resolves without that (Nest builds a class enhancer from
332
+ * the declaring module's injector), and `app.get` does not.
333
+ *
334
+ * Missing/invalid/expired session => a plain `401` (the API is called via `fetch`, never a browser
335
+ * navigation, so the redirect `CatalogUiSessionGuard` throws would just fail the request — the
336
+ * caller reads a status code, not HTML). A no-op (always `true`) when `dashboardAuth` was not
337
+ * configured, matching `CatalogUiSessionGuard`: a host that left the console open has not asked
338
+ * for its API to be shut by this.
277
339
  *
278
- * Mount-level and role-agnostic, same as `CatalogUiSessionGuard` above.
340
+ * Mount-level and role-agnostic, same as `CatalogUiSessionGuard` above: it only ever answers "is
341
+ * there a valid console session", never who may do what with it. Authorisation on the catalog's
342
+ * surface is `CatalogModule`'s scopes, which this cannot and must not stand in for.
279
343
  */
280
344
  declare class CatalogApiSessionGuard implements CanActivate {
281
345
  private readonly auth;
@@ -283,9 +347,12 @@ declare class CatalogApiSessionGuard implements CanActivate {
283
347
  canActivate(context: ExecutionContext): Promise<boolean>;
284
348
  /**
285
349
  * A bare 401 body carrying `{ auth: { modes } }` — mirrors `@dudousxd/nestjs-telescope`'s
286
- * dashboardAuth 401. The API is fetched (never navigated), so this is the ONLY way the console
287
- * SPA (`catalog-client.ts`) learns which auth surface to send the operator to on a mid-session
288
- * 401; `CatalogUiSessionGuard`'s redirect/session-required exceptions above don't reach it.
350
+ * dashboardAuth 401. The API is fetched, never navigated, so the redirect and session-required
351
+ * exceptions `CatalogUiSessionGuard` throws are useless here: what reaches the SPA is a status
352
+ * code and a body. `modes` is in that body so the console can send an operator to the right
353
+ * place on a mid-session 401 — the built-in login page under Mode B, the host's launcher under
354
+ * Mode A — rather than guessing at one of them. `client/transport.ts` surfaces the raw body on
355
+ * `UnauthorizedError`, which is what puts it in reach.
289
356
  */
290
357
  private unauthorized;
291
358
  }
@@ -71,13 +71,34 @@ type UnauthenticatedPageHook = (context: UnauthenticatedPageContext) => void | P
71
71
  type AuthMode = 'session' | 'login';
72
72
  /**
73
73
  * Author-facing `dashboardAuth` option on `CatalogDashboardModule.forRoot`/`forRootAsync`. Gates
74
- * BOTH the SPA (a full-page navigation redirected to a server-rendered login page) and the JSON
75
- * API (a plain `401`) behind a signed session cookie, mirroring `@dudousxd/nestjs-telescope`'s
76
- * `dashboardAuth` mechanism (same HMAC-SHA256 cookie, same fail-closed validation). Two ways to
77
- * mint that cookie: Mode A (`session`) — the host frontend, already carrying its own auth, POSTs
78
- * to `<basePath>/session` and the host hook decides; or Mode B (`login`) — the built-in,
79
- * dependency-free server-rendered login page (`GET <basePath>/login`). At least one of the two is
80
- * required so an un-mintable gate is a boot error, not a silently-open (or silently-stuck) console.
74
+ * the SPA — a full-page navigation, redirected to a server-rendered login page — behind a signed
75
+ * session cookie, mirroring `@dudousxd/nestjs-telescope`'s `dashboardAuth` mechanism (same
76
+ * HMAC-SHA256 cookie, same fail-closed validation). Two ways to mint that cookie: Mode A
77
+ * (`session`) — the host frontend, already carrying its own auth, POSTs to `<basePath>/session`
78
+ * and the host hook decides; or Mode B (`login`) — the built-in, dependency-free server-rendered
79
+ * login page (`GET <basePath>/login`). At least one of the two is required so an un-mintable gate
80
+ * is a boot error, not a silently-open (or silently-stuck) console.
81
+ *
82
+ * IT DOES NOT GATE THE JSON API, AND CANNOT
83
+ * -----------------------------------------
84
+ * This said "gates BOTH the SPA and the JSON API (a plain 401)" for as long as it existed, and
85
+ * that was never true: this module registers `CatalogUiController` and `CatalogAuthController` and
86
+ * nothing else — there is no API controller here to guard. The catalog's HTTP surface is mounted
87
+ * by `CatalogModule`/`CatalogPipelineModule`, behind whatever the host already put in front of it,
88
+ * and a second guarded copy proxied through this console is the thing this package deliberately
89
+ * does not ship (see `CatalogDashboardOptions.apiPath`). A host that configured `auth` and stopped
90
+ * reading here therefore left rows, ad-hoc SQL and connector runs on whatever was guarding the API
91
+ * before — which was the honest state of things, described backwards at the one place a host
92
+ * configures auth.
93
+ *
94
+ * Closing it is one of two host-side moves, and the package ships both:
95
+ *
96
+ * - `readCatalogConsoleSession(auth, request)` — verify the console's cookie inside the host's
97
+ * OWN API guard, alongside its own tokens. The right shape when the host's guard already
98
+ * exists and needs the identity, not merely a yes/no. See `server/index.ts`.
99
+ * - `CatalogApiSessionGuard` — the same check as a ready-made guard the host applies to its API
100
+ * controllers with `@UseGuards`. The right shape when a console session IS the credential for
101
+ * that surface. See `catalog-session.guard.ts` for how to apply it.
81
102
  */
82
103
  interface DashboardAuthOptions {
83
104
  /** REQUIRED HMAC-SHA256 signing key. Missing/empty => boot error (fail closed). */
@@ -270,12 +291,55 @@ declare class CatalogUiSessionGuard implements CanActivate {
270
291
  private denyUnauthenticated;
271
292
  }
272
293
  /**
273
- * Gates `CatalogApiController` (the JSON API the SPA fetches) on a valid `dashboardAuth` session
274
- * cookie. A no-op (always `true`) when `dashboardAuth` was not configured. Missing/invalid/expired
275
- * session => a plain `401` (the API is called via `fetch`, never a browser navigation, so a
276
- * redirect would just fail the request anyway — the caller reads the status code, not HTML).
294
+ * The console session as a guard a HOST applies to ITS OWN API controllers.
295
+ *
296
+ * It is bound to nothing in this package, and that is not an oversight to be tidied away — it is
297
+ * the only shape this guard can have. There is no JSON API here to guard: this module registers
298
+ * the SPA shell and the session endpoints, and the catalog's HTTP surface is mounted by
299
+ * `CatalogModule`/`CatalogPipelineModule` in the host's own tree, deliberately un-proxied (see
300
+ * `CatalogDashboardOptions.apiPath`). A guard cannot be stamped from here onto a controller this
301
+ * package never sees.
302
+ *
303
+ * (Its docblock used to claim it gated `CatalogApiController`, a class that exists nowhere in the
304
+ * repo, and cited a `catalog-client.ts` that does not either. Both were written for a proxying
305
+ * design this package does not have.)
306
+ *
307
+ * WHEN TO REACH FOR IT
308
+ * --------------------
309
+ * The gap it fills is real and specific: the console SPA fetches the catalog API from a browser,
310
+ * carrying this cookie and no bearer token, so a host whose API guard understands only its own
311
+ * tokens answers 401 to every screen while the shell loads perfectly. Two ways out, and the
312
+ * difference is whether the host has a guard already:
313
+ *
314
+ * - Its own guard, needing the identity as well as the verdict: inject `DASHBOARD_AUTH` and call
315
+ * `readCatalogConsoleSession` — see `catalog-console-session.integration.spec.ts`, written from
316
+ * the host's side.
317
+ * - No guard of its own, or one for which a console session simply IS the credential: apply this
318
+ * one. Import `CatalogDashboardModule` in the module that owns those controllers — that is what
319
+ * puts `DASHBOARD_AUTH` in reach — then either stamp it per controller or hand it to the whole
320
+ * application:
321
+ *
322
+ * ```ts
323
+ * @Module({ imports: [CatalogDashboardModule.forRoot({ auth }), CatalogModule.forRoot(...)] })
324
+ * class AppModule {}
325
+ *
326
+ * @UseGuards(CatalogApiSessionGuard) // per controller, or…
327
+ * app.useGlobalGuards(app.get(CatalogApiSessionGuard)); // …the whole surface
328
+ * ```
329
+ *
330
+ * The second line is why the module provides and exports this class as well as the barrel
331
+ * re-exporting it: the decorator form resolves without that (Nest builds a class enhancer from
332
+ * the declaring module's injector), and `app.get` does not.
333
+ *
334
+ * Missing/invalid/expired session => a plain `401` (the API is called via `fetch`, never a browser
335
+ * navigation, so the redirect `CatalogUiSessionGuard` throws would just fail the request — the
336
+ * caller reads a status code, not HTML). A no-op (always `true`) when `dashboardAuth` was not
337
+ * configured, matching `CatalogUiSessionGuard`: a host that left the console open has not asked
338
+ * for its API to be shut by this.
277
339
  *
278
- * Mount-level and role-agnostic, same as `CatalogUiSessionGuard` above.
340
+ * Mount-level and role-agnostic, same as `CatalogUiSessionGuard` above: it only ever answers "is
341
+ * there a valid console session", never who may do what with it. Authorisation on the catalog's
342
+ * surface is `CatalogModule`'s scopes, which this cannot and must not stand in for.
279
343
  */
280
344
  declare class CatalogApiSessionGuard implements CanActivate {
281
345
  private readonly auth;
@@ -283,9 +347,12 @@ declare class CatalogApiSessionGuard implements CanActivate {
283
347
  canActivate(context: ExecutionContext): Promise<boolean>;
284
348
  /**
285
349
  * A bare 401 body carrying `{ auth: { modes } }` — mirrors `@dudousxd/nestjs-telescope`'s
286
- * dashboardAuth 401. The API is fetched (never navigated), so this is the ONLY way the console
287
- * SPA (`catalog-client.ts`) learns which auth surface to send the operator to on a mid-session
288
- * 401; `CatalogUiSessionGuard`'s redirect/session-required exceptions above don't reach it.
350
+ * dashboardAuth 401. The API is fetched, never navigated, so the redirect and session-required
351
+ * exceptions `CatalogUiSessionGuard` throws are useless here: what reaches the SPA is a status
352
+ * code and a body. `modes` is in that body so the console can send an operator to the right
353
+ * place on a mid-session 401 — the built-in login page under Mode B, the host's launcher under
354
+ * Mode A — rather than guessing at one of them. `client/transport.ts` surfaces the raw body on
355
+ * `UnauthorizedError`, which is what puts it in reach.
289
356
  */
290
357
  private unauthorized;
291
358
  }
@@ -849,8 +849,20 @@ var CatalogAuthController = class _CatalogAuthController {
849
849
  }
850
850
  // Plain `GET` (not `POST`): logging out only ever destroys the CALLER's own session, so it's
851
851
  // safe/idempotent from the caller's perspective — a simple `<a href>` (no JS, no CSRF token)
852
- // works. Non-passthrough `@Res()`: this handler owns the response outright (clears the cookie,
853
- // then redirects), so Nest must not also try to send a return value afterwards.
852
+ // works.
853
+ //
854
+ // This is the ONE state-changing GET in the package, and it is where the session cookie's
855
+ // `SameSite=Lax` stops covering us: Lax is sent on a cross-site top-level GET navigation, so a
856
+ // link on another site can reach this route with the cookie attached and sign the visitor out.
857
+ // Taken knowingly. The blast radius is one session belonging to whoever followed the link, there
858
+ // is nothing to read back (the response is a redirect), and the cost of closing it — a POST, and
859
+ // therefore a form and a token on every sign-out control including the plain `<a>` on the
860
+ // session-required page — is paid on every logout to prevent a nuisance. `cookie-header.ts`
861
+ // states what Lax covers and points here for what it does not; this comment is the only place
862
+ // the trade itself is argued.
863
+ //
864
+ // Non-passthrough `@Res()`: this handler owns the response outright (clears the cookie, then
865
+ // redirects), so Nest must not also try to send a return value afterwards.
854
866
  logout(request, response) {
855
867
  clearSessionCookie({
856
868
  request,
@@ -1035,9 +1047,12 @@ var CatalogApiSessionGuard = class {
1035
1047
  }
1036
1048
  /**
1037
1049
  * A bare 401 body carrying `{ auth: { modes } }` — mirrors `@dudousxd/nestjs-telescope`'s
1038
- * dashboardAuth 401. The API is fetched (never navigated), so this is the ONLY way the console
1039
- * SPA (`catalog-client.ts`) learns which auth surface to send the operator to on a mid-session
1040
- * 401; `CatalogUiSessionGuard`'s redirect/session-required exceptions above don't reach it.
1050
+ * dashboardAuth 401. The API is fetched, never navigated, so the redirect and session-required
1051
+ * exceptions `CatalogUiSessionGuard` throws are useless here: what reaches the SPA is a status
1052
+ * code and a body. `modes` is in that body so the console can send an operator to the right
1053
+ * place on a mid-session 401 — the built-in login page under Mode B, the host's launcher under
1054
+ * Mode A — rather than guessing at one of them. `client/transport.ts` surfaces the raw body on
1055
+ * `UnauthorizedError`, which is what puts it in reach.
1041
1056
  */
1042
1057
  unauthorized(auth) {
1043
1058
  return new UnauthorizedException2({
@@ -1130,7 +1145,21 @@ function build(options, auth) {
1130
1145
  auth,
1131
1146
  // Constructed by Nest, so it must be declared here — a guard stamped by
1132
1147
  // `UseGuards` is still resolved from the declaring module's injector.
1133
- CatalogUiSessionGuard
1148
+ CatalogUiSessionGuard,
1149
+ // Not stamped on anything here, and it cannot be: it guards the catalog's
1150
+ // JSON API, which this package deliberately does not mount (see `apiPath`).
1151
+ //
1152
+ // Declared so it can be RESOLVED, which is a narrower claim than it looks.
1153
+ // `@UseGuards(CatalogApiSessionGuard)` on a host's own controller already
1154
+ // worked without this line — Nest instantiates a class enhancer from the
1155
+ // declaring module's injector, and `DASHBOARD_AUTH` is exported above, so
1156
+ // the dependency is in reach. What did NOT work is
1157
+ // `moduleRef.get(CatalogApiSessionGuard)`, which is how a host reaches an
1158
+ // instance to hand to `app.useGlobalGuards(...)` — the way you guard a
1159
+ // whole API surface rather than remembering every controller on it. That
1160
+ // threw "Nest could not find CatalogApiSessionGuard element", against a
1161
+ // class exported from this package's barrel and documented as the answer.
1162
+ CatalogApiSessionGuard
1134
1163
  ];
1135
1164
  return {
1136
1165
  module: CatalogDashboardModule,