@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/personal-data-export.d.ts

@@ -0,0 +1,241 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** Which subject an export source belongs to. */
+export type ExportSubject = 'user' | 'org';
+/** How a source is located — the axis a path cascade is blind to. */
+export type ExportKeying = 
+/** Top-level collection carrying the subject id in a FIELD. */
+'field'
+/** Top-level collection whose DOCUMENT ID is the subject id. */
+ | 'doc-id'
+/** Under the subject's own document path. */
+ | 'path'
+/** Reached through another collection's rows (a collection group). */
+ | 'collection-group'
+/** Outside Firestore entirely. */
+ | 'external';
+export interface ExportSourceSpec {
+    /** Firestore collection name, or an `external:` pseudo-name. */
+    collection: string;
+    keyedBy: ExportKeying;
+    subjects: readonly ExportSubject[];
+    /**
+     * `true` when the export discloses it. `false` requires `reason` — and the
+     * reason is the whole value of the field: it is a decision recorded at the
+     * moment it was made, not an omission discovered later.
+     */
+    exported: boolean;
+    /** Why it is withheld, or how it is disclosed. Always present. */
+    note: string;
+}
+/**
+ * Every collection `erase.ts` touches, and what the export does with it.
+ *
+ * Kept in the SAME order as the erasure's steps so a reader comparing the two
+ * files reads them in step. `personal-data-export-coverage.spec.ts` proves the
+ * set matches; this list carries the decision for each one.
+ */
+export declare const PERSONAL_DATA_SOURCES: readonly ExportSourceSpec[];
+/** Sources this export deliberately withholds, with the reason. */
+export declare const EXPORT_WITHHELD: ExportSourceSpec[];
+/** Collection names the export claims to cover, for the coverage guard. */
+export declare const EXPORT_COVERED_COLLECTIONS: readonly string[];
+/**
+ * ## WHY THIS IS SHAPE-DRIVEN AND NOT A LIST OF NAMES
+ *
+ * It used to be a list of names, anchored on separators:
+ *
+ *     /(^|[._-])(secret|token|password|apikey|…)($|[._-])/i
+ *
+ * That pattern requires a `.`, `_`, `-`, or a string boundary on both sides
+ * of the word, so it reads `password_hash` and `webhooks.secret` and misses
+ * `supplierToken` and `passwordScrypt` — the exact two fields the AGL-1881
+ * review found leaving the platform in a customer's own export file. One is
+ * a live bearer credential a supplier authenticates with; the other is a
+ * shopper's scrypt password hash. **A denylist of names is always one naming
+ * convention behind, and camelCase is the proof.**
+ *
+ * So the name half is now tokenized rather than separator-anchored, and it is
+ * no longer the only gate. Three run, in order, and any of them redacts:
+ *
+ *  * **(A) The name, tokenized.** `supplierToken` splits to
+ *    `['supplier','token']` the same way `supplier_token` and
+ *    `SUPPLIER-TOKEN` do, so the convention stops mattering. A name matches
+ *    on a single secret word or on an adjacent pair (`client secret`).
+ *  * **(B) The VALUE's shape, whatever the key is called.** This is the half
+ *    that does not need to know the schema: a PEM block, a JWT, a vendor
+ *    prefix (`sk_live_`, `whsec_`, `ghp_`, `AKIA`…), a `$2b$`/`$argon2` hash,
+ *    this repo's own `salt:hash` scrypt form, or an opaque high-entropy
+ *    string is a credential whether the field is called `supplierToken`,
+ *    `t`, or `notes`. **Gate B is the "redact unless known safe" default**:
+ *    a credential-shaped string is withheld unless its key names it as a
+ *    content identifier (see {@link SAFE_VALUE_WORDS}).
+ *  * **(C) Credentials carried inside a URL.** `?token=`, `?sig=`,
+ *    `?key=`, and `https://user:pass@host` are stripped from the URL rather
+ *    than the URL being blanked, because a media object's `url` field really
+ *    does carry a live Firebase download token in a query parameter, and the
+ *    location of the customer's own file is exactly what an access request
+ *    asks for. Precision beats blanking here.
+ *
+ * ### Why the KEY half is still deny-based, when the value half is not
+ *
+ * A true allowlist of field names is not available on this data. The export
+ * walks documents whose field names our customers author — canvas nodes,
+ * dataset records, custom metadata, form submissions — so an allowlist of
+ * names would blank most of the file and turn an access request into a
+ * non-answer, which is the under-disclosure this feature exists to stop. The
+ * allowlist therefore lives where the vocabulary IS ours: value shapes. An
+ * unrecognized VALUE shape is passed through (it is prose, a number, a date,
+ * a customer's own content); an unrecognized value shape that looks like a
+ * credential is withheld. That is the inversion the review asked for, put
+ * where it can hold.
+ *
+ * ### The one deliberate carve-out
+ *
+ * `token`/`tokens` is also a metering word — `tokensUsed: 14203` on an
+ * assist exchange is a usage count, and blanking it would blank a real
+ * disclosure. A credential is a STRING; a count is a number. So a numeric or
+ * boolean value under a name that matched only on a metering word passes
+ * through. Nothing else in the vocabulary gets that treatment.
+ *
+ * A false positive costs a redacted field in an export. A false negative
+ * costs a credential. Everything below is tuned in that direction.
+ */
+/**
+ * Split a field name into lowercase word tokens, convention-independently.
+ *
+ * `supplierToken`, `supplier_token`, `SUPPLIER-TOKEN` and `Supplier.Token`
+ * all become `['supplier','token']`. Acronym runs split at the last capital
+ * (`SSOTokenId` → `['sso','token','id']`) and digits break a word
+ * (`apiKey2` → `['api','key','2']`), so a numbered field cannot hide.
+ */
+export declare function fieldNameTokens(key: unknown): string[];
+/**
+ * Does this STRING look like a credential, ignoring what it is called?
+ *
+ * Exported because the guard spec asserts each limb independently — a shape
+ * detector tested only through the redactor is a detector whose gaps are
+ * invisible.
+ */
+export declare function looksLikeCredential(value: string): boolean;
+/** What a stripped URL parameter reads as, so the removal is visible. */
+export declare const REDACTED_URL_PARAM = "REDACTED";
+/**
+ * Strip the credential out of a URL, keeping the URL.
+ *
+ * A media object's `url` is `…/o/{path}?alt=media&token={uuid}` — a live,
+ * unauthenticated download credential, in a field an access request has a
+ * real interest in. Blanking the whole value would tell the customer nothing
+ * about where their own file is; keeping it whole hands out the credential.
+ * So the parameter is replaced and the rest survives. `user:pass@` userinfo
+ * goes the same way.
+ *
+ * Returns the input unchanged when it is not a URL — every non-URL string
+ * has already been decided by the shape gate.
+ */
+export declare function scrubUrlCredentials(value: string): string;
+/**
+ * Gate (A): does the NAME say credential?
+ *
+ * `value` is consulted only for the metering carve-out described in the
+ * header — a `tokensUsed: 14203` is a count, not a credential.
+ */
+export declare function secretByName(key: unknown, value?: unknown): boolean;
+/** What a redacted value is replaced with — presence, never content. */
+export interface RedactedValue {
+    redacted: true;
+    /** Whether a value was actually there, so absence is distinguishable. */
+    present: boolean;
+    reason: 'secret';
+}
+/**
+ * Deep-copy a document, replacing every credential-shaped value with a
+ * presence marker.
+ *
+ * Presence rather than deletion, because "we hold a webhook secret for you"
+ * is itself a true and disclosable fact, and a silently-absent key would make
+ * the export look like it holds less than it does — the under-disclosure this
+ * feature exists to stop, reintroduced by the safety measure.
+ *
+ * Firestore values that are not plain JSON (Timestamp, GeoPoint, DocumentRef,
+ * Buffer) are stringified rather than walked: they carry no nested keys to
+ * redact, and `JSON.stringify` on a Timestamp yields `{_seconds,_nanoseconds}`,
+ * which is not a date to a human reading the file.
+ *
+ * Three gates, any of which redacts — the name (A), the value's shape (B),
+ * and a credential embedded in a URL (C). See the header above
+ * {@link fieldNameTokens} for why the value half is the one that carries the
+ * "withhold unless known safe" default.
+ */
+export declare function redactSecrets(value: unknown, key?: string): unknown;
+export interface ExportedDocument {
+    /** Document id — omitted where the id is itself a secret (see `apiKeys`). */
+    id?: string;
+    path?: string;
+    data: unknown;
+}
+export interface PersonalDataExport {
+    subject: {
+        type: ExportSubject;
+        id: string;
+    };
+    generatedAt: string;
+    /**
+     * The disclosure decision for every source, copied into the file the
+     * customer receives. An export that silently omits a collection is
+     * indistinguishable from one that has nothing to report; this makes the two
+     * different, and it is what a supervisory authority would ask to see.
+     */
+    coverage: readonly ExportSourceSpec[];
+    /** Collection name → the documents disclosed for it. */
+    data: Record<string, ExportedDocument[]>;
+    /** Collection name → row count, for sources disclosed as a count only. */
+    counts: Record<string, number>;
+    /** Places we hold data that is not in Firestore. */
+    elsewhere: readonly string[];
+}
+export interface ExportOptions {
+    /** Injectable for tests; defaults to the admin app's Firestore. */
+    firestore?: any;
+    /** Stops a pathological workspace from building an unbounded file. */
+    maxDepth?: number;
+}
+/**
+ * Everything we hold about a PERSON, as the person themselves may ask for it
+ * (GDPR Art. 15 and Art. 20).
+ *
+ * Scoped to them, never to the workspaces they belong to. Their membership row
+ * in each org is theirs; the roster around it is their colleagues'. An org
+ * export is a separate call with a separate authorization, which is the whole
+ * reason the two are different functions rather than one with a flag.
+ */
+export declare function exportUserData(uid: string, options?: ExportOptions): Promise<PersonalDataExport>;
+/**
+ * Everything we hold about a WORKSPACE, for its owner (Art. 15 for the
+ * personal data in it, and the "export before you delete" the Delete tab,
+ * DPA §11 and Terms §13.3 have been promising).
+ *
+ * Every top-level collection the erasure sweeps by `orgId` is read here by the
+ * same bound, so the two see the same rows. Where a source is withheld, its
+ * COUNT is still reported: a collection that appears in neither the data nor
+ * the counts is indistinguishable from one that does not exist, and that
+ * ambiguity is what makes an incomplete export undetectable.
+ */
+export declare function exportOrgData(orgId: string, options?: ExportOptions): Promise<PersonalDataExport>;
+/** A filename a human can file: subject, id and the date it was produced. */
+export declare function exportFilename(exported: PersonalDataExport): string;
+export default exportUserData;