user-data-rights
Implements GDPR Art. 15 (access / my-audit-log query), Art. 17 (erasure / request-deletion + cancel-deletion, plus the anonymous email-verified request-deletion-by-email + confirm-deletion-by-token flow for lockout-safe self-service, + cron cleanup with grace period), Art. 18 (restriction / restrict-account + lift-restriction), and Art. 20 (portability / async request-export → ZIP via file-foundation, Magic-Link download) as first-class HTTP handlers and cron jobs. Each domain feature opts in by calling r.applyExtension({ name: EXT_USER_DATA, entity: "<entity>", export, delete }) — the feature then orchestrates the export and forget pipelines across all registered hooks automatically. When mail-foundation and a mail-transport-* are mounted, it also sends the GDPR notifications (export ready/failed, deletion requested/executed) itself with no app callback code, rendered in each recipient’s locale. The anonymous deletion flow sends its verify mail itself through delivery. Requires user, data-retention, compliance-profiles, and sessions.
Quick example
Section titled “Quick example”From recipes-user-data-rights — the smallest working mount:
// User-Data-Rights — recipe//// How an app domain integrates the GDPR pipeline: one// (export, delete) hook per entity via EXT_USER_DATA. Forget cron, export ZIP build// and magic link delivery come entirely from user-data-rights —// the app author writes only the two hooks per entity.//// Demo domain: minimal note service. A note has (id, tenantId, authorId,// title, body). Pins:// 1. The export hook delivers note rows as a JSON snippet into the export bundle.// 2. The delete hook removes note rows during the forget-cleanup cron.// 3. An event-sourced entity needs no hand-written loop: forgetOwnRowsDeleteHook forgets// every mute the user set or received, trashed rows included.//// What is not in the recipe (see samples/apps/user-data-rights-demo// for a complete app):// - Strategy-aware delete (anonymize vs hardDelete)// - HTTP endpoints for create/list// - Compliance profile wiring + cron scheduling
import { forgetOwnRowsDeleteHook } from "@cosmicdrift/kumiko-bundled-features/user-data-rights-defaults";import { deleteMany, deriveEntityTableMeta, selectMany, updateMany,} from "@cosmicdrift/kumiko-framework/db";import { createEntity, createEntityExecutor, createTextField, defineFeature, EXT_USER_DATA, type UserDataDeleteHook, type UserDataExportHook,} from "@cosmicdrift/kumiko-framework/engine";
export const noteEntity = createEntity({ name: "note", table: "store_notes", idType: "uuid", fields: { authorId: createTextField({ personal: "ref" }), title: createTextField({ personal: false, reason: "is_business_data", required: true, maxLength: 200, }), // Plaintext on purpose: store_notes is an unmanaged direct-write store, so the // PII executor never encrypts it. Art. 17 runs through the EXT_USER_DATA // hook below instead (deletes the author's rows, or unlinks them on anonymize). body: createTextField({ personal: false, reason: "covered_by_user_data_hook", maxLength: 4000, }), },});
// Plain EntityTableMeta, NOT a branded EntityTable: store_notes is a deliberate// unmanaged direct-write store (r.storeTable below), so the forget hook may// updateMany/deleteMany it directly — the meta carries no executor-only brand.export type NoteRow = { readonly id: string; readonly authorId: string | null; readonly title: string; readonly body: string | null;};
export const notesTable = deriveEntityTableMeta(noteEntity, { source: "unmanaged" });
export const muteEntity = createEntity({ name: "mute", table: "read_udr_recipe_mutes", idType: "uuid", softDelete: true, fields: { userId: createTextField({ personal: "ref", required: true }), mutedUserId: createTextField({ personal: "ref", required: true }), },});
export const { table: mutesTable, executor: muteExecutor } = createEntityExecutor(muteEntity);
// A mute names two users; when either is erased the row goes, so no mute points at a missing user.export const forgetMutes = forgetOwnRowsDeleteHook({ entityName: "mute", table: mutesTable, executor: muteExecutor, ownerFields: ["userId", "mutedUserId"],});
export const notesFeature = defineFeature("notes", (r) => { r.requires({ features: ["user-data-rights"] }); // store_notes is a direct-write store: the forget hook below `updateMany`/ // `deleteMany`s rows WITHOUT emitting lifecycle events. r.entity would make // it a rebuildable implicit projection whose replay finds zero note events // and wipes the table (or un-forgets anonymized rows) on the next rebuild // (#498). r.storeTable keeps the DDL, opts out of implicit rebuild. r.storeTable(notesTable, { reason: "read_side.notes_direct_write", });
const exportNotes: UserDataExportHook = async (ctx) => { const rows = await selectMany<NoteRow>(ctx.db, notesTable, { tenantId: ctx.tenantId, authorId: ctx.userId, }); if (rows.length === 0) return null; return { entity: "note", rows: rows.map((row) => ({ id: row.id, title: row.title, body: row.body ?? "", })), }; };
const deleteNotes: UserDataDeleteHook = async (ctx, strategy) => { const where = { tenantId: ctx.tenantId, authorId: ctx.userId }; if (strategy === "anonymize") { await updateMany(ctx.db, notesTable, { authorId: null }, where); } else { await deleteMany(ctx.db, notesTable, where); } };
r.applyExtension({ name: EXT_USER_DATA, entity: "note", export: exportNotes, delete: deleteNotes, });
r.entity(muteEntity); r.applyExtension({ name: EXT_USER_DATA, entity: "mute", delete: forgetMutes });});📄 On GitHub: samples/recipes/user-data-rights/src/feature.ts
Live preview
Section titled “Live preview”
How it fits
Section titled “How it fits”What this feature needs to run (Requires, top) and the other features’ commands this feature reads from (uses, top), and the write commands this feature provides (Provides, bottom).
flowchart TB
n_user_data_rights["user-data-rights"]
subgraph how_reqs["Requires"]
n_user["user"]
n_data_retention["data-retention"]
n_compliance_profiles["compliance-profiles"]
n_sessions["sessions"]
end
n_uses_compliance_forTenant(("compliance.forTenant"))
n_uses_retention_policyFor(("retention.policyFor"))
n_uses_sessions_revokeAllForUser(("sessions.revokeAllForUser"))
subgraph how_provides["Provides"]
n_cmd_user_data_rights_write_cancel_deletion(["cancel-deletion"])
n_cmd_user_data_rights_write_cancel_deletion_by_token(["cancel-deletion-by-token"])
n_cmd_user_data_rights_write_confirm_deletion_by_token(["confirm-deletion-by-token"])
n_cmd_user_data_rights_write_lift_restriction(["lift-restriction"])
n_cmd_user_data_rights_write_request_deletion(["request-deletion"])
n_cmd_user_data_rights_write_request_deletion_by_email(["request-deletion-by-email"])
n_cmd_more(["+3 more"])
end
n_user --> n_user_data_rights
n_data_retention --> n_user_data_rights
n_compliance_profiles --> n_user_data_rights
n_sessions --> n_user_data_rights
n_uses_compliance_forTenant -->|uses| n_user_data_rights
n_uses_retention_policyFor -->|uses| n_user_data_rights
n_uses_sessions_revokeAllForUser -->|uses| n_user_data_rights
n_user_data_rights --> n_cmd_user_data_rights_write_cancel_deletion
n_user_data_rights --> n_cmd_user_data_rights_write_cancel_deletion_by_token
n_user_data_rights --> n_cmd_user_data_rights_write_confirm_deletion_by_token
n_user_data_rights --> n_cmd_user_data_rights_write_lift_restriction
n_user_data_rights --> n_cmd_user_data_rights_write_request_deletion
n_user_data_rights --> n_cmd_user_data_rights_write_request_deletion_by_email
n_user_data_rights --> n_cmd_more
Provides — write commands this feature registers (dispatch them through the command bus):
user-data-rights:write:cancel-deletionuser-data-rights:write:cancel-deletion-by-tokenuser-data-rights:write:confirm-deletion-by-tokenuser-data-rights:write:lift-restrictionuser-data-rights:write:request-deletionuser-data-rights:write:request-deletion-by-emailuser-data-rights:write:request-exportuser-data-rights:write:restrict-accountuser-data-rights:write:run-forget-cleanup
Getting started
Section titled “Getting started”Start with recipes-user-data-rights for a step-by-step walkthrough with runnable code and integration tests.
Dependencies
Section titled “Dependencies”- Requires:
user,data-retention,compliance-profiles,sessions - Activation: always on (not toggleable)
Configuration
Section titled “Configuration”Per-tenant config keys, set via the tenant-admin UI or a seed. 🔒 = encrypted at rest.
| Key | Type | Default | Scope | Who can write | Who can read |
|---|---|---|---|---|---|
tenant-model | select (single-user | multi-user) | multi-user | system | system | TenantAdmin, Admin, SystemAdmin |
Extensions & cross-feature APIs
Section titled “Extensions & cross-feature APIs”- Exposes API:
userDataRights.runForget,userDataRights.runExport - Uses API:
compliance.forTenant,retention.policyFor,sessions.revokeAllForUser