@dudousxd/nestjs-catalog 0.5.0 → 0.6.0

package/README.md

@@ -124,6 +124,169 @@ is a way to create one your IdP has never heard of.
 The routes mount at `accessPath`, a sibling of `path` by default — `api/catalog`
 gives `api/access`, which is the shape the React screens build.
 
+## Embed a chart in someone else's application
+
+A saved query or a dashboard can be fetched by another application and drawn in
+its own UI, without that application knowing anything about this catalog's SQL,
+its schema or its console.
+
+| Method | Path | What it does |
+|---|---|---|
+| `GET` | `/catalog/embed` | What this caller may embed |
+| `GET` | `/catalog/embed/charts/:id` | One shared saved query, run and rendered |
+| `GET` | `/catalog/embed/dashboards/:id` | A shared dashboard, every card resolved |
+
+### What comes back is rows, not SQL
+
+`GET /catalog/embed/charts/:id` runs the saved query and hands back the result
+already shaped for drawing:
+
+```jsonc
+{
+  "id": "9a1c0e2e-…",
+  "title": "Vehicles by status",
+  "description": "Current fleet, grouped by operational status.",
+  "visualization": { "kind": "bar", "labelColumn": "status", "valueColumns": ["vehicles"] },
+  "columns": ["status", "vehicles"],
+  "rows": [
+    { "status": "Operational",    "vehicles": 412 },
+    { "status": "In maintenance", "vehicles": 57 },
+    { "status": "Deadlined",      "vehicles": 9 }
+  ],
+  "rowCount": 3,
+  "cached": true,
+  "generatedAt": "2026-02-11T09:15:04.221Z"
+}
+```
+
+That it is rendered rows rather than the statement behind them is the point of
+the endpoint. **Handing back SQL would make every consumer a second
+implementation of the console** — each one parsing this catalog's query
+language, each one deciding what a `bar` means, each one drifting. A consumer
+here needs a chart library and a `fetch`.
+
+`title` and `visualization` come from the saved query itself. `layout` appears
+only when the chart was reached through a dashboard, carrying that card's
+`width` (1–4) and `position`; it is a hint the consumer may ignore, and it is
+absent from `GET /catalog/embed/charts/:id`, which knows nothing about any
+board.
+
+`GET /catalog/embed/dashboards/:id` is the same shape one level up — `id`,
+`name`, `description`, `generatedAt`, and `charts`, each entry exactly the
+object above, ordered by card position. Cards are resolved **sequentially**, not
+in parallel: every one is a database query, and a shared dashboard is precisely
+the thing a consumer will poll on a timer. A card whose query is unshared,
+missing or failing is left out rather than failing the whole board — one bad
+card should not blank a page, and a consumer should therefore not assume
+`charts.length` matches the card count it saw at discovery.
+
+`GET /catalog/embed` is that discovery endpoint, so a consuming frontend can
+list what it is allowed to render instead of being told the ids out of band:
+
+```jsonc
+{
+  "dashboards": [{ "id": "…", "name": "Fleet readiness", "description": "…", "charts": 4 }],
+  "charts":     [{ "id": "…", "name": "Vehicles by status", "description": "…", "kind": "bar" }]
+}
+```
+
+Two things about freshness. `cached` says the rows came from the query cache
+rather than the database — the TTL is the one the query was saved with, per
+query, and zero means never cached. `generatedAt` is when *this response* was
+assembled, so on a cached hit it is not the age of the rows; `cached` is the
+field that tells you which you are looking at. The cache key includes the
+catalog's version, so a curation edit that renames a column cannot serve a
+result computed under the old name.
+
+One limit worth knowing before you build against it: rows are capped by
+`maxQueryRows` (default 1000) like any other query here, and the embed payload
+carries no "truncated" flag, so a chart that hit the cap looks like a complete
+result.
+
+### Only what has been shared, and only ever explicitly
+
+The two fetches serve a saved query or dashboard whose `shared` flag is set and
+answer **403** otherwise; discovery lists only what carries the flag. An unshared
+chart says so by name and tells you to mark it shared in the console, because the
+fix is a decision somebody makes there rather than a configuration change.
+
+`shared` is never inferred from the SQL. A saved query can join five relations,
+so working out "which types does this touch" means parsing the statement, and a
+permission that depends on a parser widens silently the first time the parser
+meets a query it did not expect. Marking something shared is an act a person
+performed, and it shows up in the audit trail as one.
+
+The shipped console exposes the toggle on a saved query; the flag on a dashboard
+is `shared` on the workspace store's `saveDashboard` / `updateDashboard` input.
+
+### `catalog:embed` is its own scope
+
+An application that draws one chart in its own UI needs nothing else. Giving it
+`catalog:read` to do that hands it every type in the catalog, and that is the
+kind of over-grant nobody revisits. So the embed API has its own scope, and a
+principal can hold it alone:
+
+```ts
+new StaticKeyPrincipalResolver([
+  {
+    key: process.env.SALES_PORTAL_KEY!,
+    id: "sales-portal",
+    displayName: "Sales portal",
+    scopes: ["catalog:embed"], // and nothing else — no reads, no curation
+  },
+]);
+```
+
+That resolver keys on the `x-catalog-key` header by default and is explicitly the
+lesser option — prefer resolving a token against your IdP where there is one.
+`hasScope(principal, "catalog:embed")` is how a guard asks, whichever resolver
+answered; `catalog:admin` implies it, as it implies every scope.
+
+**Declaring a scope is separate from enforcing it.** This library ships no guard,
+for the same reason it ships none for anything else, so `catalog:embed` means
+what the guard you pass to `guards` makes it mean: read `REQUIRED_SCOPES` off the
+handler — `RequireScopes` is what sets it — and check it with `hasScope`. Nothing
+under the `embed` prefix checks a scope by itself.
+
+Note also what the embed path does *not* consult: nothing in it applies a
+principal's `readTypes` or `classifications`. Those are helpers (`mayRead`,
+`maySeeClassification`) for a host's guard to apply at the door, and the saved
+query's SQL runs as written. The `shared` flag is the boundary — so what a query
+selects is what an embedding application sees.
+
+### What every route asks for
+
+Absence of a declaration is itself a declaration — it means "authenticated is
+enough" — so every route on the built-in controller names a scope:
+
+| Routes | Scope |
+| --- | --- |
+| the model and the rows under it: `GET /`, `graph`, `types/:name`, `objects/:name`, `objects/:name/snapshots`, `query/relations` | `catalog:read` |
+| reading the workspace: `workspace/capabilities`, `saved-queries`, `saved-queries/:id`, `saved-queries/:id/run`, `saved-queries/:id/export.csv`, `dashboards`, `dashboards/:id` | `catalog:read` |
+| the trail: `events`, `events/traces`, `events/traces/:id` | `catalog:read` |
+| curation: `PATCH types/:name`, `PATCH types/:name/properties/:property`, `POST reset` | `catalog:curate` |
+| workspace authoring that carries no SQL: `DELETE saved-queries/:id`, `POST`/`PATCH`/`DELETE dashboards` | `catalog:curate` |
+| anything that chooses what SQL runs: `POST query`, `POST saved-queries`, `PATCH saved-queries/:id` | `catalog:admin` |
+| `GET embed`, `embed/dashboards/:id`, `embed/charts/:id` | `catalog:embed` |
+
+Two of those need saying out loud.
+
+**Arbitrary SQL is `catalog:admin` because read-only is not the same as
+bounded.** `catalog:read` is "read object metadata and rows" — rows of a
+catalogued type, through a route that names one. `POST query` is whatever the
+store's read connection can reach, and with the bundled MikroORM store that is
+the catalog's own schema: `SELECT * FROM catalog_principal` returns every
+principal's scopes, grants and `keyHash`. `query/relations` lists only the
+catalogued types, but it is the editor's schema panel, not a restriction on the
+statement. If you want analysts writing SQL without the rest of admin, give the
+read connection a database role that cannot see the `catalog_*` tables and
+publish your own route with your own declaration.
+
+**Running a saved query is only `catalog:read`.** What the admin scope holds back
+is choosing what SQL runs, not seeing a result. Gating execution instead would
+stop an analyst opening a dashboard and would let an unprivileged caller plant a
+statement for a privileged one to run.
+
 ## Build your own endpoints, or use ours
 
 The built-in controller is a convenience, not the interface. Pass

