@stacksjs/orm 0.75.41 → 0.75.43

package/dist/define-model.d.ts

@@ -9,6 +9,7 @@ import { type OrmModelDefinition as BQBModelDefinition, type OrmModelStatic } fr
 import type { ApiMiddleware, DashboardModelOptions } from '@stacksjs/types';
 import type { BelongsToForeignKeys } from './model-types';
 import type { Faker } from '@stacksjs/faker';
+import type { GdprTraitOptions, PersonalAttribute } from './gdpr/types';
 import type { InferRelationNames } from '@stacksjs/query-builder';
 import type { Validator } from '@stacksjs/validation';
 // Re-export types from bun-query-builder for convenience
@@ -104,6 +105,7 @@ export declare interface StacksModelDefinition extends Omit<BQBModelDefinition,
       readonly middleware?: ApiMiddleware
     }
     commentable?: boolean | object
+    gdpr?: GdprTraitOptions
     broadcastOn?: (model: any) => string[]
     broadcastWith?: (model: any) => Record<string, unknown>
   }
@@ -217,6 +219,12 @@ export type StacksModelAttribute = Omit<BQBModelAttribute, 'factory'> & {
    * value can depend on another: `(faker, { discountType }) => ...`.
    */
   factory?: (faker: Faker, attributes: Readonly<Record<string, unknown>>) => unknown
+  /**
+   * Personal data (stacksjs/stacks#365): exported by an access request,
+   * anonymized by erasure and retention. See `GdprTraitOptions` for the
+   * model-level half.
+   */
+  personal?: PersonalAttribute
 }
 declare type ModelDefinition = StacksModelDefinition;
 declare type ValidationRuleOf<TAttribute> = TAttribute extends { validation: { rule: infer TRule } } ? TRule : never;

package/dist/gdpr/engine.d.ts

@@ -0,0 +1,82 @@
+import type { GdprErasureResult, GdprExport, GdprModels, GdprPruneResult, GdprSubjectIdentity } from './types';
+/** Whether a table exists. Only a missing-table answer is "no"; anything else propagates. */
+export declare function gdprTableExists(table: string, handle?: Handle): Promise<boolean>;
+/** Find the user a request is about, by id, email or uuid. */
+export declare function resolveGdprSubject(reference: number | string, options?: GdprRunOptions, handle?: Handle): Promise<GdprSubjectIdentity | null>;
+/**
+ * Everything the subject's declared personal data amounts to, as one document.
+ *
+ * Per model: the matching rows, carrying only the declared personal columns
+ * plus the row's id, uuid and timestamps - never an undeclared column, so a
+ * column added later is not exported until somebody classifies it. Alongside
+ * the data, the purpose, basis and retention each model declares, which an
+ * Article 15 answer owes the subject as well. Records an `access` audit row.
+ */
+export declare function exportSubjectData(reference: number | string, options?: GdprRunOptions): Promise<GdprExport>;
+/**
+ * Erase a data subject, per each model's declaration.
+ *
+ * `delete` removes the matched rows, `anonymize` overwrites their personal
+ * columns, `keep` leaves them (and is still reported, so the operator sees
+ * what was retained and can say why). All of it in one transaction with the
+ * audit row, so an erasure is either recorded and complete or neither.
+ *
+ * Idempotent: a second run matches what the first left behind and finds
+ * nothing to change. A dry run reads the same rows and writes nothing, so its
+ * report is exactly what a real run would do.
+ */
+export declare function eraseSubject(reference: number | string, options?: GdprEraseOptions): Promise<GdprErasureResult>;
+/**
+ * End every session the subject still holds.
+ *
+ * After the commit, not inside it: the auth layer runs its own transactions,
+ * and on SQLite a second writer inside an open one waits on itself. Failing
+ * here propagates - the data is already erased, re-running is safe, and a
+ * reported success that left a token alive would be the worse outcome.
+ */
+declare function revokeCredentials(subjectId: number | string): Promise<boolean>;
+/**
+ * Apply every model's retention policy.
+ *
+ * Candidate rows are read with a string bound one day past the cutoff and then
+ * compared as dates. Stored timestamps come in two spellings - the database
+ * clock's `YYYY-MM-DD HH:MM:SS` and the framework's `YYYY-MM-DDTHH:MM:SS.sss`
+ * - and comparing either against the other as a string is off by up to a day
+ * in the direction of deleting too much. The wider bound can only over-select,
+ * and the date comparison removes what it over-selected.
+ *
+ * One transaction per model, so a large table does not hold a lock over the
+ * whole run, with a `retention` audit row when anything changed.
+ */
+export declare function pruneRetainedData(options?: GdprPruneOptions): Promise<GdprPruneResult>;
+/**
+ * Access, erasure and retention over the declared personal data
+ * (stacksjs/stacks#365).
+ *
+ * Every write goes through the rows a subject link MATCHED - primary keys read
+ * first, written second - never through a predicate re-evaluated at write
+ * time. That is what keeps another subject's rows out of reach: an erasure can
+ * only touch a row it has already shown belongs to the subject it was asked
+ * about, and a dry run reports exactly the rows a real run would change.
+ */
+/** The audit ledger: one row per access request, erasure, and retention run that changed something. */
+export declare const GDPR_AUDIT_TABLE: 'gdpr_requests';
+export declare interface GdprRunOptions {
+  models?: GdprModels
+  actor?: string
+}
+export declare interface GdprEraseOptions extends GdprRunOptions {
+  dryRun?: boolean
+  revokeCredentials?: boolean
+}
+export declare interface GdprPruneOptions extends GdprRunOptions {
+  dryRun?: boolean
+  now?: Date
+}
+declare type Row = Record<string, unknown>;
+// The tables here are named by model declarations at runtime, so the typed
+// schema cannot describe them. One alias rather than a cast at every call.
+declare type Handle = any;
+export declare class GdprSubjectNotFoundError extends Error {
+  constructor(reference: number | string);
+}

