@softure-ai/privacy 0.0.0-stage → 0.1.5

package/src/options.ts

@@ -0,0 +1,87 @@
+// The options an app passes to `privacy({ ... })` in softure.config.ts, parsed at startup.
+import type { PrivacyContributor } from "@softure-ai/core";
+import { z } from "zod";
+
+/** Kebab-case, like a module id: contributor ids are the keys of the export. */
+export const CONTRIBUTOR_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+/** A document version as the app writes it, e.g. `2026-10-01` or `1.2`. */
+export const DOCUMENT_VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z._-]{0,31}$/;
+
+const MEBIBYTE = 1024 * 1024;
+
+/** The export size limit when the app sets none. */
+export const DEFAULT_EXPORT_MAX_BYTES = 10 * MEBIBYTE;
+
+type ExportUserData = NonNullable<PrivacyContributor["exportUserData"]>;
+type DeleteUserData = NonNullable<PrivacyContributor["deleteUserData"]>;
+
+const isFunction = (value: unknown) => typeof value === "function";
+
+const appContributorSchema = z
+  .strictObject({
+    /** Names the contributor's part of the export and its log lines, e.g. `profile`. */
+    id: z.string().max(64, "must be at most 64 characters").regex(CONTRIBUTOR_ID_PATTERN, "must be kebab-case, e.g. user-profile"),
+    /** The user's data held by the app, as plain JSON values (dates become ISO strings). */
+    exportUserData: z.custom<ExportUserData>(isFunction, "must be a function").optional(),
+    /** Deletes (or anonymises) that data. An `Err` refuses the deletion of the whole account. */
+    deleteUserData: z.custom<DeleteUserData>(isFunction, "must be a function").optional(),
+  })
+  .refine((contributor) => contributor.exportUserData !== undefined || contributor.deleteUserData !== undefined, {
+    message: "needs exportUserData, deleteUserData or both",
+  });
+
+const legalDocumentSchema = z.strictObject({
+  /** Names the document in consent records and in `getLegalDocument`, e.g. `terms`. */
+  id: z.string().max(64, "must be at most 64 characters").regex(CONTRIBUTOR_ID_PATTERN, "must be kebab-case, e.g. privacy-policy"),
+  /**
+   * The version in force, stamped on every consent given to the document. Change it whenever the
+   * published text changes, e.g. to the date the new text takes effect.
+   */
+  version: z.string().regex(DOCUMENT_VERSION_PATTERN, "must be 1-32 letters, digits, '.', '_' or '-', e.g. 2026-10-01"),
+});
+
+export const privacyOptionsSchema = z
+  .strictObject({
+    /**
+     * The app's own contributors, next to the ones of its modules. They export after the modules
+     * and delete before them, so app tables that reference module tables go first.
+     */
+    contributors: z.array(appContributorSchema).default([]),
+    /** The app's legal documents (terms, privacy policy) and their current versions. */
+    documents: z.array(legalDocumentSchema).default([]),
+    export: z
+      .strictObject({
+        /** The largest export, in bytes of JSON; a larger one is refused instead of sent. */
+        maxBytes: z
+          .number()
+          .int()
+          .min(1024)
+          .max(100 * MEBIBYTE)
+          .default(DEFAULT_EXPORT_MAX_BYTES),
+        /** The download's file name before the date, e.g. `account-data-2026-10-03.json`. */
+        fileName: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/, "must be 1-64 lowercase letters, digits or -").default("account-data"),
+      })
+      .prefault({}),
+  })
+  .superRefine((options, context) => {
+    const seen = new Set<string>();
+    options.contributors.forEach((contributor, index) => {
+      if (seen.has(contributor.id)) {
+        context.addIssue({ code: "custom", path: ["contributors", index, "id"], message: `"${contributor.id}" is registered twice` });
+      }
+      seen.add(contributor.id);
+    });
+    const documentIds = new Set<string>();
+    options.documents.forEach((document, index) => {
+      if (documentIds.has(document.id)) {
+        context.addIssue({ code: "custom", path: ["documents", index, "id"], message: `"${document.id}" is declared twice` });
+      }
+      documentIds.add(document.id);
+    });
+  });
+
+export type PrivacyOptionsInput = z.input<typeof privacyOptionsSchema>;
+export type PrivacyOptions = z.output<typeof privacyOptionsSchema>;
+export type AppPrivacyContributor = PrivacyOptions["contributors"][number];
+export type LegalDocumentDeclaration = PrivacyOptions["documents"][number];

