--- title: Personal Data and GDPR description: "Declare personal data on your models, then answer access and erasure requests, enforce retention, and generate the processing register from those declarations." --- # Personal Data and GDPR Stacks handles data-subject requests from declarations on your models. You mark which attributes are personal data and say, per model, whose data the rows are, what erasure does to them and how long they are kept. Access exports, erasure, retention pruning and the processing register all read those same declarations, so the register cannot describe behaviour the application does not have. Cookie consent is the other half, covered by `` and `useCookieConsent` in `@stacksjs/composables`. ## Declare personal data Two declarations, both on the model: - `personal` on an attribute marks the column as personal data. An access export includes it, and erasure and retention anonymize it. - `traits.gdpr` on the model says whose data the rows are, what erasure does, how long rows are kept, and why they are held at all. ```ts // app/Models/Order.ts import { defineModel } from '@stacksjs/orm' import { schema } from '@stacksjs/validation' export default defineModel({ name: 'Order', table: 'orders', belongsTo: ['Customer'], traits: { gdpr: { subject: { via: 'Customer' }, erasure: 'anonymize', basis: 'legal_obligation', purpose: 'Order fulfilment, kept for tax and accounting', retention: { days: 3650, action: 'anonymize' }, }, }, attributes: { deliveryAddress: { personal: true, validation: { rule: schema.string() } }, totalAmount: { validation: { rule: schema.number() } }, }, } as const) ``` ### `personal` `personal: true`, or the options form: | Option | Effect | |---|---| | `anonymize` | The value anonymization writes. Defaults to `NULL` for a nullable column, and to a placeholder of the column's type for a `NOT NULL` one: `'[erased]'`, `erased-` when the column is also unique, `0`, `false` or `'{}'`. A `NOT NULL` enum or timestamp has no safe placeholder, so it must say. | | `export` | `false` leaves the column out of access exports while erasure still clears it. The built-in `User.password` uses this. | ### `traits.gdpr` | Key | Meaning | |---|---| | `subject` | Whose data a row is. Left out, it is derived: `id` on the `User` model, and the foreign key of a `belongsTo: ['User']` everywhere else. | | `erasure` | `'anonymize'` (the default), `'delete'`, or `'keep'` for records the law requires you to retain. | | `retention` | `{ days, column?, action? }`. Rows whose `column` (default `created_at`) is older than `days` are deleted (the default) or anonymized. | | `basis` | The lawful basis: `consent`, `contract`, `legal_obligation`, `vital_interests`, `public_task` or `legitimate_interests`. | | `purpose` | Why the data is processed, in a sentence. | `subject` takes one of these forms: | Form | Matches rows where | |---|---| | `'user_id'` or `['referrer_id', 'referred_user_id']` | any named column holds the subject's user id | | `{ column: 'tokenable_id', where: { tokenable_type: 'users' } }` | the column matches and the fixed values hold, for polymorphic owners | | `{ via: 'Customer' }` | the `belongsTo` parent row is the subject's. Chains, so `OrderItem` can go via `Order` via `Customer` | | `{ email: 'recipient' }` | the column holds the subject's email address, for ledgers keyed by address rather than account | A model with no subject (a request log keyed by IP, say) is out of reach of access and erasure, but retention still applies to it and the register lists it. A declaration that cannot be honoured is an error rather than a guess. A personal `NOT NULL` enum with no `anonymize` value, a `via` naming a model that is not in `belongsTo`, or a subject with no personal attributes and the default `'anonymize'` all stop every request until fixed, with each problem named by model. ### Built-in models The framework's own models ship with declarations: `User`, `Customer`, `Order`, `Payment`, `Subscriber`, `Comment`, `ConsentEvent`, `SocialAccount`, `PersonalAccessToken` and the rest of the models that hold personal data. Run `buddy gdpr:register --stdout` to see all of them. None of them declares a retention policy, since pruning data an app already holds is a decision for that app, so override the model in `app/Models/` to add one. Records the business must keep are anonymized rather than deleted: orders, payments and transactions keep their amounts and lose the address, card digits and billing email. Consent records and suppression lists are kept, because proving consent and honouring an opt-out both need the address. ## Access requests ```bash buddy gdpr:export ada@example.com --out ada.json # by email, id or uuid ``` ```ts import { exportSubjectData } from '@stacksjs/orm' const result = await exportSubjectData(user.id, { actor: 'support' }) // { subject, generatedAt, data: { User: [...], Order: [...] }, processing: { Order: { purpose, basis, retentionDays } } } ``` Each model's rows carry only the declared personal columns plus the row's `id`, `uuid` and timestamps, so a column added later is not exported until someone classifies it. Only the subject's rows are included. Signed-in users can download their own export from `GET /me/data-export`, which is in the default `auth` route bundle, needs authentication, and is limited to three requests an hour. The subject is always the caller. ## Erasure ```bash buddy gdpr:erase ada@example.com --dry-run # print exactly what would change buddy gdpr:erase ada@example.com # asks for confirmation buddy gdpr:erase 42 --yes # non-interactive ``` ```ts import { eraseSubject } from '@stacksjs/orm' const preview = await eraseSubject(42, { dryRun: true }) const result = await eraseSubject(42, { actor: 'support' }) ``` Per model, erasure deletes, anonymizes or keeps the subject's rows as declared, children before parents and the `User` row last. It runs in one transaction with its audit row, so an erasure is either complete and recorded or neither. It only writes rows it has already matched to the subject, a dry run reads the same rows and writes nothing, and a second run finds nothing left to change. After the transaction commits, the subject's API tokens are revoked and their sessions destroyed. Pass `revokeCredentials: false` to skip that. A table a model declares that this database does not have (a framework default your app never migrated) is reported as skipped rather than failing the request. ## Retention ```bash buddy gdpr:prune --dry-run buddy gdpr:prune ``` `PruneRetainedDataJob` runs the same thing daily at 03:30. Ages are compared as dates, so a policy of 30 days removes rows older than exactly 30 days whichever timestamp format the column holds. Each run that changes something writes one audit row. ## The audit ledger Every access export, every erasure, and every retention run that changed rows writes a row to `gdpr_requests` (the `GdprRequest` model): the type, the subject id, who asked, and per-model counts. It holds no personal values, and it has no foreign key to `users`, because the record of erasing someone has to outlive their row. Run `buddy migrate` to create it. ## The processing register ```bash buddy gdpr:register # writes database/processing-register.md buddy gdpr:register --format json # database/processing-register.json buddy gdpr:register --stdout buddy gdpr:register:check # fails when the committed copy is stale ``` The register lists every model that declares personal data or a `gdpr` trait: its table, subject link, personal columns, erasure behaviour, retention, lawful basis and purpose. It is byte-stable, with no timestamp and everything sorted, so you can commit it and run `gdpr:register:check` in CI. It also lists models that belong to a user but declare nothing, under **Unclassified**. Access and erasure do not reach those models, so classify each one, even if only as `erasure: 'keep'`.