package/dist/gdpr/index.d.ts

@@ -0,0 +1,20 @@
+export type { GdprEraseOptions, GdprPruneOptions, GdprRunOptions } from './engine';
+export type { GdprProcessingRegister, GdprRegisterEntry, GdprRegisterFormat } from './register';
+export type * from './types';
+/**
+ * Data-subject access, erasure, retention and the processing register, all
+ * read off the model declarations (stacksjs/stacks#365). See `./types` for
+ * the vocabulary a model declares.
+ */
+export {
+  eraseSubject,
+  exportSubjectData,
+  GDPR_AUDIT_TABLE,
+  GdprSubjectNotFoundError,
+  gdprTableExists,
+  pruneRetainedData,
+  resolveGdprSubject,
+} from './engine';
+export { loadGdprModels } from './models';
+export { assertGdprPlan, GDPR_SUBJECT_MODEL, GdprDeclarationError, gdprTableName, resolveGdprPlan } from './plan';
+export { buildProcessingRegister, renderProcessingRegister } from './register';

package/dist/gdpr/models.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The model definitions GDPR requests run against: the framework defaults,
+ * with the app's own `app/Models` overriding them by name - the same merge the
+ * generated API routes and the OpenAPI spec read.
+ *
+ * A default whose table this app never migrated is still in the set; the
+ * engine reports it as skipped rather than querying a table that is not there.
+ */
+export declare function loadGdprModels(): Promise<Record<string, any>>;

package/dist/gdpr/plan.d.ts

@@ -0,0 +1,12 @@
+import type { GdprDeclarationProblem, GdprModelDefinition, GdprModels, GdprPlan } from './types';
+export declare function gdprTableName(name: string, definition: GdprModelDefinition): string;
+export declare function resolveGdprPlan(models: GdprModels): GdprPlan;
+/** Throw every declaration problem at once, or return the plan untouched. */
+export declare function assertGdprPlan(plan: GdprPlan): GdprPlan;
+/** The model whose rows ARE the data subjects. */
+export declare const GDPR_SUBJECT_MODEL: 'User';
+/** Raised when a declaration cannot be honoured; carries every problem at once. */
+export declare class GdprDeclarationError extends Error {
+  readonly problems: GdprDeclarationProblem[];
+  constructor(problems: GdprDeclarationProblem[]);
+}

package/dist/gdpr/register.d.ts

@@ -0,0 +1,30 @@
+import type { GdprErasureAction, GdprLawfulBasis, GdprPlan } from './types';
+export declare function buildProcessingRegister(plan: GdprPlan): GdprProcessingRegister;
+export declare function renderProcessingRegister(register: GdprProcessingRegister, format?: GdprRegisterFormat): string;
+/**
+ * The processing register: a record of what personal data the application
+ * holds, whose it is, why, and what happens to it (GDPR Article 30).
+ *
+ * Generated, never edited. A hand-kept register is accurate on the day it is
+ * written and wrong from the first migration after; deriving it from the same
+ * declarations the erasure and retention code reads means the document cannot
+ * describe behaviour the application does not have. The output is stable - no
+ * timestamp, everything sorted - so a committed copy can be checked for drift
+ * the way the other generated documents are (`buddy gdpr:register:check`).
+ */
+export declare interface GdprRegisterEntry {
+  model: string
+  table: string
+  subject: string
+  personal: string[]
+  notExported: string[]
+  erasure: GdprErasureAction | null
+  retention: string | null
+  basis: GdprLawfulBasis | null
+  purpose: string | null
+}
+export declare interface GdprProcessingRegister {
+  entries: GdprRegisterEntry[]
+  unclassified: string[]
+}
+export type GdprRegisterFormat = 'markdown' | 'json';

