@lunora/privacy 0.0.0-stage → 1.0.0-alpha.1

package/dist/packem_shared/define.d-B0cbIvBs.d.mts

@@ -0,0 +1,368 @@
+import { b as RetainDirective, R as RetentionRule, P as PrivacyPreset } from "./rules.d-DJa3SIb3.mjs";
+/** One problem the coverage check found. */
+interface CoverageProblem {
+  /** `unclassified`: no dataset and no exclusion. `excluded_without_reason`: excluded with a blank reason. */
+  readonly code: "excluded_without_reason" | "unclassified";
+  readonly table: string;
+}
+/** The better-auth tables `authDataset()` covers when no table is renamed. */
+declare const AUTH_DEFAULT_TABLES: readonly ["account", "apikey", "member", "passkey", "session", "teamMember", "twoFactor", "user"];
+/**
+ * Which GDPR articles a dataset's export falls under. One export serves both
+ * Art. 15 (access, every origin) and Art. 20 (portability, data the subject
+ * provided, on consent or contract, by automated means).
+ */
+/** Where a dataset's data came from. */
+type DataOrigin = "provided" | "observed" | "derived" | "inferred";
+/** The Art. 6(1) basis the data is processed on. */
+type LegalBasis = "consent" | "contract" | "legal_obligation" | "legitimate_interest";
+/** When a dataset is handled. Erasure runs `quiesce` first, so nothing writes behind it. */
+type DatasetPhase = "quiesce" | "erase" | "tombstone";
+/** Which shard holds the subject's rows. */
+type DatasetPlacement = "subject" | "root" | "global";
+/** What erasure does to one table. */
+type TableErasure = "delete" | "anonymise" | RetainDirective;
+/** How one table in a dataset is treated. */
+interface TableSpec {
+  /** Defaults to `delete`. */
+  readonly erase?: TableErasure;
+  /** Columns left out of the export, such as internal bookkeeping. */
+  readonly omit?: ReadonlyArray<string>;
+  /** Overrides the dataset's origin for this table. */
+  readonly origin?: DataOrigin;
+}
+/** The description a module writes for its dataset. */
+interface DatasetSpec {
+  /**
+   * Object-storage files the subject owns. `prefix` returns the key prefix of one subject's
+   * files; it must be specific to that subject, because erasure deletes everything under it.
+   */
+  readonly files?: {
+    readonly prefix: (subjectId: string) => string;
+  };
+  readonly legalBasis: LegalBasis;
+  readonly origin: DataOrigin;
+  readonly phase?: DatasetPhase;
+  readonly placement?: DatasetPlacement;
+  readonly purpose: string;
+  readonly recipients?: ReadonlyArray<string>;
+  readonly tables: Readonly<Record<string, TableSpec>>;
+}
+/** A validated dataset, ready for the coverage check and the workflows. */
+interface Dataset extends DatasetSpec {
+  readonly id: string;
+  readonly phase: DatasetPhase;
+  readonly placement: DatasetPlacement;
+  readonly recipients: ReadonlyArray<string>;
+  /** The tables this dataset covers, by bare name. */
+  readonly tableNames: ReadonlyArray<string>;
+}
+/**
+ * Validate and freeze a dataset. Refuses an empty purpose, a dataset with no
+ * tables, and an id that is not a plain identifier, so the Art. 30 draft and the
+ * workflow step names stay well formed.
+ */
+declare const defineDataset: (id: string, spec: DatasetSpec) => Dataset;
+/** Rows per table per call. A drain step never erases more, so one step stays inside the platform's limits. */
+declare const ERASE_BATCH = 100;
+/** What happens to a row when its table is erased. */
+type Disposition = {
+  readonly kind: "delete";
+} | {
+  readonly kind: "anonymise";
+} | {
+  readonly kind: "keep";
+  readonly until: Date;
+};
+/** The package's verdict for one row, which the app's `eraseBatch` applies. */
+type RowDisposition = (dataset: Dataset, table: string, row: {
+  readonly [column: string]: unknown;
+}, now: Date) => Disposition;
+/**
+ * Bind the presets' retention rules into the verdict `eraseBatch` receives. A table with no
+ * `erase` is deleted, `delete` and `anonymise` apply as written, and a `retain` directive keeps
+ * the row while its rule's period is running.
+ */
+declare const dispositionFor: (rules: ReadonlyMap<string, RetentionRule>) => RowDisposition;
+/**
+ * The statuses a privacy request moves through, and which of them are terminal.
+ *
+ * `@lunora/privacy` stores them and the Studio's Privacy requests page renders them.
+ * The Studio must not depend on the runtime package, so both read the list from here
+ * and the bundler inlines it into each. A status added here reaches both, and the
+ * Studio's exhaustive badge map fails to compile until it has a variant.
+ */
+/** Every status, in lifecycle order. */
+declare const REQUEST_STATUSES: readonly ["received", "grace", "processing", "ready", "completed", "failed", "cancelled", "expired"];
+type RequestStatus = (typeof REQUEST_STATUSES)[number];
+type RequestType = "erasure" | "export";
+declare const isTerminal: (status: RequestStatus) => boolean;
+/** A request as the service sees it. */
+interface RequestRecord {
+  readonly dueAt: Date;
+  readonly erasureGraceUntil?: Date;
+  /** When the archive stops being downloadable. */
+  readonly expiresAt?: Date;
+  readonly extendedDueAt?: Date;
+  readonly id: string;
+  readonly reason?: string;
+  readonly receivedAt: Date;
+  readonly status: RequestStatus;
+  /** Where the finished archive is kept, once the request is ready. */
+  readonly storageKey?: string;
+  readonly subjectId: string;
+  readonly type: RequestType;
+}
+/** The storage the service needs. The app implements it over `ctx.db`. */
+interface RequestStore {
+  addEvent: (requestId: string, at: Date, kind: string, detail?: string) => Promise<void>;
+  /**
+   * Apply the patch only if the request still holds `from`, and report whether it did. The host must
+   * make the check and the write one step, so two callers that both read `from` cannot both win.
+   */
+  claim: (id: string, from: RequestStatus, patch: Partial<Omit<RequestRecord, "id">>) => Promise<boolean>;
+  /** The subject's request of this type that is not yet terminal, if any. */
+  findOpen: (subjectId: string, type: RequestType) => Promise<RequestRecord | undefined>;
+  get: (id: string) => Promise<RequestRecord | undefined>;
+  insert: (record: RequestRecord) => Promise<void>;
+  /** Every request of the subject, in every status. Erasure deletes the files each one wrote. */
+  listForSubject: (subjectId: string) => Promise<ReadonlyArray<RequestRecord>>;
+  /** Every request that is not yet terminal, for the deadline sweep. */
+  listOpen: () => Promise<ReadonlyArray<RequestRecord>>;
+  update: (id: string, patch: Partial<Omit<RequestRecord, "id">>) => Promise<void>;
+}
+/** Inputs that come from the caller and the app's settings. */
+interface ErasureSettings {
+  readonly drainBudgetDays: number;
+  /** The sign-in window an erasure needs, in milliseconds. Account deletion uses 24 hours. */
+  readonly freshAgeMs: number;
+  readonly graceDays: number;
+}
+/**
+ * The storage the tombstones need. Keep it outside the database a restore rolls back: a tombstone
+ * restored away with the data it guards would let the restore bring the erased subject back.
+ */
+interface TombstonePort {
+  /**
+   * Record that the subject was erased at this time. Must be an idempotent upsert keyed by `key`:
+   * a workflow step that fails after the write is retried and writes the same tombstone again, and a
+   * second row for one key must not appear.
+   */
+  readonly add: (key: string, erasedAt: Date) => Promise<void>;
+  /** Every tombstone key on record. */
+  readonly keys: () => Promise<ReadonlySet<string>>;
+}
+/** The app's data, one dataset at a time. The app implements it over its tables. */
+interface DataPort {
+  /** The subject's rows for each table of the dataset, keyed by table name. */
+  readonly collect: (dataset: Dataset, subjectId: string) => Promise<Readonly<Record<string, ReadonlyArray<Readonly<Record<string, unknown>>>>>>;
+  /**
+   * Erase one batch of the dataset's rows for the subject. The package decides and the app
+   * writes: call `disposition` for each row, then delete a `delete` row, anonymise an
+   * `anonymise` row, and move a `keep` row into the archive table. A kept row must not be
+   * selected again, or the drain never finishes.
+   */
+  readonly eraseBatch: (dataset: Dataset, subjectId: string, now: Date, disposition: RowDisposition) => Promise<{
+    readonly hasMore: boolean;
+  }>;
+  /**
+   * Rows still present per table after erasure, for the verify step. Two kinds of row may be
+   * counted and are excluded from the verdict by the package: a row a retention rule still keeps
+   * (verify judges each one again through `collect`), and every row of an `anonymise` table, which
+   * stays in place once anonymised. Prefer not to count anonymised rows at all; the package cannot
+   * tell an anonymised row from one `eraseBatch` missed, so it does not hold them against the erasure.
+   */
+  readonly remaining: (dataset: Dataset, subjectId: string) => Promise<Readonly<Record<string, number>>>;
+}
+/**
+ * Where a request's files are kept between steps and in the end. `put` must key a request's
+ * files under `${requestId}/`, so listing that prefix finds every file the request wrote.
+ */
+interface StorePort {
+  /** Remove one stored object. Removing a key that is not there is not an error. */
+  readonly delete: (key: string) => Promise<void>;
+  /** The keys of every stored object whose key starts with the prefix. */
+  readonly list: (prefix: string) => Promise<ReadonlyArray<string>>;
+  readonly put: (requestId: string, file: {
+    readonly data: Uint8Array | string;
+    readonly name: string;
+  }) => Promise<string>;
+  /** The text of a file written earlier in the same request, or `undefined` if it is not there. */
+  readonly read: (requestId: string, name: string) => Promise<string | undefined>;
+  /** A short-lived link to a stored file. The caller decides the lifetime, and the link is checked by the host. */
+  readonly signedUrl: (key: string, ttlSeconds: number) => Promise<string>;
+}
+/**
+ * The archive of rows erasure kept under a retention rule (`privacy_archive`, or the app's own
+ * table). The app writes a `keep` row into it with the `until` its disposition carries as
+ * `retainUntil`; the sweep purges it once that date has passed.
+ */
+interface ArchivePort {
+  /**
+   * Delete up to `ERASE_BATCH` archived rows whose `retainUntil` is before `before`, and say how
+   * many it deleted and whether more may remain.
+   */
+  readonly purgeBatch: (before: Date) => Promise<{
+    readonly hasMore: boolean;
+    readonly purged: number;
+  }>;
+}
+/** The ports one invocation binds: the app's data, storage, requests and clock. */
+interface PrivacyPorts {
+  /** Where kept rows wait out their retention period. Required for `admin.sweep` once a dataset uses `retain`. */
+  readonly archive?: ArchivePort;
+  readonly data: DataPort;
+  readonly files: StorePort;
+  readonly newId: () => string;
+  readonly now: () => Date;
+  readonly store: RequestStore;
+  /**
+   * Where erased subjects are tombstoned, so a restored backup can be erased again. An erasure and
+   * `restore` refuse to run without it; a call that only exports or reads may leave it out.
+   */
+  readonly tombstones?: TombstonePort;
+}
+/**
+ * How a run executes its named steps. A durable host memoises each `do` by name and retries a step
+ * that throws, so every step result is JSON-safe. `sleepUntil` is the host's durable sleep; the
+ * one-call path has none, so it refuses an erasure that is still inside its grace window.
+ */
+interface StepRunner {
+  readonly do: <T>(name: string, run: () => Promise<T>) => Promise<T>;
+  readonly sleepUntil?: (name: string, when: Date) => Promise<void>;
+}
+/** The outcome of an export run. */
+interface ExportOutcome {
+  readonly archiveKey?: string;
+  readonly status: RequestStatus;
+}
+/** The outcome of an erasure run. */
+interface ErasureOutcome {
+  readonly leftover: ReadonlyArray<string>;
+  readonly status: RequestStatus;
+}
+/** The app's erasure settings. An unset field takes the decided default (D3 and the sign-in window). */
+type ErasureOptions = Partial<ErasureSettings>;
+/**
+ * The authenticated subject of a call. The app resolves it from its session, never from a request
+ * argument, and passes it as the second argument of `privacyFor(ctx, identity)`, so a caller cannot
+ * act on another subject's data by naming them. An operator call, a cron or a workflow passes none.
+ */
+interface PrivacyIdentity {
+  readonly sessionAgeMs: number;
+  readonly subjectId: string;
+}
+/**
+ * Everything `definePrivacy` needs from the app. The ports depend on the invocation: a
+ * mutation's `ctx.db` exists only inside that call, so `ports` runs once per call with
+ * the caller's context.
+ */
+interface PrivacyConfig<C> {
+  readonly datasets: ReadonlyArray<Dataset>;
+  readonly erasure?: ErasureOptions;
+  /** Tables left out of the export and erasure, each with the reason the reviewer reads. */
+  readonly exclude?: Readonly<Record<string, string>>;
+  readonly ports: (context: C) => PrivacyPorts;
+  readonly presets?: ReadonlyArray<PrivacyPreset>;
+  /** The identifier the archive shows for the subject. Defaults to the subject id itself. */
+  readonly subjectKey?: (subjectId: string) => string;
+  /**
+   * The HMAC secret tombstone keys are derived with. Every erasure and `restore` refuse to run
+   * without it and without a `tombstones` port. Keep it in a secret binding, and keep it stable,
+   * because a new secret no longer matches the tombstones already written.
+   */
+  readonly tombstoneSecret?: string;
+}
+/**
+ * Binds an invocation's context, and the caller's identity when the caller is a data subject, into
+ * the API: `privacyFor(ctx, identity).requestExport()`. The subject methods refuse a call bound
+ * without an identity; the operator methods and the workflows never read it.
+ */
+type PrivacyFor<C> = (context: C, identity?: PrivacyIdentity) => Privacy;
+/** The step surface a Workflow handler receives. Matches the native `WorkflowStep` methods the package uses. */
+interface PrivacyWorkflowContext {
+  readonly params: {
+    readonly requestId: string;
+  };
+  readonly step: Required<StepRunner>;
+}
+/** The bound API. */
+interface Privacy {
+  /** Operator views and actions. Each one is for the operator's own console, not the subject. */
+  readonly admin: {
+    /**
+     * Extend a request's deadline by the policy's further months (Art. 12(3) sentence 2). Extension
+     * is the controller's decision, so it is an operator action: once per request, within the first
+     * period, with the reasons the controller must give the subject.
+     */
+    readonly extend: (requestId: string, reason: string) => Promise<RequestRecord>;
+    /** Every request that is not yet terminal. */
+    readonly open: () => Promise<ReadonlyArray<RequestRecord>>;
+    /**
+     * Retry a failed export or erasure; any other status is refused. The Art. 12(3) clock keeps
+     * running throughout. An export runs again in this call and returns `ran` with its outcome. An
+     * erasure is moved to `processing` in this call and returns `restart`: the app then starts its
+     * erasure workflow for the request, in the same mutation, and the workflow resumes it. Because
+     * the request leaves `failed` here, a second retry is refused rather than starting a second run.
+     */
+    readonly retry: (requestId: string) => Promise<RetryResult>;
+    /**
+     * The housekeeping sweep. Run it from a cron. It expires every ready export past its download
+     * window (its files go first, then it is marked `expired`), and it purges every archived row
+     * whose retention period has ended through the `archive` port. Returns the expired requests
+     * and how many archived rows it purged.
+     */
+    readonly sweep: () => Promise<SweepResult>;
+  };
+  readonly cancelRequest: (input: {
+    requestId: string;
+  }) => Promise<RequestRecord>;
+  readonly coverage: (tables: ReadonlyArray<string>, exclusions?: Readonly<Record<string, string>>) => ReadonlyArray<CoverageProblem>;
+  /** The subject's download link for a finished export. Refused for anyone but the subject, and once expired. */
+  readonly downloadUrl: (input: {
+    requestId: string;
+  }) => Promise<string>;
+  /** Every request of the subject, in every status, newest first. A finished erasure's requests no longer carry the subject's id. */
+  readonly myRequests: () => Promise<ReadonlyArray<RequestRecord>>;
+  readonly requestErasure: () => Promise<RequestRecord>;
+  readonly requestExport: () => Promise<RequestRecord>;
+  /** Erase again any restored subject that was erased after the backup. Returns the subject ids it re-erased. */
+  readonly restore: (input: {
+    restoredSubjectIds: ReadonlyArray<string>;
+  }) => Promise<ReadonlyArray<string>>;
+  readonly runErasure: (requestId: string) => Promise<ErasureOutcome>;
+  readonly runExport: (requestId: string) => Promise<ExportOutcome>;
+  /** The deadline sweep: requests due within seven days, and those already overdue. Run it from a cron. */
+  readonly tick: () => Promise<{
+    readonly approaching: ReadonlyArray<RequestRecord>;
+    readonly overdue: ReadonlyArray<RequestRecord>;
+  }>;
+  /** The durable handlers the app registers with `defineWorkflow`. Each step is memoised by name. */
+  readonly workflows: {
+    readonly erasureHandler: (context: PrivacyWorkflowContext) => Promise<void>;
+    readonly exportHandler: (context: PrivacyWorkflowContext) => Promise<void>;
+  };
+}
+/**
+ * What `admin.retry` did: an export ran again (`ran`), or an erasure was moved out of `failed` and the
+ * app must now start its erasure workflow for `requestId` (`restart`).
+ */
+type RetryResult = {
+  readonly kind: "ran";
+  readonly outcome: ExportOutcome;
+} | {
+  readonly kind: "restart";
+  readonly requestId: string;
+};
+/** What `admin.sweep` did. */
+interface SweepResult {
+  readonly expired: ReadonlyArray<RequestRecord>;
+  /** Archived rows deleted because their retention period has ended. */
+  readonly purged: number;
+}
+/**
+ * Bind the settings into a factory. Pure construction: nothing runs until a method is
+ * called, and each call of the factory binds the ports for that invocation.
+ */
+declare const definePrivacy: <C>(config: PrivacyConfig<C>) => PrivacyFor<C>;
+export { AUTH_DEFAULT_TABLES as A, isTerminal as B, CoverageProblem as C, Dataset as D, ERASE_BATCH as E, LegalBasis as L, PrivacyConfig as P, RequestStatus as R, StorePort as S, TableErasure as T, PrivacyPorts as a, RequestType as b, RequestRecord as c, ArchivePort as d, DataOrigin as e, DataPort as f, DatasetPhase as g, DatasetPlacement as h, DatasetSpec as i, Disposition as j, ErasureOptions as k, ErasureOutcome as l, ExportOutcome as m, Privacy as n, PrivacyFor as o, PrivacyIdentity as p, PrivacyWorkflowContext as q, RequestStore as r, RetryResult as s, RowDisposition as t, SweepResult as u, TableSpec as v, TombstonePort as w, defineDataset as x, definePrivacy as y, dispositionFor as z };