@dudousxd/nestjs-catalog-dashboard 0.8.0 → 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.
- package/dist/server/index.cjs +35 -6
- package/dist/server/index.cjs.map +1 -1
- package/dist/server/index.d.cts +82 -15
- package/dist/server/index.d.ts +82 -15
- package/dist/server/index.js +35 -6
- package/dist/server/index.js.map +1 -1
- package/dist/spa/assets/index-CoGwllLM.css +1 -0
- package/dist/spa/assets/{index-Dm46fQcn.js → index-X45aTJmr.js} +198 -188
- package/dist/spa/index.html +2 -2
- package/package.json +2 -2
- package/dist/spa/assets/index-BrkRcRNu.css +0 -1
package/dist/server/index.d.cts
CHANGED
|
@@ -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
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
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
|
-
*
|
|
274
|
-
*
|
|
275
|
-
*
|
|
276
|
-
*
|
|
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
|
|
287
|
-
*
|
|
288
|
-
*
|
|
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
|
}
|
package/dist/server/index.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
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
|
-
*
|
|
274
|
-
*
|
|
275
|
-
*
|
|
276
|
-
*
|
|
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
|
|
287
|
-
*
|
|
288
|
-
*
|
|
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
|
}
|
package/dist/server/index.js
CHANGED
|
@@ -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.
|
|
853
|
-
//
|
|
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
|
|
1039
|
-
*
|
|
1040
|
-
*
|
|
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,
|