package/dist/access.controller.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAccessController = createAccessController;
 const common_1 = require("@nestjs/common");
 const catalog_access_1 = require("./catalog.access");
+const catalog_route_auth_1 = require("./catalog.route-auth");
 const ROLES = ['viewer', 'curator', 'administrator'];
 function isRole(value) {
     return typeof value === 'string' && ROLES.some((role) => role === value);
@@ -40,6 +41,27 @@ function createAccessController(path, guards, decorators = []) {
             }
             return this.directory;
         }
+        /**
+         * Every route here is `catalog:admin`, and the screen is the reason.
+         *
+         * `listApplications` enumerates each application that can reach the catalog
+         * together with its scopes, its `writeTypes` and its `classifications` —
+         * which is to say, the map of what a stolen credential would be worth and
+         * which one to steal. `upsertPerson` writes into the host's directory and
+         * accepts `role: 'administrator'`, so an unscoped POST here is a way to
+         * grant yourself the scope this endpoint is protecting.
+         *
+         * Nothing weaker fits: `catalog:curate` is documented as editing labels and
+         * units, and reading who may write to the catalog is not a curation act.
+         * The console already hides this screen behind `catalog:admin`; until now
+         * that client-side check was the ONLY check, and a hidden tab is not an
+         * access control — anybody authenticated could call these three paths
+         * directly. `catalog.route-auth.ts` is explicit that a route declaring no
+         * scope means "authenticated is enough", so the absence was not an
+         * oversight the framework would catch. It is caught now: the completeness
+         * sweep in `catalog.route-scopes.integration.spec.ts` reads THIS factory
+         * too, which is what let these three escape it in the first place.
+         */
         principals() {
             return this.require().listApplications();
         }
