@voltro/plugin-governance 0.32.0 → 0.34.0

package/THIRD-PARTY-NOTICES.md

@@ -5,7 +5,7 @@ property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plugin-governance itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (52 packages).
+Generated from the resolved runtime dependency closure (51 packages).
 
 ---
 
@@ -37,34 +37,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## @effect/opentelemetry@0.64.0
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2020-present The Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## @effect/platform-node@0.108.0
 
 License: MIT

package/dist/index.d.ts

@@ -1,14 +1,41 @@
 import { Context } from 'effect';
+import { DEFAULT_SUBJECT_GRAPH_DEPTH } from '@voltro/database';
 import { deriveKey } from '@voltro/runtime';
+import { deriveSubjectGraph } from '@voltro/database';
+import { DeriveSubjectGraphInput } from '@voltro/database';
 import { ENCRYPTED_PREFIX } from '@voltro/database';
 import { FieldCipher } from '@voltro/database';
+import { formatSubjectGraph } from '@voltro/database';
 import { isEncrypted } from '@voltro/database';
 import { makeAesCipher } from '@voltro/runtime';
 import { makeFieldCipher } from '@voltro/runtime';
 import { SchemaTable } from '@voltro/database';
 import { setFieldCipher } from '@voltro/runtime';
+import { SubjectGraph } from '@voltro/database';
+import { SubjectGraphLimitation } from '@voltro/database';
+import { SubjectHop } from '@voltro/database';
+import { SubjectPath } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
+export declare interface CollectedTable {
+    readonly table: string;
+    readonly rows: ReadonlyArray<Record<string, unknown>>;
+    /** Set when the row cap cut this table short. */
+    readonly truncated?: boolean;
+}
+
+/**
+ * Resolve every path against the store and return the rows per TABLE (merged
+ * and de-duplicated by `id` — two routes can legitimately reach the same table).
+ *
+ * Hop resolution: hop 0's filter is the subject id itself; each later hop is
+ * filtered by the `id`s (or `parentKey`s) found at the previous one. A hop that
+ * finds nothing terminates that path — there is no point asking for the children
+ * of an empty set, and asking anyway with an empty `IN` is how a filter
+ * accidentally becomes "all rows".
+ */
+export declare const collectSubjectRows: (store: GovStore, paths: ReadonlyArray<SubjectPath>, subjectId: string, rowCap?: number) => Promise<ReadonlyArray<CollectedTable>>;
+
 export declare const CONSENT_TABLE = "_voltro_consent";
 
 /** Narrow slice of the framework DataStore the durable consent store needs. */
@@ -65,12 +92,30 @@ export declare const dataStoreConsentStore: (store: ConsentDataStore) => Consent
 /** Adapt a framework `DataStore` (untyped here) to `GovStore`. */
 export declare const dataStoreGovStore: (store: unknown) => GovStore;
 
+export { DEFAULT_SUBJECT_GRAPH_DEPTH }
+
 export { deriveKey }
 
+export { deriveSubjectGraph }
+
+export { DeriveSubjectGraphInput }
+
 export { ENCRYPTED_PREFIX }
 