package/src/schema.ts

@@ -0,0 +1,18 @@
+// Drizzle view of the module's table (migrations/0001_create_consents.sql). The migration is the
+// source of truth; this file only types the queries.
+import { users } from "@softure-ai/auth";
+import { bigint, boolean, pgSchema, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+export const privacySchema = pgSchema("privacy");
+
+export const consents = privacySchema.table("consents", {
+  id: bigint("id", { mode: "number" }).primaryKey().generatedAlwaysAsIdentity(),
+  userId: uuid("user_id").references(() => users.id, { onDelete: "cascade" }),
+  emailKey: text("email_key"),
+  purpose: text("purpose").notNull(),
+  granted: boolean("granted").notNull(),
+  documentId: text("document_id"),
+  documentVersion: text("document_version"),
+  source: text("source").notNull(),
+  recordedAt: timestamp("recorded_at", { withTimezone: true }).notNull(),
+});

package/src/server/collect.ts

@@ -0,0 +1,58 @@
+// The export: every contributor's part of one user's data, read in one transaction so the parts
+// agree with each other, and bounded in size before it is handed to a response.
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import type { PrivacyExport } from "../contract.js";
+import type { PrivacyContext } from "./context.js";
+import { getExportingContributors } from "./contributors.js";
+import { getPrivacyOptions } from "./options.js";
+
+export interface CollectedUserData {
+  readonly document: PrivacyExport;
+  /** The document as JSON, the bytes a download sends; measured against `export.maxBytes`. */
+  readonly json: string;
+}
+
+export type CollectUserDataResult = Ok<CollectedUserData> | Err<"privacy.export_failed" | "privacy.export_too_large">;
+
+/**
+ * Collects every exporting contributor's part for `userId`. A contributor's `Err` fails the whole
+ * export (`privacy.export_failed`, logged with the contributor's id and code): a file with a part
+ * missing would look complete. Thrown errors (a database failure) propagate after the rollback.
+ */
+export async function collectUserData(ctx: PrivacyContext, userId: string): Promise<CollectUserDataResult> {
+  const contributors = getExportingContributors(ctx.config);
+  const exportedAt = ctx.clock.now();
+
+  const collected = await ctx.db.transaction(
+    async (tx): Promise<Ok<Record<string, unknown>> | Err<"privacy.export_failed">> => {
+      const txCtx: PrivacyContext = { ...ctx, db: tx };
+      const data: Record<string, unknown> = {};
+      for (const contributor of contributors) {
+        const part = await contributor.exportUserData(txCtx, userId);
+        if (!part.ok) {
+          console.error(`@softure-ai/privacy: contributor "${contributor.id}" failed the export: ${part.error}`);
+          return err("privacy.export_failed");
+        }
+        data[contributor.id] = part.value;
+      }
+      return ok(data);
+    },
+    { isolationLevel: "repeatable read", accessMode: "read only" },
+  );
+  if (!collected.ok) return collected;
+
+  const document: PrivacyExport = {
+    format: "softure.privacy-export",
+    version: 1,
+    userId,
+    exportedAt: exportedAt.toISOString(),
+    data: collected.value,
+  };
+  const json = JSON.stringify(document, null, 2);
+  const { maxBytes } = getPrivacyOptions(ctx.config).export;
+  if (Buffer.byteLength(json, "utf8") > maxBytes) {
+    console.error(`@softure-ai/privacy: an export exceeded export.maxBytes (${String(maxBytes)})`);
+    return err("privacy.export_too_large");
+  }
+  return ok({ document, json });
+}

package/src/server/consents-contributor.ts

@@ -0,0 +1,48 @@
+// The privacy module's own part of a GDPR export and deletion: the consent ledger. A user's
+// consents are the rows of their account and the rows of their email address recorded before
+// the account existed (a waitlist sign-up).
+import { users } from "@softure-ai/auth";
+import { ok, type ModuleContext, type Ok, type PrivacyContributor } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { asc, eq, or, type SQL } from "drizzle-orm";
+import type { ConsentRecord } from "../contract.js";
+import { consents } from "../schema.js";
+import { getEmailKey, toConsentRecord } from "./consents.js";
+
+/** What privacy holds about one user, as it appears in their export. */
+export interface PrivacyUserData {
+  /** Every consent given or withdrawn, oldest first; `subject` says whether it names the account or its email. */
+  readonly consents: readonly (ConsentRecord & { readonly subject: "account" | "email" })[];
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The rows of the account and of its email; null when no account has this id. */
+async function matchUserConsents(db: Queryable, userId: string): Promise<SQL | null> {
+  if (!UUID.test(userId)) return null;
+  const [account] = await db.select({ email: users.email }).from(users).where(eq(users.id, userId));
+  if (account === undefined) return eq(consents.userId, userId);
+  return or(eq(consents.userId, userId), eq(consents.emailKey, getEmailKey(account.email))) ?? null;
+}
+
+export async function exportConsentUserData(context: ModuleContext, userId: string): Promise<Ok<PrivacyUserData>> {
+  // Core types `db` as unknown; privacy passes the @softure-ai/db handle or its transaction.
+  const db = context.db as Queryable;
+  const condition = await matchUserConsents(db, userId);
+  if (condition === null) return ok({ consents: [] });
+  const rows = await db.select().from(consents).where(condition).orderBy(asc(consents.recordedAt), asc(consents.id));
+  return ok({ consents: rows.map((row) => ({ ...toConsentRecord(row), subject: row.userId === null ? "email" : "account" })) });
+}
+
+/** Deletes the user's consents: with the data gone there is nothing left to prove consent for. */
+export async function deleteConsentUserData(context: ModuleContext, userId: string): Promise<Ok<undefined>> {
+  const db = context.db as Queryable;
+  const condition = await matchUserConsents(db, userId);
+  if (condition !== null) await db.delete(consents).where(condition);
+  return ok();
+}
+
+export const privacyConsentsContributor: PrivacyContributor = {
+  exportUserData: exportConsentUserData,
+  deleteUserData: deleteConsentUserData,
+};

package/src/server/consents.ts

@@ -0,0 +1,142 @@
+// The consent ledger: recording a consent or its withdrawal, and reading the current state and the
+// history of a subject. Rows are only ever inserted (the table refuses UPDATE); the current state
+// of a purpose is its latest row.
+import { createHash } from "node:crypto";
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import { and, asc, desc, eq, type SQL } from "drizzle-orm";
+import { z } from "zod";
+import type { ConsentRecord, ConsentState, ConsentSubject } from "../contract.js";
+import { CONTRIBUTOR_ID_PATTERN } from "../options.js";
+import { consents } from "../schema.js";
+import type { PrivacyContext } from "./context.js";
+import { findLegalDocument } from "./legal-documents.js";
+
+const MAX_NAME_LENGTH = 64;
+const MAX_EMAIL_LENGTH = 254;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A SHA-256 digest in unpadded base64url, the shape of every stored email key. */
+const EMAIL_KEY = /^[A-Za-z0-9_-]{43}$/;
+const emailSchema = z.email();
+
+export interface RecordConsentInput {
+  readonly subject: ConsentSubject;
+  /** What the consent is for, kebab-case, e.g. `terms` or `newsletter`. */
+  readonly purpose: string;
+  /** True to give consent, false to withdraw it (a new row; the earlier one stays as evidence). */
+  readonly granted: boolean;
+  /** The id of a document declared in `privacy({ documents })`; its configured version is recorded. */
+  readonly document?: string;
+  /** Where the consent was given, kebab-case, e.g. `registration`, `waitlist`, `account`. */
+  readonly source: string;
+}
+
+export type RecordConsentResult = Ok<ConsentRecord> | Err<"privacy.consent_invalid" | "privacy.document_unknown">;
+
+export interface ConsentQuery {
+  readonly subject: ConsentSubject;
+  readonly purpose: string;
+}
+
+/** The key an email subject is stored under: base64url SHA-256 of the trimmed, lowercased address. */
+export function getEmailKey(email: string): string {
+  return createHash("sha256").update(email.trim().toLowerCase()).digest("base64url");
+}
+
+const isName = (value: string) => value.length <= MAX_NAME_LENGTH && CONTRIBUTOR_ID_PATTERN.test(value);
+
+/** The subject's column values, or null when it cannot name anyone (not a UUID, an address or a key). */
+function toSubjectColumns(subject: ConsentSubject): { userId: string; emailKey: null } | { userId: null; emailKey: string } | null {
+  if ("userId" in subject) return UUID.test(subject.userId) ? { userId: subject.userId, emailKey: null } : null;
+  if ("emailKey" in subject) return EMAIL_KEY.test(subject.emailKey) ? { userId: null, emailKey: subject.emailKey } : null;
+  const email = subject.email.trim().toLowerCase();
+  if (email.length > MAX_EMAIL_LENGTH || !emailSchema.safeParse(email).success) return null;
+  return { userId: null, emailKey: getEmailKey(email) };
+}
+
+function matchSubject(subject: ConsentSubject): SQL | null {
+  const columns = toSubjectColumns(subject);
+  if (columns === null) return null;
+  return columns.userId === null ? eq(consents.emailKey, columns.emailKey) : eq(consents.userId, columns.userId);
+}
+
+type ConsentRow = typeof consents.$inferSelect;
+
+export function toConsentRecord(row: ConsentRow): ConsentRecord {
+  return {
+    purpose: row.purpose,
+    granted: row.granted,
+    document: row.documentId === null || row.documentVersion === null ? null : { id: row.documentId, version: row.documentVersion },
+    source: row.source,
+    recordedAt: row.recordedAt,
+  };
+}
+
+/**
+ * Records a consent at `recordedAt`. For `recordConsent` (the clock's now) and the registration
+ * hook (the account's creation time).
+ */
+export async function insertConsent(ctx: PrivacyContext, input: RecordConsentInput, recordedAt: Date): Promise<RecordConsentResult> {
+  const subject = toSubjectColumns(input.subject);
+  if (subject === null || !isName(input.purpose) || !isName(input.source)) return err("privacy.consent_invalid");
+
+  let document: { id: string; version: string } | null = null;
+  if (input.document !== undefined) {
+    const declared = findLegalDocument(ctx.config, input.document);
+    if (declared === undefined) return err("privacy.document_unknown");
+    document = { id: declared.id, version: declared.version };
+  }
+
+  const [row] = await ctx.db
+    .insert(consents)
+    .values({
+      ...subject,
+      purpose: input.purpose,
+      granted: input.granted,
+      documentId: document?.id ?? null,
+      documentVersion: document?.version ?? null,
+      source: input.source,
+      recordedAt,
+    })
+    .returning();
+  // An INSERT … RETURNING without a conflict clause returns its row or throws.
+  if (row === undefined) throw new Error("@softure-ai/privacy: recording a consent returned no row");
+  return ok(toConsentRecord(row));
+}
+
+/**
+ * Records that `subject` gave (or withdrew) consent to `purpose`, now. With `document`, the
+ * document's configured version is recorded with it. Database errors propagate.
+ */
+export function recordConsent(ctx: PrivacyContext, input: RecordConsentInput): Promise<RecordConsentResult> {
+  return insertConsent(ctx, input, ctx.clock.now());
+}
+
+/** The current state of one purpose for one subject (its latest record), or null when none was recorded. */
+export async function getConsent(ctx: PrivacyContext, query: ConsentQuery): Promise<ConsentState | null> {
+  const subject = matchSubject(query.subject);
+  if (subject === null) return null;
+  const [row] = await ctx.db
+    .select()
+    .from(consents)
+    .where(and(subject, eq(consents.purpose, query.purpose)))
+    .orderBy(desc(consents.recordedAt), desc(consents.id))
+    .limit(1);
+  if (row === undefined) return null;
+  const record = toConsentRecord(row);
+  const isCurrentVersion = record.document === null || findLegalDocument(ctx.config, record.document.id)?.version === record.document.version;
+  return { ...record, isCurrentVersion };
+}
+
+/** Whether the latest record of the purpose grants it, for the document version in force. */
+export async function hasConsent(ctx: PrivacyContext, query: ConsentQuery): Promise<boolean> {
+  const state = await getConsent(ctx, query);
+  return state !== null && state.granted && state.isCurrentVersion;
+}
+
+/** Every record of the subject, oldest first: the evidence of what was given and withdrawn, when. */
+export async function listConsents(ctx: PrivacyContext, subject: ConsentSubject): Promise<ConsentRecord[]> {
+  const condition = matchSubject(subject);
+  if (condition === null) return [];
+  const rows = await ctx.db.select().from(consents).where(condition).orderBy(asc(consents.recordedAt), asc(consents.id));
+  return rows.map(toConsentRecord);
+}

package/src/server/context.ts

@@ -0,0 +1,5 @@
+import type { ModuleContext } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+
+/** What the privacy server functions receive; contributors get the same with `db` as a transaction. */
+export type PrivacyContext = ModuleContext<Queryable>;

package/src/server/contributors.ts

@@ -0,0 +1,58 @@
+// The registry: every part of a user's data the app holds, as contributors. The enabled modules
+// contribute through `defineModule({ privacy })` (core checks it against their manifest), the app
+// through `privacy({ contributors })`. Nothing is listed by hand, so a module enabled in the config
+// is in the export and the deletion by being enabled.
+import type { PrivacyContributor, SoftureConfig } from "@softure-ai/core";
+import { getPrivacyOptions } from "./options.js";
+
+export interface RegisteredContributor extends PrivacyContributor {
+  /** A module id or an app contributor id; the key of its part of the export. */
+  readonly id: string;
+  readonly source: "module" | "app";
+}
+
+export type ExportingContributor = RegisteredContributor & Required<Pick<PrivacyContributor, "exportUserData">>;
+export type DeletingContributor = RegisteredContributor & Required<Pick<PrivacyContributor, "deleteUserData">>;
+
+const registries = new WeakMap<SoftureConfig, readonly RegisteredContributor[]>();
+
+/**
+ * Every contributor in export order: the modules in the config's dependency order (dependencies
+ * first), then the app's in the order it lists them. Throws when an app contributor takes the id of
+ * an enabled module: both parts would land under one key.
+ */
+export function getPrivacyContributors(config: SoftureConfig): readonly RegisteredContributor[] {
+  const cached = registries.get(config);
+  if (cached !== undefined) return cached;
+
+  const modules: RegisteredContributor[] = config.modules.flatMap((module) =>
+    module.privacy === null ? [] : [{ ...module.privacy, id: module.id, source: "module" as const }],
+  );
+  const moduleIds = new Set(config.modules.map((module) => module.id));
+  const app: RegisteredContributor[] = getPrivacyOptions(config).contributors.map((contributor) => {
+    if (moduleIds.has(contributor.id)) {
+      throw new Error(`@softure-ai/privacy: app contributor "${contributor.id}" has the id of an enabled module; give it another id`);
+    }
+    return { ...contributor, source: "app" as const };
+  });
+
+  const registry = Object.freeze([...modules, ...app]);
+  registries.set(config, registry);
+  return registry;
+}
+
+/** The contributors with an export, in export order. */
+export function getExportingContributors(config: SoftureConfig): readonly ExportingContributor[] {
+  return getPrivacyContributors(config).filter((contributor): contributor is ExportingContributor => contributor.exportUserData !== undefined);
+}
+
+/**
+ * The contributors with a deletion, in deletion order: the reverse of the export order. The app's
+ * own data goes first, then each module before the modules it depends on, so a row is always
+ * deleted before the rows it references, whatever the foreign key's ON DELETE action.
+ */
+export function getDeletingContributors(config: SoftureConfig): readonly DeletingContributor[] {
+  return getPrivacyContributors(config)
+    .filter((contributor): contributor is DeletingContributor => contributor.deleteUserData !== undefined)
+    .toReversed();
+}

package/src/server/erase.ts

@@ -0,0 +1,42 @@
+// The deletion: every contributor deletes its part of one user's data, in one transaction and in
+// deletion order (the app's data first, auth's account last). A refusal or a failure anywhere
+// rolls back every contributor: an account is deleted whole or not at all.
+import { err, ok, type Err, type ErrorCode, type Ok } from "@softure-ai/core";
+import type { PrivacyContext } from "./context.js";
+import { getDeletingContributors } from "./contributors.js";
+
+export type EraseUserDataResult = Ok<undefined> | Err<"privacy.deletion_refused">;
+
+/** Thrown inside the transaction to roll it back when a contributor refuses. */
+class DeletionRefusal extends Error {
+  constructor(
+    readonly contributorId: string,
+    readonly code: ErrorCode,
+  ) {
+    super(`contributor "${contributorId}" refused the deletion: ${code}`);
+    this.name = "DeletionRefusal";
+  }
+}
+
+/**
+ * Deletes everything the app holds about `userId`. A contributor that must keep data (legal
+ * retention) returns an `Err`: nothing is deleted, the result is `privacy.deletion_refused`, and
+ * the contributor's id and code are logged. Thrown errors propagate after the rollback.
+ */
+export async function eraseUserData(ctx: PrivacyContext, userId: string): Promise<EraseUserDataResult> {
+  const contributors = getDeletingContributors(ctx.config);
+  try {
+    await ctx.db.transaction(async (tx) => {
+      const txCtx: PrivacyContext = { ...ctx, db: tx };
+      for (const contributor of contributors) {
+        const result = await contributor.deleteUserData(txCtx, userId);
+        if (!result.ok) throw new DeletionRefusal(contributor.id, result.error);
+      }
+    });
+  } catch (error) {
+    if (!(error instanceof DeletionRefusal)) throw error;
+    console.warn(`@softure-ai/privacy: ${error.message}; nothing was deleted`);
+    return err("privacy.deletion_refused");
+  }
+  return ok();
+}

package/src/server/health.ts

@@ -0,0 +1,12 @@
+// The module's readiness probe for `GET /api/health` of `@softure-ai/ops`: the consents table
+// exists and answers, i.e. `softure migrate` ran. It reads no rows.
+import { ok, type HealthCheck } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { sql } from "drizzle-orm";
+
+export const checkConsentsTable: HealthCheck = async (context) => {
+  // Core types `db` as unknown; the health route passes the @softure-ai/db handle.
+  const db = context.db as Queryable;
+  await db.execute(sql`select 1 from privacy.consents limit 0`);
+  return ok();
+};

package/src/server/index.ts

@@ -0,0 +1,41 @@
+// Server-only API of @softure-ai/privacy. Every function receives the module context
+// (`{ db, clock, config }`) and never reads request scope; the user id comes in as a value.
+export {
+  getConsent,
+  getEmailKey,
+  hasConsent,
+  listConsents,
+  recordConsent,
+  type ConsentQuery,
+  type RecordConsentInput,
+  type RecordConsentResult,
+} from "./consents.js";
+export {
+  deleteConsentUserData,
+  exportConsentUserData,
+  privacyConsentsContributor,
+  type PrivacyUserData,
+} from "./consents-contributor.js";
+export { collectUserData, type CollectedUserData, type CollectUserDataResult } from "./collect.js";
+export type { PrivacyContext } from "./context.js";
+export {
+  getDeletingContributors,
+  getExportingContributors,
+  getPrivacyContributors,
+  type DeletingContributor,
+  type ExportingContributor,
+  type RegisteredContributor,
+} from "./contributors.js";
+export { eraseUserData, type EraseUserDataResult } from "./erase.js";
+export { findLegalDocument, getLegalDocument, getLegalDocuments } from "./legal-documents.js";
+export { getPrivacyOptions, getPrivacyRoutes, type PrivacyRoutes } from "./options.js";
+export { recordRegistrationConsent, REGISTRATION_SOURCE, type RegistrationConsentOptions } from "./registration-consent.js";
+export {
+  deleteOwnAccount,
+  exportOwnData,
+  type DeleteOwnAccountErrorCode,
+  type DeleteOwnAccountInput,
+  type DeleteOwnAccountResult,
+  type ExportOwnDataInput,
+  type ExportOwnDataResult,
+} from "./self-service.js";

package/src/server/legal-documents.ts

@@ -0,0 +1,24 @@
+// The app's legal documents and their current versions, declared once in `privacy({ documents })`:
+// consents are stamped with these versions, and legal pages show the same ones.
+import type { SoftureConfig } from "@softure-ai/core";
+import type { LegalDocumentDeclaration } from "../options.js";
+import { getPrivacyOptions } from "./options.js";
+
+/** Every declared document, in the order the config lists them. */
+export function getLegalDocuments(config: SoftureConfig): readonly LegalDocumentDeclaration[] {
+  return getPrivacyOptions(config).documents;
+}
+
+/** The declared document with this id, or undefined. */
+export function findLegalDocument(config: SoftureConfig, id: string): LegalDocumentDeclaration | undefined {
+  return getLegalDocuments(config).find((document) => document.id === id);
+}
+
+/** The declared document with this id. Throws for an id the config does not declare: a page naming one is a bug. */
+export function getLegalDocument(config: SoftureConfig, id: string): LegalDocumentDeclaration {
+  const document = findLegalDocument(config, id);
+  if (document === undefined) {
+    throw new Error(`@softure-ai/privacy: no legal document "${id}"; declare it in privacy({ documents: [{ id: "${id}", version }] })`);
+  }
+  return document;
+}

package/src/server/options.ts

@@ -0,0 +1,33 @@
+// The privacy options and routes of the running app, read from the configuration in the module context.
+import { getModule, type SoftureConfig } from "@softure-ai/core";
+import type { PrivacyOptions } from "../options.js";
+
+const MODULE_ID = "privacy";
+
+export interface PrivacyRoutes {
+  /** The page with the export link and the delete form. */
+  readonly account: string;
+  /** The export route handler. */
+  readonly export: string;
+  /** Where a deleted account lands, signed out. */
+  readonly afterDelete: string;
+}
+
+/** The enabled module. Throws when the app did not enable it: calling its functions then is a bug. */
+export function getPrivacyModule(config: SoftureConfig) {
+  const module = getModule(config, MODULE_ID);
+  if (module === undefined) {
+    throw new Error("@softure-ai/privacy: the module is not enabled; add privacy({ ... }) to modules in softure.config.ts");
+  }
+  return module;
+}
+
+export function getPrivacyOptions(config: SoftureConfig): PrivacyOptions {
+  // The module factory parsed these options with privacyOptionsSchema.
+  return getPrivacyModule(config).options as PrivacyOptions;
+}
+
+export function getPrivacyRoutes(config: SoftureConfig): PrivacyRoutes {
+  // The manifest declares exactly these routes; the factory merged the app's overrides.
+  return getPrivacyModule(config).routes as unknown as PrivacyRoutes;
+}

package/src/server/rate-limits.ts

@@ -0,0 +1,32 @@
+// The rate limit buckets privacy consumes (PRIVACY_RATE_LIMIT_BUCKETS), both counted per user.
+import { getModule, type SoftureConfig } from "@softure-ai/core";
+import { subjectKey } from "@softure-ai/security/server";
+
+export const BUCKETS = {
+  export: "privacy-export",
+  delete: "privacy-delete",
+} as const;
+
+/** The subject key of a user in the privacy buckets. */
+export function userSubjectKey(userId: string): string {
+  return subjectKey(`user:${userId}`);
+}
+
+const checkedConfigs = new WeakSet<SoftureConfig>();
+
+/**
+ * Throws, naming every missing bucket, when the app's `security({ buckets })` lacks one privacy
+ * counts in. Checked once per config, before the first attempt is counted.
+ */
+export function assertPrivacyBuckets(config: SoftureConfig): void {
+  if (checkedConfigs.has(config)) return;
+  const options = getModule(config, "security")?.options as { buckets?: Readonly<Record<string, unknown>> } | undefined;
+  const configured = options?.buckets ?? {};
+  const missing = Object.values(BUCKETS).filter((name) => !Object.hasOwn(configured, name));
+  if (missing.length > 0) {
+    throw new Error(
+      `@softure-ai/privacy: security({ buckets }) lacks ${missing.map((name) => `"${name}"`).join(", ")}; spread PRIVACY_RATE_LIMIT_BUCKETS into it`,
+    );
+  }
+  checkedConfigs.add(config);
+}

package/src/server/registration-consent.ts

@@ -0,0 +1,43 @@
+// The consent ticked at registration, recorded through auth's `onRegistered` hook: inside the
+// account's transaction, so an account never exists without the evidence of its consent.
+import type { OnRegisteredHook } from "@softure-ai/auth";
+import { getLegalDocuments } from "./legal-documents.js";
+import { insertConsent } from "./consents.js";
+
+export interface RegistrationConsentOptions {
+  /**
+   * The documents the registration checkbox accepts, by id. Defaults to every document declared
+   * in `privacy({ documents })`.
+   */
+  readonly documents?: readonly string[];
+}
+
+/** The source of the rows this hook records. */
+export const REGISTRATION_SOURCE = "registration";
+
+/**
+ * An `onRegistered` hook for `auth({ onRegistered: recordRegistrationConsent() })`: one consent row
+ * per accepted document (purpose = document id, its configured version, source `registration`),
+ * at the account's creation time. Records nothing when auth's `requireConsent` is off. Throws
+ * (rolling the registration back) when no document is declared or one is unknown: a
+ * misconfiguration must not create accounts without evidence.
+ */
+export function recordRegistrationConsent(options: RegistrationConsentOptions = {}): OnRegisteredHook {
+  return async (event, ctx) => {
+    if (event.consent === null) return;
+    const documents = options.documents ?? getLegalDocuments(ctx.config).map((document) => document.id);
+    if (documents.length === 0) {
+      throw new Error("@softure-ai/privacy: recordRegistrationConsent() has no document to record; declare them in privacy({ documents })");
+    }
+    for (const document of documents) {
+      const recorded = await insertConsent(
+        ctx,
+        { subject: { userId: event.user.id }, purpose: document, granted: true, document, source: REGISTRATION_SOURCE },
+        event.consent.acceptedAt,
+      );
+      if (!recorded.ok) {
+        throw new Error(`@softure-ai/privacy: recording the registration consent to "${document}" failed: ${recorded.error}`);
+      }
+    }
+  };
+}