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

package/src/lib/server/erase.d.ts

@@ -0,0 +1,458 @@
+/**
+ * @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.
+ */
+import { type AccountAddressSet, type AccountAddressSource } from './account-addresses';
+import { type PluginUserErasureReport } from '@aglyn/aglyn/plugin-manager/plugin-user-erasure';
+import { type PluginOrgErasureReport } from '@aglyn/aglyn/plugin-manager/plugin-org-erasure';
+import { type SendingDomainDisposition, type TeardownSendingDomainDriver } from './sending-domain-debt';
+/** The reversible hold before a requested erasure is executed (AGL-485). */
+export declare const ERASURE_HOLD_MS: number;
+/**
+ * Permanently erase a single site and everything it owns (AGL-488).
+ * Unlike deleting the host doc alone (which orphans data), this cleans up
+ * every trailing reference:
+ *   - Storage objects under `hosts/{hostId}/` (media, CDN variants),
+ *   - the `hostIndex/{hostId}` routing entry (subdomain/cname resolution),
+ *   - the owning org's `hosts` routing-map entry, and
+ *   - the host's Firestore tree (screens, layouts, versions, counters, …)
+ *     via `recursiveDelete`.
+ *
+ * Shared by the self-serve delete-site route and the org-erasure pipeline
+ * (AGL-487). Fail-soft on Storage/index cleanup so a partial failure never
+ * blocks the Firestore delete; safe to re-run.
+ */
+export interface EraseHostOptions {
+    /**
+     * The console-side sending-domain teardown, injected because this library
+     * may not hold the credentials it needs — see `sending-domain-debt.ts`.
+     *
+     * Absent, the site's domain is not released inline: the debt is recorded on
+     * the surviving label claim and `/api/admin/reap-sending-domains` settles
+     * it. That is the only correct default here. A library the tenant runtime
+     * imports cannot reach a full-access mail credential, and an erasure must
+     * not fail or stall because a vendor is unreachable.
+     */
+    tearDownSendingDomain?: TeardownSendingDomainDriver | null;
+}
+export interface EraseHostResult {
+    /** What became of the site's dedicated sending domain, if it had one. */
+    sendingDomain: SendingDomainDisposition;
+}
+export declare function eraseHost(hostId: string, options?: EraseHostOptions): Promise<EraseHostResult>;
+/**
+ * Delete a single resource document *and everything under it* (AGL-945).
+ *
+ * Firestore does not cascade: deleting `orgs/{o}/datasets/{d}` leaves every
+ * `records/{r}` beneath it alive but unreachable from the console — still
+ * billed, still matched by the rules (which match subcollection paths
+ * independently of the parent), and resurrected wholesale if the parent id
+ * is ever reused. Only the Admin SDK has `recursiveDelete`, so the console
+ * cards route their deletes through /api/resources/erase, which lands here.
+ *
+ * Authorization belongs to the caller — this only walks the tree.
+ */
+export declare function eraseSubtree(path: readonly [string, string, string, string]): Promise<void>;
+/**
+ * What an erasure did with `publisherProfiles/{orgId}` (AGL-1970).
+ *
+ * Three outcomes rather than a boolean, because the third one is a decision
+ * the audit row has to be able to state: a listing the erased org published
+ * can outlive it, and a listing whose publisher document is simply gone is
+ * unattributable in a way nobody chose.
+ */
+export type PublisherProfileDisposition = 'absent' | 'deleted' | 'tombstoned';
+/**
+ * The two things an OPERATOR needs that a served caller does not (AGL-1481).
+ *
+ * `tools/scripts/erase-tenant.mjs` is the manual path staff reach for when the
+ * cron is stuck. It used to be a second implementation of this function, and it
+ * drifted: by the time AGL-1481 was filed it was missing four sweeps added that
+ * week and still wrote a complete dump of the workspace to the operator's
+ * working directory. The fix is that it CALLS this function — which means the
+ * capabilities it had and this function lacked have to live here instead.
+ *
+ * Neither is a hold bypass, deliberately. The script refused to run before the
+ * 7-day hold elapsed and this function refuses too; an `ignoreHold` flag would
+ * have been the easy way to keep the two paths identical and is the one
+ * difference worth preserving as a refusal on both.
+ */
+export interface EraseOrgOptions {
+    /**
+     * Count what an erasure WOULD destroy and destroy nothing. Every sweep runs
+     * its query and skips its write, so the plan is produced by the same list of
+     * sweeps that the erasure is — a separate counting pass would be exactly the
+     * second enumeration this issue removed. Nothing external is touched (no
+     * Storage, no Stripe, no Vercel, no DNS) and no audit row is written.
+     *
+     * Returns `ok: false` with `skippedReason: 'dry-run'`: `ok` means the org was
+     * erased, and a plan did not erase it. A caller that treats a plan as an
+     * erasure is the one mistake this shape has to make impossible.
+     */
+    dryRun?: boolean;
+    /**
+     * Who is answerable for this erasure, for the audit row. Defaults to the
+     * cron. A staff member running the script by hand is not the scheduler, and
+     * an erasure trail that says otherwise names the wrong actor for the single
+     * most irreversible action the platform performs.
+     */
+    actorUid?: string;
+    /**
+     * The console-side sending-domain teardown, passed through to every host
+     * this erasure destroys. See {@link EraseHostOptions.tearDownSendingDomain}.
+     *
+     * Never consulted on a dry run: a plan touches no vendor.
+     */
+    tearDownSendingDomain?: TeardownSendingDomainDriver | null;
+    /**
+     * Erase a workspace that carries NO erasure request at all (AGL-2585).
+     *
+     * ⛔ EXACTLY ONE CALLER, and the option exists so that caller has to say so
+     * out loud. `/api/admin/reap-unverified-orgs` collects workspaces created by
+     * a signup whose address was never confirmed — there is nobody to ask for an
+     * erasure, because nobody has been shown to exist. Every other path reaches
+     * this function through `erasureRequestedAt`, which is a person's decision
+     * with a seven-day hold on it, and none of them passes this.
+     *
+     * What it turns off is narrow and named: the `no-request` refusal and the
+     * hold, and nothing else. Every sweep, every audit row and `dryRun` behave
+     * identically — the caller supplies the proof that this workspace is
+     * nobody's, and this records WHAT that proof was on the audit row.
+     *
+     * It does not skip the request when one exists. An org somebody has already
+     * asked to erase is still that person's decision, and the reaper refuses
+     * such an org before it ever gets here.
+     */
+    withoutRequest?: {
+        reason: string;
+    } | null;
+}
+export interface EraseOrgResult {
+    ok: boolean;
+    /**
+     * Set when the org was NOT erased (flag missing, hold not elapsed, gone) —
+     * and `'dry-run'` when nothing was erased because nothing was meant to be.
+     */
+    skippedReason?: string;
+    hosts?: number;
+    /** Member back-references cleaned up — reported so a plan can show them. */
+    members?: number;
+    /** API credentials destroyed (AGL-1444) — outside the org path. */
+    apiKeys?: number;
+    /**
+     * What each plugin's workspace eraser did (AGL-2978), keyed by plugin id:
+     * counts and flags, such as grants revoked at a provider. The erasers run
+     * before anything below is deleted. **`null` means that plugin's eraser
+     * failed** and its share may not be done; it is not zero. A plan carries
+     * each eraser's count of what it would do.
+     */
+    plugins?: Record<string, PluginOrgErasureReport | null>;
+    /** Outreach mailbox grants destroyed (AGL-2974) — outside the org path. */
+    outreachMailboxCredentials?: number;
+    /** Public SSO routing docs destroyed (AGL-1448) — outside the org path. */
+    ssoDomains?: number;
+    /** Custom console domains released (AGL-1448) — outside the org path. */
+    consoleDomains?: number;
+    /** REST API replay keys destroyed (AGL-1448) — no TTL reaps these. */
+    apiIdempotency?: number;
+    /** Local Stripe reverse-index rows destroyed (AGL-1448/AGL-1028). */
+    stripeIndex?: number;
+    /** Slugs released — the current one AND every tombstone (AGL-1448). */
+    slugs?: number;
+    /**
+     * ORPHANED `hostIndex` rows collected (AGL-1448) — ones with no surviving
+     * `hosts` document for the per-host loop to reach them through.
+     */
+    hostIndex?: number;
+    /**
+     * `hostMemberships` projections collected (AGL-1448), including FORMER
+     * members' rows that no membership list names.
+     *
+     * `null` means the sweep could not RUN — almost always the missing
+     * `COLLECTION_GROUP` index on `hostMemberships.orgId`. Deliberately not
+     * `0`: an erasure that could not reach a collection must not report the
+     * same number as one that reached it and found nothing.
+     */
+    hostMemberships?: number | null;
+    /** Marketplace handle reservations released (AGL-1970) — id-keyed, public. */
+    publisherHandles?: number;
+    /** What became of the org's public publisher profile (AGL-1970). */
+    publisherProfile?: PublisherProfileDisposition;
+    /**
+     * Marketplace listings that OUTLIVE this erasure and still name the org
+     * (AGL-1970/AGL-1448 Tier 3). Reported rather than deleted: an erasure that
+     * leaves something standing has to say so, and this is the number that makes
+     * the parked listing-survival decision cost something measurable.
+     */
+    listingsRetained?: number;
+    /**
+     * Support threads destroyed, each with its `messages` subtree (AGL-1971) —
+     * the highest-PII-density collection outside the org path.
+     */
+    supportTickets?: number;
+    /**
+     * What became of the erased sites' dedicated sending domains.
+     *
+     * `deferred` is the number an operator reads: those provider slots and zone
+     * records are still held, the debt is on each label claim, and
+     * `/api/admin/reap-sending-domains` is what settles them. The erasure itself
+     * is complete either way — a vendor outage may delay a slot's release and
+     * may not delay a deletion somebody has a legal right to.
+     */
+    sendingDomains?: {
+        released: number;
+        deferred: number;
+        /** Shared pool members refused. Always 0; a non-zero is a real alarm. */
+        protected: number;
+    };
+}
+/**
+ * Permanently erase an organization once its 7-day hold has elapsed
+ * (AGL-485/487). Runs from the automated cron and the manual staff path.
+ *
+ * **Both of those are literally this function (AGL-1481).** The manual path,
+ * `tools/scripts/erase-tenant.mjs`, used to be a second implementation, and a
+ * second implementation of a cascade delete is a divergence with a schedule:
+ * within a week of `eraseOrgApiKeys`, the SSO/console-domain release and the
+ * org-keyed index sweeps landing here, the script was missing all four and
+ * reporting success without them — leaving a live API credential, live domain
+ * reservations, `orgSlugs` tombstones and the `stripeCustomers` reverse index
+ * behind an erasure a human had been told was complete. The script now calls
+ * this, and `EraseOrgOptions` is where the two capabilities it had and this
+ * did not (a plan, and a named actor) live instead.
+ *
+ * Order matters and every step is defensive:
+ *   1. Re-read the org and re-verify erasureRequestedAt + hold — never
+ *      delete on a stale/cancelled request.
+ *   2. Nothing is written. This step used to persist a final JSON export of
+ *      the org and host trees to `erasures/{orgId}/…` and abort if it could
+ *      not — see the note below for why it is gone (AGL-1443).
+ *   3. Revoke the org's API credentials (AGL-1444), its public routing — SSO
+ *      domains and custom console domains (AGL-1448) — and its public
+ *      marketplace identity: the publisher profile and every handle it
+ *      reserved (AGL-1970); and destroy the OAuth grants behind its reps'
+ *      Outreach mailboxes (AGL-2974). All of them are top-level collections
+ *      keyed by something other than a path under the org, so the org-tree
+ *      delete cannot reach them; doing them before the content delete also
+ *      closes the mid-erasure window, in which a credential, a domain or a
+ *      public publisher page still resolves to a half-deleted workspace.
+ *   4. Delete each host (eraseHost), org-level Storage, the Stripe customer
+ *      AND its local reverse index, member back-references, then the org tree
+ *      and every slug the org ever held — tombstones included (AGL-1448).
+ *   5. Audit.
+ *
+ * Every ending is audited, not just the successful one (AGL-1455). A throw
+ * from any step writes an `org.erase-failed` row before re-throwing, because
+ * `erasureRequestedAt` stays set on a failure: without a record the org is
+ * retried and fails identically on every subsequent run, forever, and nothing
+ * anywhere says so.
+ *
+ * **The erasure writes no copy of the workspace (AGL-1443).** It used to
+ * persist `erasures/{orgId}/{requestedMs}.json` — and "export" understated
+ * it: `exportDocTree` recursed `listCollections()` with no bound and copied
+ * `snapshot.data()` wholesale, so the object was a complete verbatim copy of
+ * the org tree and every host tree, carrying `webhooks.secret` (a plaintext
+ * HMAC key), `orders.paymentLinkUrl` (a live bearer URL that lets its holder
+ * pay), `screens.protection.passwordHash` and `ssoDomains.token`. It landed
+ * on a prefix this function's own storage sweep does not cover, in a bucket
+ * with no lifecycle rule, so the most sensitive object the platform can
+ * produce outlived the request that deleted everything else — indefinitely,
+ * unread, and belonging to a customer who had been told their workspace was
+ * gone. Four facts decided it, and none of them is about tidiness:
+ *
+ *   - **Nothing read it.** One producer, zero consumers in the repo; the
+ *     owner's confirmation email never mentioned it.
+ *   - **A governed full copy already exists.** Firestore backups run weekly
+ *     with 14-week retention (AGL-871), so the dump added no recoverability —
+ *     only a second, ungoverned place the data lived.
+ *   - **The minimum that proves an erasure was already being written.** The
+ *     `adminAudit` row below is ids and counts, in a collection with a
+ *     retention policy. The one thing the object's NAME carried that the row
+ *     did not — which request this run fulfilled — is now `after.requestedAt`.
+ *   - **The DPA commits to "a limited period, after which deleted or
+ *     de-identified"**, which indefinite retention of a full dump sits
+ *     outside of.
+ *
+ * Two consequences are deliberate, not side effects. The export-write abort
+ * is gone with the write: there is nothing left to fail before the first
+ * delete, so an erasure can no longer be blocked by Storage. And the export
+ * was the only unbounded work in this function — it built the whole workspace
+ * in memory inside a 60-second cron, so the larger the workspace the likelier
+ * its erasure silently never happened (AGL-1455 half 1). That defect is
+ * removed by deletion rather than by a streaming exporter.
+ */
+export declare function eraseOrg(orgId: string, options?: EraseOrgOptions): Promise<EraseOrgResult>;
+/** An org that stops a person's account from being erased. */
+export interface UserErasureBlocker {
+    orgId: string;
+    orgName: string;
+    /** Whether the org still bills — the reason a human must intervene. */
+    hasLiveSubscription: boolean;
+    /** Other people who would be stranded if this org lost its owner. */
+    otherMembers: number;
+}
+export interface UserErasureCandidateOrg {
+    orgId: string;
+    orgName: string;
+    ownerUid: string | null;
+    hasLiveSubscription: boolean;
+    memberCount: number;
+}
+/**
+ * Which orgs block erasing `uid` (AGL-1140).
+ *
+ * Pure so the policy can be tested without Firestore, because the policy is
+ * the part worth arguing about — the deletion itself is mechanical.
+ *
+ * **Owning an org blocks erasure, always.** Not only when it bills, and not
+ * only when other members would be stranded. The alternative — cascading
+ * into `eraseOrg` — deletes a workspace, its sites and its data as a side
+ * effect of someone closing a personal account, and no consent given to the
+ * second act was given to the first. Blocking is recoverable; a cascade is
+ * not.
+ *
+ * A live subscription and stranded members are reported rather than gating,
+ * so the message can say WHY this org needs attention instead of a bare
+ * refusal — "transfer ownership" is useless advice if you do not know which
+ * of eleven workspaces is the problem.
+ */
+export declare function userErasureBlockers(uid: string, orgs: readonly UserErasureCandidateOrg[]): UserErasureBlocker[];
+/**
+ * An address this account holds that a SECOND account also holds, which stops
+ * the erasure until a human decides what it is.
+ *
+ * ⛔ Carries no address and no other uid. The whole question is about a second
+ * customer, and a refusal that names them — or hands back an address in the
+ * clear, which `emailDeliveries` is hashed precisely to avoid keeping —
+ * discloses the person the refusal exists to protect. The staff account page
+ * already lists this account's own addresses and marks the shared ones, so
+ * the operator has the specifics without this record carrying them.
+ */
+export interface SharedAddressBlocker {
+    /** `sha256(address)` — matches the delivery log's own key. Not readable. */
+    key: string;
+    /** Where this account got it: `primary`, `provider`, `stored`. */
+    sources: AccountAddressSource[];
+}
+/**
+ * Which of an account's addresses a second account is also known to hold.
+ *
+ * Pure, and separate from the sweep, for the same reason `userErasureBlockers`
+ * is: the policy is the arguable part. The mechanical part is deleting rows.
+ *
+ * ⚠️ `shared` is evidence in ONE direction. True proves a second holder;
+ * false only means none was found, because no lookup exists for an account
+ * holding an address through a federated provider. So this finds every case
+ * we can SEE and cannot promise there is no other — which is exactly why the
+ * sweep still tombstones every address it erases.
+ */
+export declare function sharedAddressBlockers(set: Pick<AccountAddressSet, 'addresses'>): SharedAddressBlocker[];
+export interface EraseUserResult {
+    ok: boolean;
+    /** Set when the account was NOT erased. */
+    skippedReason?: 'not-found' | 'owns-orgs' | 'shared-address';
+    /** Orgs that must be handed over or deleted first. */
+    blockers?: UserErasureBlocker[];
+    /**
+     * Addresses a second account also holds. Set with
+     * `skippedReason: 'shared-address'`, and NOTHING was erased.
+     */
+    sharedAddresses?: SharedAddressBlocker[];
+    /** What was actually removed, for the audit row and the caller's message. */
+    deleted?: {
+        subcollections: string[];
+        authRecord: boolean;
+        photo: boolean;
+        /** `profiles/{uid}` — the world-readable public identity (AGL-1970). */
+        profile: boolean;
+        /**
+         * Support messages stripped of `authorId`/`authorEmail` (AGL-1971). The
+         * threads themselves belong to the org and survive. **`null` means the
+         * redaction could not run** — not that there was nothing to redact.
+         */
+        supportMessagesRedacted: number | null;
+        /**
+         * What each plugin's eraser removed (AGL-2939), keyed by plugin id — the
+         * data a plugin keeps about the person where neither the recursive
+         * delete of the user document nor an org's cascade reaches, such as
+         * documents under each org keyed by the uid. **`null` means that
+         * plugin's eraser failed** and its data may remain; it is not zero.
+         */
+        plugins: Record<string, PluginUserErasureReport | null>;
+        /**
+         * Messages removed from `emailDeliveries/{sha256(address)}/messages` —
+         * the per-recipient delivery log. Zero for an account with no address on
+         * file, or one we never mailed.
+         *
+         * Across EVERY address the account held, not just the current primary.
+         */
+        emailDeliveries: number;
+        /**
+         * `emailIdentityIndex/{address}` rows released — the address-keyed
+         * uniqueness claims, which no `recursiveDelete` of the user can reach.
+         */
+        emailIdentityIndex: number;
+        /**
+         * How wide the address sweep actually was.
+         *
+         * ⚠️ `incomplete` is the field a compliance answer turns on: true means a
+         * source could not be read and an address the account held may have been
+         * missed, so this was not a complete erasure and must not be reported as
+         * one. Counts only — never the addresses, which is the data being erased.
+         */
+        addressSweep: {
+            /** Addresses found across the Auth record, its providers and the store. */
+            resolved: number;
+            /** Addresses the delivery sweep actually visited. */
+            erased: number;
+            /**
+             * Addresses left INTACT because a second account also holds them.
+             *
+             * Always 0 on a successful erasure: a contested address refuses the
+             * whole run before anything is destroyed. It is reported so the audit
+             * row states that rather than leaving a reader to infer it.
+             */
+            contested: number;
+            incomplete: boolean;
+        };
+    };
+}
+/**
+ * Permanently erase a person's account (AGL-1140).
+ *
+ * Nothing did this before: `eraseHost`, `eraseSubtree` and `eraseOrg` existed
+ * and no path anywhere deleted a `users/{uid}`. That was survivable while the
+ * doc held a name and a phone; AGL-1133 added a postal address, and "we have
+ * no mechanism to delete it" is a bad answer to an erasure request.
+ *
+ * `eraseOrg` is deliberately NOT the model here. An org is a workspace with
+ * one owner; a person belongs to many orgs, so erasing them must not take
+ * anything with it that outlives them.
+ *
+ * Order matters:
+ *   1. Refuse if they own an org — see `userErasureBlockers`.
+ *   1b. Refuse if a second account holds one of their addresses — see
+ *      `sharedAddressBlockers`. Both refusals come before any delete, so a
+ *      blocked erasure leaves the account exactly as it was.
+ *   2. Remove their membership from every org they belong to, so no roster
+ *      keeps their email and no host projection keeps granting them access.
+ *      This runs BEFORE the profile delete: a half-erased account that still
+ *      appears on a roster is worse than one not yet started.
+ *   3. Delete the `users/{uid}` subtree, the avatar, the world-readable
+ *      `profiles/{uid}` public identity (AGL-1970), redact their name and
+ *      email off every support message they wrote (AGL-1971), then the auth
+ *      record last — once that is gone there is no uid to retry with.
+ */
+export declare function eraseUser(uid: string): Promise<EraseUserResult>;