-/** Erase a subject across `scopes`. Returns an immutable erasure-log entry. */
-export declare const eraseSubject: (store: GovStore, scopes: ReadonlyArray<SubjectScope>, subjectId: string, opts?: ErasureOptions, now?: () => string) => Promise<ErasureLogEntry>;
+/**
+ * Erase a subject across `paths`. Returns an immutable erasure-log entry.
+ *
+ * DELETION ORDER IS DEEPEST-FIRST. The paths describe a parent→child graph and
+ * the branch's own foreign keys are real, so deleting a parent before its
+ * children either fails on `RESTRICT` or silently widens the erasure through
+ * `CASCADE` — and a cascade is an erasure nobody counted, which the log entry
+ * would then under-report.
+ *
+ * An `anonymize` erasure only touches columns the caller named, so it has no
+ * ordering requirement; it is run in the same order for one behaviour rather
+ * than two.
+ */
+export declare const eraseSubject: (store: GovStore, paths: ReadonlyArray<SubjectPath>, subjectId: string, opts?: ErasureOptions, now?: () => string) => Promise<ErasureLogEntry>;
 
 /**
  * Most-recent GDPR erasure-log entries kept in memory (most-recent-first).
@@ -89,6 +134,13 @@ export declare interface ErasureLogEntry {
         table: string;
         count: number;
     }>;
+    /**
+     * Tables whose row set hit {@link SUBJECT_ROW_CAP}. NON-EMPTY MEANS THE
+     * ERASURE IS INCOMPLETE and must be re-run — recorded in the log entry rather
+     * than warned about, because the log entry is the compliance artefact and a
+     * warning on a console is not.
+     */
+    readonly truncated?: ReadonlyArray<string>;
 }
 
 export declare interface ErasureOptions {
@@ -98,17 +150,48 @@ export declare interface ErasureOptions {
     readonly anonymizeFields?: ReadonlyArray<string>;
 }
 
-/** Collect every row across `scopes` that belongs to a subject → a portable bundle. */
-export declare const exportSubject: (store: GovStore, scopes: ReadonlyArray<SubjectScope>, subjectId: string) => Promise<Record<string, ReadonlyArray<Record<string, unknown>>>>;
+/** Collect every row belonging to a subject across `paths` → a portable bundle. */
+export declare const exportSubject: (store: GovStore, paths: ReadonlyArray<SubjectPath>, subjectId: string) => Promise<Record<string, ReadonlyArray<Record<string, unknown>>>>;
 
 export { FieldCipher }
 
+export { formatSubjectGraph }
+
 export declare const governancePlugin: (options?: GovernancePluginOptions) => VoltroPlugin;
 
 export declare interface GovernancePluginOptions {
     readonly retention?: ReadonlyArray<RetentionPolicy>;
-    /** Tables (+ subject column) the GDPR export/erase walk. */
+    /**
+     * Tables (+ subject column) the GDPR export/erase walk — the EXPLICIT form.
+     *
+     * Still first-class, and the only way to reach data the schema does not
+     * encode: a subject id in a plain (non-`reference()`) column, a polymorphic
+     * `(ownerType, ownerId)` pair, an id inside JSON. Merged with anything
+     * `deriveSubjectScopes` finds.
+     */
     readonly subjectScopes?: ReadonlyArray<SubjectScope>;
+    /**
+     * DERIVE the subject scope from the schema instead of hand-listing it.
+     *
+     * Give it the table whose primary key is the subject id and the walk follows
+     * the relations registry + the `reference()` column graph outward, so a table
+     * added tomorrow is in the DSAR tomorrow — which a hand-written list is not.
+     * Only CHILD edges are followed (a table holding a reference to the subject's
+     * row), never parent/lookup edges: walking from a person to their organisation
+     * would export, and then ERASE, everybody else in it.
+     *
+     * It is not a substitute for reading `GovernanceService.subjectGraph()`. Some
+     * links are structurally invisible to it (see `SubjectGraph.limitations`) and
+     * the derivation says so rather than implying completeness.
+     */
+    readonly deriveSubjectScopes?: {
+        readonly subjectTable: string;
+        /** Hop ceiling; default 4. Anything cut is reported as `depth-truncated`. */
+        readonly maxDepth?: number;
+        /** Tables never walked into. A framework audit trail is the usual entry —
+         *  Art. 17(3)(b) frequently REQUIRES retaining it. */
+        readonly exclude?: ReadonlyArray<string>;
+    };
     /** Default erasure mode + anonymise fields. */
     readonly erasure?: ErasureOptions;
     /**
@@ -133,6 +216,24 @@ export declare interface GovernancePluginOptions {
     readonly fieldEncryption?: boolean | {
         readonly secretKey?: string;
     };
+    /**
+     * Namespace for this plugin's rpc tags + inspect endpoints. Default `governance`.
+     *
+     * Set it when your app already publishes under that name — an exact tag
+     * collision is fatal at codegen, and this is the way out. Orthogonal to
+     * `name` below: `alias` REPLACES the namespace, `name` distinguishes two
+     * installations within it.
+     *
+     * The cost, stated because nothing else states it: the local and cloud
+     * dashboards fetch this plugin's panel at the DEFAULT slug, so an aliased
+     * install keeps working while its dashboard panel 404s. Alias to escape a
+     * collision, not for taste.
+     */
+    readonly alias?: string;
+    /**
+     * Discriminator for a SECOND installation of this plugin, when one app runs
+     * two (`@voltro/plugin-governance#analytics`). Not a rename — for that use `alias`.
+     */
     readonly name?: string;
 }
 
@@ -147,19 +248,44 @@ export declare interface GovernanceServiceShape {
     readonly recordConsent: (entry: ConsentRecord) => Promise<void>;
     readonly hasConsent: (subjectId: string, purpose: string) => Promise<boolean>;
     readonly runRetentionNow: () => Promise<void>;
+    /**
+     * The routes a DSAR will walk, plus what the derivation CANNOT see. Read this
+     * before signing off on an erasure process: the completeness of a right-to-be-
+     * forgotten claim is exactly the completeness of this list, and the honest
+     * parts of it are the `limitations`.
+     */
+    readonly subjectGraph: () => SubjectGraph;
 }
 
 export declare interface GovStore {
     /**
      * All rows of a table.
      *
-     * CEILING: this materialises the WHOLE table in memory. It is used by the
-     * GDPR export/erase walks, which are admin-gated, occasional, single-subject
-     * operations — fine in practice. Do NOT use it on the retention path (the
-     * retention table is the one that grows unbounded) — use {@link page} +
-     * a bounded loop there instead.
+     * CEILING: this materialises the WHOLE table in memory. Nothing on the GDPR
+     * path uses it any more — export and erasure go through {@link where}, which
+     * pushes the subject filter into SQL. It survives for callers that genuinely
+     * want the whole table, and for the in-memory test store.
+     *
+     * It USED to back the DSAR walk, and the doc comment here argued that was fine
+     * because the operation is "admin-gated and occasional". That argument is
+     * wrong in the way scale arguments usually are: the cost is not per REQUEST,
+     * it is per TABLE IN THE SUBJECT SCOPE, and a derived scope has many more
+     * tables than a hand-listed one. One erasure meant one full scan of every
+     * table holding personal data.
      */
     readonly all: (table: string) => Promise<ReadonlyArray<Record<string, unknown>>>;
+    /**
+     * Rows of `table` whose `column` is one of `values` — the indexed read the
+     * subject walk runs, one per hop.
+     *
+     * `values` is expected to be chunked by the caller ({@link SUBJECT_KEY_CHUNK})
+     * so the emitted `IN (…)` list stays inside every dialect's parameter ceiling.
+     * An EMPTY `values` must return no rows without touching the database: an
+     * unbounded `IN ()` is a syntax error on some engines and "every row" if a
+     * caller papers over it, and "every row" on an erasure path is the worst
+     * possible failure.
+     */
+    readonly where: (table: string, column: string, values: ReadonlyArray<unknown>) => Promise<ReadonlyArray<Record<string, unknown>>>;
     /**
      * One bounded page of rows (`limit` rows starting at `offset`, ordered by a
      * stable key). Lets the retention sweep scan a large table in capped batches
@@ -233,12 +359,49 @@ declare interface RetentionReport {
  */
 export declare const runRetention: (store: GovStore, policies: ReadonlyArray<RetentionPolicy>, now?: number, batchSize?: number) => Promise<ReadonlyArray<RetentionReport>>;
 
+/** Normalise a hand-listed scope into the path form the walk runs on. A scope on
+ *  the subject table keyed by its own id column is depth 0; anything else is a
+ *  single hop off the subject table. */
+export declare const scopeToPath: (scope: SubjectScope, subjectTable: string) => SubjectPath;
+
 /** Pure — the ids of rows past their TTL. */
 export declare const selectExpired: (rows: ReadonlyArray<Record<string, unknown>>, policy: RetentionPolicy, now: number) => ReadonlyArray<string>;
 
 export { setFieldCipher }
 
-/** One table that references a subject, by which column. */
+/**
+ * Keys per `IN (…)` chunk. Well under every dialect's parameter ceiling (SQL
+ * Server's 2100 is the tightest) and small enough that one subject with a very
+ * large child set does not build a single statement megabytes wide.
+ */
+export declare const SUBJECT_KEY_CHUNK = 500;
+
+/**
+ * Rows collected per table, per subject. A ceiling exists because a DSAR is an
+ * unauthenticated-user-triggerable operation in most apps, and "export
+ * everything reachable" against a pathological graph is a memory exhaustion the
+ * caller cannot see coming. Exceeding it is REPORTED (`truncated`), never
+ * silently dropped — a short export presented as complete is the failure this
+ * whole module exists to avoid.
+ */
+export declare const SUBJECT_ROW_CAP = 50000;
+
+export { SubjectGraph }
+
+export { SubjectGraphLimitation }
+
+export { SubjectHop }
+
+export { SubjectPath }
+
+/**
+ * One table that references a subject, by which column — the hand-written form.
+ *
+ * Still supported and still first-class: a subject id carried in a plain column,
+ * or reached by a rule the schema does not encode, can only be declared. It
+ * normalises into a depth-0/1 {@link SubjectPath}, so both forms run through one
+ * walk.
+ */
 export declare interface SubjectScope {
     readonly table: string;
     /** Column holding the subject id (e.g. 'userId', 'createdBy', 'id'). */