package/dist/gdpr/types.d.ts

@@ -0,0 +1,88 @@
+import type { GdprErasureAction, GdprLawfulBasis, GdprRetentionAction, GdprRetentionPolicy, GdprSubject, GdprTraitOptions, PersonalAttribute, PersonalAttributeOptions } from '@stacksjs/types';
+export type {
+  GdprErasureAction,
+  GdprLawfulBasis,
+  GdprRetentionAction,
+  GdprRetentionPolicy,
+  GdprSubject,
+  GdprTraitOptions,
+  PersonalAttribute,
+  PersonalAttributeOptions,
+};
+/** A model definition, as much of it as the GDPR layer reads. */
+export declare interface GdprModelDefinition {
+  readonly name?: string
+  readonly table?: string
+  readonly primaryKey?: string
+  readonly belongsTo?: unknown
+  readonly traits?: Readonly<Record<string, unknown>> & { readonly gdpr?: GdprTraitOptions }
+  readonly attributes?: Readonly<Record<string, unknown>>
+}
+/** One personal column, resolved. */
+export declare interface GdprPersonalField {
+  attribute: string
+  column: string
+  export: boolean
+  perRow: boolean
+  anonymizeTo: string | number | boolean | null
+}
+/** Everything the GDPR layer knows about one model. */
+export declare interface GdprModelPlan {
+  model: string
+  table: string
+  primaryKey: string
+  subject: GdprSubjectLink | null
+  personal: GdprPersonalField[]
+  erasure: GdprErasureAction
+  retention: { days: number, column: string, action: GdprRetentionAction } | null
+  purpose: string | null
+  basis: GdprLawfulBasis | null
+  depth: number
+  exportColumns: string[]
+}
+export declare interface GdprDeclarationProblem {
+  model: string
+  message: string
+}
+export declare interface GdprPlan {
+  models: GdprModelPlan[]
+  unclassified: string[]
+  problems: GdprDeclarationProblem[]
+}
+/** The subject an access or erasure request is about. */
+export declare interface GdprSubjectIdentity {
+  id: number | string
+  email: string | null
+}
+export declare interface GdprExport {
+  subject: { id: number | string }
+  generatedAt: string
+  data: Record<string, Array<Record<string, unknown>>>
+  processing: Record<string, { purpose: string | null, basis: GdprLawfulBasis | null, retentionDays: number | null }>
+}
+export declare interface GdprModelChange {
+  model: string
+  table: string
+  action: GdprErasureAction | GdprRetentionAction
+  matched: number
+  changed: number
+  fields: string[]
+}
+export declare interface GdprErasureResult {
+  subject: { id: number | string }
+  dryRun: boolean
+  changes: GdprModelChange[]
+  skipped: string[]
+  credentialsRevoked: boolean
+}
+export declare interface GdprPruneResult {
+  dryRun: boolean
+  cutoffs: Record<string, string>
+  changes: GdprModelChange[]
+  skipped: string[]
+}
+export type GdprModels = Readonly<Record<string, GdprModelDefinition>> | readonly GdprModelDefinition[];
+/** How a model's rows are matched to a subject, resolved to columns. */
+export type GdprSubjectLink = | { kind: 'column', columns: string[], where: Record<string, string | number | boolean> }
+  | { kind: 'via', model: string, foreignKey: string }
+  | { kind: 'email', column: string }

package/dist/index.d.ts

@@ -94,6 +94,7 @@ export declare const Redirect: ReturnType<typeof lazyModel<typeof import('./mode
 export declare const Site: ReturnType<typeof lazyModel<typeof import('./models/Site').default>>;
 export declare const SiteDomain: ReturnType<typeof lazyModel<typeof import('./models/SiteDomain').default>>;
 export declare const SmsOptOut: ReturnType<typeof lazyModel<typeof import('./models/SmsOptOut').default>>;
+export declare const GdprRequest: ReturnType<typeof lazyModel<typeof import('./models/GdprRequest').default>>;
 export declare const StorageItem: ReturnType<typeof lazyModel<typeof import('./models/StorageItem').default>>;
 export declare const StorageItemTask: ReturnType<typeof lazyModel<typeof import('./models/StorageItemTask').default>>;
 export declare const EmailIdempotency: ReturnType<typeof lazyModel<typeof import('./models/EmailIdempotency').default>>;
@@ -299,6 +300,10 @@ export * from './batch-loader';
 export * from './db';
 export * from './subquery';
 export * from './transaction';
+// Data-subject access, erasure and retention, plus the processing register,
+// read off each model's `personal` attributes and `gdpr` trait
+// (stacksjs/stacks#365).
+export * from './gdpr/index';
 export * from './model-types';
 export * from './types';
 export * from '@stacksjs/model-meta';