@dudousxd/nestjs-catalog 0.5.0 → 0.6.0

package/dist/catalog.events.d.ts

@@ -14,15 +14,16 @@
  */
 export declare const CATALOG_LIB = "catalog";
 /** Every event name this package emits. Exported so a watcher can claim them. */
-export declare const CATALOG_EVENTS: readonly ["schema.changed", "snapshot.written", "snapshot.committed", "snapshot.dropped", "type.curated", "connector.run.started", "connector.run.finished", "transform.changed", "workflow.changed"];
+export declare const CATALOG_EVENTS: readonly ["schema.changed", "snapshot.written", "snapshot.committed", "snapshot.dropped", "type.curated", "connector.run.started", "connector.run.finished", "transform.changed", "workflow.changed", "query.shared", "dashboard.shared"];
 export type CatalogEvent = (typeof CATALOG_EVENTS)[number];
 /**
  * Where each event sits in the life of one load.
  *
  * This exists because a timestamp is not enough to order a trace. A fast load
  * emits its whole story inside a single tick of whatever clock the recorder
- * writes — the bundled MySQL store keeps whole seconds — so sorting by time
- * alone leaves the events in insertion order, and insertion order is arbitrary.
+ * writes — the bundled MySQL store keeps milliseconds, and a commit of a few
+ * hundred rows lands well inside one — so sorting by time alone leaves the
+ * events in insertion order, and insertion order is arbitrary.
  * The observed result is a trace that reads `finished → written → committed →
  * started`: causally impossible, rendered with total confidence. Sorting by
  * time *and then* by this rank puts a same-tick story back in the only order it
@@ -142,6 +143,69 @@ export interface CatalogEventPayloads {
         nodeCount: number;
         changedBy: string;
     };
+    /**
+     * A saved query started or stopped being fetchable through the embed API.
+     *
+     * The single act that hands an outside application data from this catalog, and
+     * for a long time the only one that left no trace: `SavedQuery.shared` is the
+     * whole embed boundary, it is set by a person, and nothing recorded that they
+     * had set it.
+     *
+     * One event for both directions rather than a `query.unshared` beside it,
+     * following `connector.run.finished`: anybody watching for shares has to watch
+     * for revocations too — a trail that records only the grants cannot answer
+     * "was this still shared last Tuesday", which is the question an incident
+     * actually asks. The direction is in {@link shared}.
+     *
+     * Emitted on the transition only. A save that leaves the flag where it was is
+     * not a sharing decision, and a trail that logged every keystroke on a query
+     * would be a trail nobody reads.
+     *
+     * **Deleting a shared query is one of those transitions**, and it emits here
+     * rather than under a name of its own. The question this event answers is
+     * "when did this stop being reachable from outside", and anybody asking it
+     * filters on `query.shared` and reads the last entry. A separate
+     * `query.deleted` would leave that filter reporting `shared: true` forever
+     * for something nobody can fetch — the revocation would be in a channel the
+     * asker did not subscribe to, which is the same absence this event exists to
+     * remove. {@link deleted} says which kind of ending it was.
+     */
+    'query.shared': {
+        savedQueryId: string;
+        /** As it read at the moment of the change, so the trail is legible alone. */
+        name: string;
+        /** True when access was granted, false when it was taken back. */
+        shared: boolean;
+        /**
+         * Who decided. The host-resolved principal where there is one, and named
+         * `principalId` because that is the field a recorder lifts into the audit
+         * table's indexed column — spell it anything else and the entry lands
+         * attributed to nobody.
+         */
+        principalId: string;
+        /**
+         * Set only when the revocation was a deletion. Absent means the thing still
+         * exists and was merely un-shared.
+         *
+         * Typed as `true` rather than `boolean` so the flag cannot be written the
+         * other way round: "not a deletion" is the absence of this key, matching
+         * how the rest of these payloads treat a fact that did not happen.
+         *
+         * Worth carrying rather than leaving to be looked up, because after a
+         * deletion there is nothing left to look up. An entry that said only
+         * `shared: false` would send its reader to a row that is gone, and the
+         * empty result reads as a broken trail rather than as the answer.
+         */
+        deleted?: true;
+    };
+    /** The same decision, about a whole board. See {@link CatalogEventPayloads['query.shared']}. */
+    'dashboard.shared': {
+        dashboardId: string;
+        name: string;
+        shared: boolean;
+        principalId: string;
+        deleted?: true;
+    };
 }
 /**
  * Teach the diagnostics channel what this library puts on it.

package/dist/catalog.events.js

@@ -31,14 +31,17 @@ exports.CATALOG_EVENTS = [
     'connector.run.finished',
     'transform.changed',
     'workflow.changed',
+    'query.shared',
+    'dashboard.shared',
 ];
 /**
  * Where each event sits in the life of one load.
  *
  * This exists because a timestamp is not enough to order a trace. A fast load
  * emits its whole story inside a single tick of whatever clock the recorder
- * writes — the bundled MySQL store keeps whole seconds — so sorting by time
- * alone leaves the events in insertion order, and insertion order is arbitrary.
+ * writes — the bundled MySQL store keeps milliseconds, and a commit of a few
+ * hundred rows lands well inside one — so sorting by time alone leaves the
+ * events in insertion order, and insertion order is arbitrary.
  * The observed result is a trace that reads `finished → written → committed →
  * started`: causally impossible, rendered with total confidence. Sorting by
  * time *and then* by this rank puts a same-tick story back in the only order it
@@ -64,6 +67,16 @@ exports.CATALOG_EVENT_PHASE = {
     // be complete is exactly the mechanism that will fail the build the day a new
     // event is added and nobody thinks about where it belongs.
     'type.curated': 2,
+    // Sharing carries no snapshot id either, for the same reason curation does
+    // not: it is a standalone act on a saved query or a board, not a step of any
+    // load. So these ranks are never consulted, and they are written out for the
+    // reason the note above gives — the `Record` has to be complete, and that is
+    // what makes the build fail the day an event is added and nobody thinks about
+    // where it belongs. Ranked beside curation because they are the same kind of
+    // thing: a person deciding something about the catalog rather than data moving
+    // through it.
+    'query.shared': 2,
+    'dashboard.shared': 2,
     'schema.changed': 3,
     'snapshot.written': 4,
     'snapshot.committed': 5,

package/dist/catalog.principal.d.ts

@@ -16,6 +16,7 @@
  * to survive into the audit trail, because "the console renamed this column" is
  * not an answer anybody accepts.
  */