@@ -72,12 +94,14 @@ function createAccessController(path, guards, decorators = []) {
     };
     __decorate([
         (0, common_1.Get)('principals'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:admin'),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], AccessController.prototype, "principals", null);
     __decorate([
         (0, common_1.Get)('people'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:admin'),
         __param(0, (0, common_1.Query)('search')),
         __param(1, (0, common_1.Query)('limit')),
         __param(2, (0, common_1.Query)('offset')),
@@ -87,6 +111,7 @@ function createAccessController(path, guards, decorators = []) {
     ], AccessController.prototype, "people", null);
     __decorate([
         (0, common_1.Post)('people'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:admin'),
         __param(0, (0, common_1.Body)()),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", [Object]),

package/dist/catalog.controller.d.ts

@@ -4,5 +4,51 @@ import { type Type } from '@nestjs/common';
  * guards both come from `forRoot`. A library that hardcodes either one forces
  * every host app to accept its idea of auth, which for an endpoint that
  * enumerates every table in the database is not a reasonable default.
+ *
+ * ---------------------------------------------------------------------------
+ * Every route declares what it needs, and four of the choices are not obvious.
+ *
+ * Declaring is not enforcing — see `catalog.route-auth.ts` — but an *absent*
+ * declaration is a declaration too: it tells a host's guard that authenticated
+ * is enough. So a route left bare is not "undecided", it is "open", and for a
+ * long time this controller said that about arbitrary SQL and about every
+ * curation edit.
+ *
+ * **Arbitrary SQL is `catalog:admin`, not `catalog:read`.** `catalog:read` is
+ * "read object metadata and rows" — rows *of a catalogued type*, through a
+ * route that names one. `POST query` is not bounded by the model at all: it is
+ * whatever the store's read connection can select, and in the shipped MikroORM
+ * store that connection is the catalog's own schema. `SELECT * FROM
+ * catalog_principal` returns every principal's scopes, grants and `keyHash` —
+ * the SHA-256 of its static key — which is not something a reporting principal
+ * should be able to fetch, and is not reachable from any other route here. That
+ * is squarely the population `catalog:admin` ("manage principals and grants")
+ * describes.
+ *
+ * **So the two saved-query write routes are `catalog:admin` too.** They accept
+ * a `sql` field, and `POST saved-queries` + `POST saved-queries/:id/run` is
+ * `POST query` in two requests. Gating one and not the others would make the
+ * strict declaration decoration.
+ *
+ * **Running a saved query is only `catalog:read`.** The capability being held
+ * back is *choosing what SQL runs*, not *seeing a result*: a saved query is an
+ * artefact somebody with the authoring scope vetted, and running one is reading
+ * a report they wrote. Gating execution instead would be worse in both
+ * directions — it would stop an analyst opening a dashboard, and it would let an
+ * unprivileged caller plant a statement and wait for a privileged one to run it.
+ *
+ * **`POST reset` is `catalog:curate`, not `catalog:admin`.** It discards exactly
+ * what the two `PATCH`es write, catalog-wide, and a curator can already blank
+ * every label one request at a time. Requiring admin would deny nothing and
+ * would push a routine console action into the scope that manages principals.
+ *
+ * One consequence is worth stating rather than leaving to be discovered:
+ * `shared` rides on the dashboard write routes, so `catalog:curate` carries the
+ * power to hand a board to an outside application. That is not an oversight —
+ * it is one field on an authoring route, and splitting it would mean a route
+ * whose only job is to flip a boolean. What makes it accountable is that the
+ * act is audited, in both directions and including by deletion; see the
+ * sharing block in `catalog.service.ts`.
+ * ---------------------------------------------------------------------------
  */
 export declare function createCatalogController(path: string, guards: Type<unknown>[], decorators?: ClassDecorator[]): Type<unknown>;