+import type { CatalogObjectPage } from './catalog.types';
 export type CatalogScope = 
 /** Read object metadata and rows. */
 'catalog:read'
@@ -118,7 +119,9 @@ export interface CatalogPrincipal {
     readTypes?: string[];
     /**
      * Classifications this principal may see. A column marked with anything
-     * outside this list is dropped from its reads.
+     * outside this list is to be dropped from its reads — *by whoever serves
+     * them*, which is not this library. See the note above {@link mayWrite} on
+     * who enforces, and {@link readableObjectPage} for the drop itself.
      *
      * Undefined means "no classified columns", not "all of them" — the safe
      * default for a caller nobody has thought about yet.
@@ -198,12 +201,57 @@ export declare function expandScopes(scopes: CatalogScope[]): CatalogScope[];
  * something that happens because an administrator logged in.
  */
 export declare function delegatePrincipal(application: CatalogPrincipal, actor: CatalogActor, grants: CatalogGrants): CatalogPrincipal;
+/** Enforced by the library, because the publish API is handed a principal. */
 export declare function mayWrite(principal: CatalogPrincipal, typeName: string): boolean;
+/**
+ * Whether this principal may read a type at all.
+ *
+ * A predicate for a host to apply, not something the catalog's own read routes
+ * consult — see the note above. `readableObjectPage` is the ready-made
+ * application of it.
+ */
 export declare function mayRead(principal: CatalogPrincipal, typeName: string): boolean;
 /**
  * Whether a column is visible to this principal.
  *
  * Unclassified columns are visible to everyone; a classified one requires the
  * principal to name that classification. Absence is denial.
+ *
+ * The same caveat as {@link mayRead}: answering the question is all this does.
+ * No read path in this library asks it.
  */
 export declare function maySeeClassification(principal: CatalogPrincipal, classification: string | undefined): boolean;
+/**
+ * A page of objects as this principal is allowed to see it: the page, minus
+ * every column carrying a classification they do not hold — and `null` when
+ * they may not read the type at all.
+ *
+ * This exists so that "who applies `mayRead` and `maySeeClassification`?" has an
+ * answer a host can call rather than a rule a host has to re-derive. Wrap the
+ * service:
+ *
+ * ```ts
+ * const page = await this.catalog.readObjects(name, query);
+ * const visible = readableObjectPage(principal, page);
+ * if (!visible) throw new ForbiddenException(`${principal.id} may not read ${name}.`);
+ * return visible;
+ * ```
+ *
+ * `null` rather than a thrown exception because the status code is the host's
+ * decision: a 403 confirms to the caller that the type exists, and a deployment
+ * that considers the type list itself sensitive would rather answer 404. `null`
+ * rather than an empty page because a page with no columns is what a type whose
+ * every column is hidden legitimately returns, and a denial must not be
+ * mistakable for one.
+ *
+ * Hidden values are **deleted** from each row rather than blanked. A key present
+ * with `null` asserts that the column exists and happens to be empty, which for
+ * a classified column is itself a disclosure.
+ *
+ * What it does not do: rows can carry keys no column declares, because
+ * `readObjects` always fetches the primary key so a UI has a row identity even
+ * when that key is hidden. Those survive. This removes what a classification
+ * hides; it is not a whitelist, and a classified column that is also part of a
+ * hidden primary key is outside what a page alone can express.
+ */
+export declare function readableObjectPage(principal: CatalogPrincipal, page: CatalogObjectPage): CatalogObjectPage | null;

package/dist/catalog.principal.js

@@ -27,6 +27,7 @@ exports.delegatePrincipal = delegatePrincipal;
 exports.mayWrite = mayWrite;
 exports.mayRead = mayRead;
 exports.maySeeClassification = maySeeClassification;
+exports.readableObjectPage = readableObjectPage;
 /** Every scope, in one place, so `catalog:admin` can be expanded exactly. */
 const ALL_SCOPES = [
     'catalog:read',
@@ -222,9 +223,45 @@ function matches(list, typeName) {
         return false;
     return list.includes('*') || list.includes(typeName);
 }
+// -----------------------------------------------------------------------------
+// The grant predicates, and who is expected to call them.
+//
+// **This library declares and evaluates; the host enforces.** The same split
+// `catalog.route-auth.ts` states for scopes holds for grants: nothing in this
+// package ever turns a request into a principal. `CatalogPrincipalResolver` is
+// an interface with one bundled development implementation, no guard ships here,
+// and the `request.principal` that `publish.controller.ts` reads is put there by
+// a guard the host wrote — the error it throws even names a class this repo does
+// not contain.
+//
+// The asymmetry between write and read is real and is not the bug it looks like.
+// `mayWrite` is called inside the library, in `publish.service.ts`, for exactly
+// one reason: the publish API takes a `CatalogPrincipal` as an argument, so it
+// has one in hand. The read path does not. `CatalogService.readObjects` has no
+// principal parameter, `GET /catalog/objects/:name` has none to give it, and so
+// `mayRead` and `maySeeClassification` are called nowhere in this repository at
+// runtime. That is the design: a library that filtered reads would need a
+// principal on every read, which means shipping a guard, which means having an
+// opinion about the host's identity provider.
+//
+// What was wrong was not the mechanism but the prose around it. A host reading
+// "classifications this principal may see" is entitled to assume something drops
+// the columns, and nothing does. So, stated once, here: **the read path applies
+// no grants and no classification filtering, and a host that wants either calls
+// `readableObjectPage` itself.** Anyone about to "wire this up" should change
+// that sentence rather than quietly making it false.
+// -----------------------------------------------------------------------------
+/** Enforced by the library, because the publish API is handed a principal. */
 function mayWrite(principal, typeName) {
     return hasScope(principal, 'catalog:write') && matches(principal.writeTypes, typeName);
 }
+/**
+ * Whether this principal may read a type at all.
+ *
+ * A predicate for a host to apply, not something the catalog's own read routes
+ * consult — see the note above. `readableObjectPage` is the ready-made
+ * application of it.
+ */
 function mayRead(principal, typeName) {
     if (!hasScope(principal, 'catalog:read'))
         return false;
@@ -237,9 +274,64 @@ function mayRead(principal, typeName) {
  *
  * Unclassified columns are visible to everyone; a classified one requires the
  * principal to name that classification. Absence is denial.
+ *
+ * The same caveat as {@link mayRead}: answering the question is all this does.
+ * No read path in this library asks it.
  */
 function maySeeClassification(principal, classification) {
     if (!classification)
         return true;
     return principal.classifications?.includes(classification) ?? false;
 }
+/**
+ * A page of objects as this principal is allowed to see it: the page, minus
+ * every column carrying a classification they do not hold — and `null` when
+ * they may not read the type at all.
+ *
+ * This exists so that "who applies `mayRead` and `maySeeClassification`?" has an
+ * answer a host can call rather than a rule a host has to re-derive. Wrap the
+ * service:
+ *
+ * ```ts
+ * const page = await this.catalog.readObjects(name, query);
+ * const visible = readableObjectPage(principal, page);
+ * if (!visible) throw new ForbiddenException(`${principal.id} may not read ${name}.`);
+ * return visible;
+ * ```
+ *
+ * `null` rather than a thrown exception because the status code is the host's
+ * decision: a 403 confirms to the caller that the type exists, and a deployment
+ * that considers the type list itself sensitive would rather answer 404. `null`
+ * rather than an empty page because a page with no columns is what a type whose
+ * every column is hidden legitimately returns, and a denial must not be
+ * mistakable for one.
+ *
+ * Hidden values are **deleted** from each row rather than blanked. A key present
+ * with `null` asserts that the column exists and happens to be empty, which for
+ * a classified column is itself a disclosure.
+ *
+ * What it does not do: rows can carry keys no column declares, because
+ * `readObjects` always fetches the primary key so a UI has a row identity even
+ * when that key is hidden. Those survive. This removes what a classification
+ * hides; it is not a whitelist, and a classified column that is also part of a
+ * hidden primary key is outside what a page alone can express.
+ */
+function readableObjectPage(principal, page) {
+    if (!mayRead(principal, page.type))
+        return null;
+    const hidden = page.columns
+        .filter((column) => !maySeeClassification(principal, column.classification))
+        .map((column) => column.name);
+    if (hidden.length === 0)
+        return page;
+    return {
+        ...page,
+        columns: page.columns.filter((column) => !hidden.includes(column.name)),
+        rows: page.rows.map((row) => {
+            const visible = { ...row };
+            for (const name of hidden)
+                delete visible[name];
+            return visible;
+        }),
+    };
+}

package/dist/catalog.service.d.ts

@@ -3,7 +3,7 @@ import { type CatalogQueryRelation, type CatalogQueryResult } from './catalog.qu
 import { CatalogRegistry } from './catalog.registry.base';
 import { type CatalogReadStore, type SnapshotRef } from './catalog.store';
 import type { CatalogGraph, CatalogObjectPage, CatalogObjectQuery, CatalogObjectTypeDef, CatalogOverlay, CatalogSnapshot } from './catalog.types';
-import { type AuditQuery, type CatalogAuditEvent, type CatalogWorkspaceStore, type Dashboard, type DashboardCard, type EmbeddedChart, type EmbeddedDashboard, type SaveQueryInput, type SavedQuery } from './catalog.workspace';
+import { type AuditQuery, type CatalogAuditEvent, type CatalogWorkspaceStore, type Dashboard, type DashboardCard, type EmbeddedChart, type EmbeddedChartPlacement, type EmbeddedDashboard, type SaveQueryInput, type SavedQuery } from './catalog.workspace';
 /**
  * Reads objects of any catalogued type through one endpoint.
  *
@@ -32,6 +32,17 @@ export declare class CatalogService {
     resetOverlay(): Promise<void>;
     /** Columns a generic UI may render: visible, and not a blob. */
     visibleColumns(type: CatalogObjectTypeDef): import("./catalog.types").CatalogPropertyDef[];
+    /**
+     * Rows of one type, paged.
+     *
+     * **No principal, and so no access control.** This applies the guardrails that
+     * hold for every caller — the type exists, the page is bounded, the sort names
+     * a real column — and none that depend on who is asking: a classified column
+     * comes back to whoever the host's guard let through the door. That is the
+     * library's declare-and-enforce split, written out at length above `mayWrite`
+     * in `catalog.principal.ts`. A host that wants per-principal reads passes this
+     * page through `readableObjectPage`.
+     */
     readObjects(typeName: string, query: CatalogObjectQuery & {
         snapshot?: string;
     }): Promise<CatalogObjectPage>;
@@ -68,9 +79,22 @@ export declare class CatalogService {
     private requireWorkspace;
     listSavedQueries(): Promise<SavedQuery[]>;
     getSavedQuery(id: string): Promise<SavedQuery>;
+    /**
+     * @param createdBy who saved it — the row's author and the audit entry's
+     * actor. The host's resolved principal id where the host resolves one; see
+     * the enforcement note in `catalog.principal.ts` for why this library cannot
+     * work it out itself.
+     */
     saveQuery(input: SaveQueryInput, createdBy: string): Promise<SavedQuery>;
-    updateSavedQuery(id: string, input: Partial<SaveQueryInput>): Promise<SavedQuery>;
-    deleteSavedQuery(id: string): Promise<boolean>;
+    /** @param changedBy who made the change, for the audit trail. */
+    updateSavedQuery(id: string, input: Partial<SaveQueryInput>, changedBy: string): Promise<SavedQuery>;
+    /**
+     * @param deletedBy who deleted it, for the audit trail. Required rather than
+     * defaulted, matching `saveQuery` and `updateSavedQuery`: a default would
+     * quietly attribute revocations to nobody in every caller that was not
+     * updated, and the trail's whole value here is that it names somebody.
+     */
+    deleteSavedQuery(id: string, deletedBy: string): Promise<boolean>;
     /** Runs a saved query, honouring the TTL it was saved with. */
     runSavedQuery(id: string, maxRows?: number): Promise<{
         savedQuery: SavedQuery;
@@ -78,17 +102,31 @@ export declare class CatalogService {
     }>;
     listDashboards(): Promise<Dashboard[]>;
     getDashboard(id: string): Promise<Dashboard>;
+    /**
+     * `shared` is declared here, and that is not cosmetic.
+     *
+     * The store has always accepted it, so it worked as long as the body reached
+     * the store untouched. A host with a whitelisting `ValidationPipe` — the
+     * normal, recommended configuration — strips a property no type declares, and
+     * the symptom is a dashboard that cannot be shared with no error anywhere:
+     * the toggle saves, the response says `shared: false`, and the embed API
+     * keeps answering 403 for a board somebody just shared.
+     */
     saveDashboard(input: {
         name: string;
         description?: string;
         cards?: DashboardCard[];
+        shared?: boolean;
     }, createdBy: string): Promise<Dashboard>;
+    /** @param changedBy who made the change, for the audit trail. */
     updateDashboard(id: string, input: Partial<{
         name: string;
         description: string;
         cards: DashboardCard[];
-    }>): Promise<Dashboard>;
-    deleteDashboard(id: string): Promise<boolean>;
+        shared: boolean;
+    }>, changedBy: string): Promise<Dashboard>;
+    /** @param deletedBy who deleted it. See {@link deleteSavedQuery}. */
+    deleteDashboard(id: string, deletedBy: string): Promise<boolean>;
     /** Everything shared, so a consumer can discover what it may render. */
     listEmbeddable(): Promise<{
         dashboards: Array<{
@@ -104,11 +142,16 @@ export declare class CatalogService {
             kind: string;
         }>;
     }>;
-    /** One chart, rendered. */
-    embedChart(savedQueryId: string, layout?: {
-        width: number;
-        position: number;
-    }): Promise<EmbeddedChart>;
+    /**
+     * One chart, rendered.
+     *
+     * `placement` is what the dashboard card said, and it is honoured rather than
+     * merely carried: a card's `title` and `library` exist to override the saved
+     * query on THIS board, so an embed that ignored them would show a different
+     * heading and a different chart from the console for the same dashboard —
+     * silently, with nothing thrown and nothing logged.
+     */
+    embedChart(savedQueryId: string, placement?: EmbeddedChartPlacement): Promise<EmbeddedChart>;
     /** A whole dashboard, every chart resolved. */
     embedDashboard(dashboardId: string): Promise<EmbeddedDashboard>;
     listEvents(query: AuditQuery): Promise<CatalogAuditEvent[]>;