@nestarc/data-subject 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nestarc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# @nestarc/data-subject
+
+`@nestarc/data-subject` is a small NestJS-oriented toolkit for handling data-subject export and erasure requests against subject-scoped data.
+
+Today the package ships:
+
+- a programmatic entity registry
+- a `DataSubjectService` for `export`, `erase`, and request lookup
+- a `DataSubjectModule.forRoot(...)` integration for NestJS
+- a lightweight Prisma adapter built on `findMany`, `deleteMany`, and `updateMany`
+- in-memory request and artifact stores for tests and local development
+- typed policy validation and typed runtime errors
+
+## Current Scope
+
+Package version: `0.1.0`
+
+This repository currently focuses on the execution core. It does **not** currently ship:
+
+- decorators or automatic entity discovery
+- a CLI or schema linter
+- persistent request storage adapters
+- persistent artifact storage adapters beyond the in-memory implementation
+- schema-aware Prisma field deletion beyond `null` assignment
+
+If you need database-specific behavior, you can plug in your own `EntityExecutor`, `RequestStorage`, or `ArtifactStorage`.
+
+## Installation
+
+```bash
+npm install @nestarc/data-subject
+```
+
+Peer dependencies used by this package:
+
+- `@nestjs/common`
+- `@nestjs/core`
+- `reflect-metadata`
+- `rxjs`
+- `@prisma/client` if you use `fromPrisma(...)`
+
+## Quick Start
+
+```ts
+import { Module } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+import {
+  DataSubjectModule,
+  InMemoryArtifactStorage,
+  InMemoryRequestStorage,
+  fromPrisma,
+} from '@nestarc/data-subject';
+
+const prisma = new PrismaClient();
+
+@Module({
+  imports: [
+    DataSubjectModule.forRoot({
+      requestStorage: new InMemoryRequestStorage(),
+      artifactStorage: new InMemoryArtifactStorage(),
+      slaDays: 30,
+      strictLegalBasis: true,
+      entities: [
+        {
+          policy: {
+            entityName: 'User',
+            subjectField: 'userId',
+            rowLevel: 'delete-row',
+            fields: {
+              email: 'delete',
+              name: 'delete',
+            },
+          },
+          executor: fromPrisma({
+            delegate: prisma.user,
+            subjectField: 'userId',
+            tenantField: 'tenantId',
+          }),
+        },
+        {
+          policy: {
+            entityName: 'Invoice',
+            subjectField: 'customerId',
+            fields: {
+              customerName: {
+                strategy: 'retain',
+                legalBasis: 'tax:KR-basic-law-sec85',
+                until: '+7y',
+              },
+              amount: {
+                strategy: 'retain',
+                legalBasis: 'tax:KR-basic-law-sec85',
+              },
+              customerEmail: {
+                strategy: 'anonymize',
+                replacement: '[REDACTED]',
+              },
+            },
+          },
+          executor: fromPrisma({
+            delegate: prisma.invoice,
+            subjectField: 'customerId',
+            tenantField: 'tenantId',
+          }),
+        },
+      ],
+      publishOutbox: async (type, payload) => {
+        // forward to your outbox publisher
+      },
+      publishAudit: async (event, data) => {
+        // optional hook
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Usage:
+
+```ts
+const exportRequest = await dataSubject.export('user_123', 'tenant_abc');
+const eraseRequest = await dataSubject.erase('user_123', 'tenant_abc');
+
+const sameRequest = await dataSubject.getRequest(exportRequest.id);
+const tenantRequests = await dataSubject.listByTenant('tenant_abc');
+const overdue = await dataSubject.listOverdue();
+```
+
+## Policy Model
+
+Policies are registered per entity and compiled before execution.
+
+### `delete`
+
+```ts
+fields: {
+  email: 'delete',
+}
+```
+
+- shorthand `'delete'` is normalized to `{ strategy: 'delete' }`
+- entity `rowLevel` defaults to `'delete-fields'`
+- with the default Prisma adapter:
+  - `'delete-row'` calls `deleteMany`
+  - `'delete-fields'` calls `updateMany` and writes `null` into the configured delete fields
+
+### `anonymize`
+
+```ts
+fields: {
+  email: { strategy: 'anonymize', replacement: '[REDACTED]' },
+}
+```
+
+- replacements must be static
+- function replacements are rejected during policy compilation
+
+### `retain`
+
+```ts
+fields: {
+  amount: {
+    strategy: 'retain',
+    legalBasis: 'tax:KR-basic-law-sec85',
+    until: '+7y',
+  },
+}
+```
+
+- `legalBasis` is required
+- `strictLegalBasis: true` enables `scheme:reference` validation
+- `pseudonymize` is part of the type model, but this package does not perform pseudonymization by itself
+
+### Mixed Strategies
+
+When an entity mixes `delete`, `anonymize`, and `retain`, execution is intentionally conservative:
+
+- `retain` fields are preserved
+- delete fields are downgraded to field-level updates instead of row deletion
+- mixed entities are reported as `strategy: 'mixed'` in erase stats
+- retained fields are recorded in `stats.retained`
+
+This prevents `retain` fields from being dropped just because some other fields on the same row are deletable.
+
+## Export Behavior
+
+`DataSubjectService.export(subjectId, tenantId)` does the following:
+
+1. creates a request record
+2. reads matching rows from every registered entity
+3. writes one JSON file per entity into a ZIP archive
+4. stores the ZIP through `ArtifactStorage.put(...)`
+5. records:
+   - `artifactHash` as a SHA-256 digest of the ZIP bytes
+   - `artifactUrl` returned by the artifact storage
+   - `stats.entities[]` with `strategy: 'export'`
+
+Current export artifact shape:
+
+- key: `<requestId>.zip`
+- contents: `<EntityName>.json` files
+
+## Erase Behavior
+
+`DataSubjectService.erase(subjectId, tenantId)` does the following:
+
+1. creates a request record
+2. publishes `data_subject.erasure_requested`
+3. executes each registered entity according to its compiled policy
+4. records:
+   - `stats.entities[]`
+   - `stats.retained[]`
+   - `stats.verificationResidual[]`
+   - `artifactHash` as a SHA-256 digest of the erase report JSON
+
+Important details:
+
+- erase uses `ArtifactStorage` for exports, but **not** for erase reports
+- erase verification currently only fails on residual rows after `delete-row`
+- field-level delete and anonymize operations keep rows in place by design
+
+## NestJS Integration
+
+`DataSubjectModule.forRoot(...)` accepts:
+
+- `requestStorage`
+- `artifactStorage`
+- `slaDays`
+- `strictLegalBasis`
+- `entities`
+- `publishOutbox`
+- `publishAudit`
+- `runInTransaction`
+
+The module exports:
+
+- `DataSubjectService`
+- `DATA_SUBJECT_REGISTRY`
+
+## Public API
+
+The package currently exports:
+
+- `DataSubjectService`
+- `DataSubjectModule`
+- `Registry`
+- `compilePolicy`
+- `validateLegalBasis`
+- `fromPrisma`
+- `InMemoryRequestStorage`
+- `InMemoryArtifactStorage`
+- all public types from `src/types.ts`
+- typed errors from `src/errors.ts`
+
+## Events and Hooks
+
+### Outbox Hook
+
+If `publishOutbox` is provided, the built-in service emits:
+
+- `data_subject.request_created`
+- `data_subject.erasure_requested`
+- `data_subject.request_completed`
+- `data_subject.request_failed`
+
+`request_completed` and `request_failed` are emitted for both export and erase requests. `erasure_requested` is erase-only.
+
+### Audit Hook
+
+If `publishAudit` is provided, the built-in service currently emits:
+
+- `data_subject.request_created`
+
+No additional audit lifecycle events are emitted by the current implementation.
+
+## Typed Errors
+
+The package exposes `DataSubjectError` with stable error codes.
+
+Currently used codes include:
+
+- `dsr_invalid_policy`
+- `dsr_anonymize_dynamic_replacement`
+- `dsr_verification_failed`
+- `dsr_entity_already_registered`
+- `dsr_request_conflict`
+- `dsr_request_not_found`
+
+Some additional codes exist in the public enum for future or adapter-specific use.
+
+## Transaction Boundaries
+
+`runInTransaction` is an integration hook, not an automatic rollback guarantee.
+
+```ts
+new DataSubjectService({
+  // ...
+  runInTransaction: async (work) => myUnitOfWork.run(work),
+});
+```
+
+Use it when your erase flow can run inside a real unit-of-work that also covers:
+
+- the entity executors
+- request storage writes
+- outbox publishing
+
+If those components do not participate in the same transaction boundary, rollback remains best-effort.
+
+## Practical Limitations
+
+The current implementation is intentionally small. A few things are important to know up front:
+
+- `fromPrisma(...)` only depends on `findMany`, `deleteMany`, and `updateMany`
+- default Prisma field deletion writes `null`; it does not inspect schema nullability
+- request states include `validating`, but the built-in service currently transitions through `created -> processing -> completed|failed`
+- there is no built-in subject existence check before export or erase
+- only in-memory request and artifact adapters are included in this repository
+
+## Development
+
+```bash
+npm test
+npm run build
+```
+
+## CI and Release
+
+GitHub Actions is configured with two workflows:
+
+- `CI`: runs `npm ci`, `npm run lint`, `npm test -- --runInBand`, and `npm run build` on pushes, pull requests, and manual runs
+- `Release`: runs the same validation suite and then publishes to npm when a GitHub Release is published
+
+Release expectations:
+
+- configure repository secret `NPM_TOKEN`
+- publish a GitHub Release from a tag that matches `v<package.json version>`
+- prerelease versions publish with npm dist-tag `next`
+- stable versions such as `0.1.0` publish with npm dist-tag `latest`
+
+## Related Docs
+
+- [docs/prd.md](docs/prd.md)
+- [docs/spec.md](docs/spec.md)
+- [docs/compliance.md](docs/compliance.md)
+- [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+MIT

package/dist/data-subject.module.d.ts

@@ -0,0 +1,19 @@
+import { DynamicModule } from '@nestjs/common';
+import { type DataSubjectServiceDeps } from './data-subject.service';
+import { type RegisterInput } from './registry';
+import type { ArtifactStorage } from './storage/artifact-storage.interface';
+import type { RequestStorage } from './storage/request-storage.interface';
+export declare const DATA_SUBJECT_REGISTRY: unique symbol;
+export interface DataSubjectModuleOptions {
+    requestStorage: RequestStorage;
+    artifactStorage: ArtifactStorage;
+    slaDays?: number;
+    strictLegalBasis?: boolean;
+    entities?: RegisterInput[];
+    publishOutbox?: DataSubjectServiceDeps['publishOutbox'];
+    publishAudit?: DataSubjectServiceDeps['publishAudit'];
+    runInTransaction?: DataSubjectServiceDeps['runInTransaction'];
+}
+export declare class DataSubjectModule {
+    static forRoot(options: DataSubjectModuleOptions): DynamicModule;
+}

package/dist/data-subject.module.js

@@ -0,0 +1,55 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var DataSubjectModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataSubjectModule = exports.DATA_SUBJECT_REGISTRY = void 0;
+const common_1 = require("@nestjs/common");
+const data_subject_service_1 = require("./data-subject.service");
+const registry_1 = require("./registry");
+exports.DATA_SUBJECT_REGISTRY = Symbol('DATA_SUBJECT_REGISTRY');
+let DataSubjectModule = DataSubjectModule_1 = class DataSubjectModule {
+    static forRoot(options) {
+        const providers = [
+            {
+                provide: exports.DATA_SUBJECT_REGISTRY,
+                useFactory: () => {
+                    const registry = new registry_1.Registry({
+                        strictLegalBasis: options.strictLegalBasis,
+                    });
+                    for (const entity of options.entities ?? []) {
+                        registry.register(entity);
+                    }
+                    return registry;
+                },
+            },
+            {
+                provide: data_subject_service_1.DataSubjectService,
+                useFactory: (registry) => new data_subject_service_1.DataSubjectService({
+                    registry,
+                    requestStorage: options.requestStorage,
+                    artifactStorage: options.artifactStorage,
+                    slaDays: options.slaDays ?? 30,
+                    publishOutbox: options.publishOutbox,
+                    publishAudit: options.publishAudit,
+                    runInTransaction: options.runInTransaction,
+                }),
+                inject: [exports.DATA_SUBJECT_REGISTRY],
+            },
+        ];
+        return {
+            module: DataSubjectModule_1,
+            providers,
+            exports: [data_subject_service_1.DataSubjectService, exports.DATA_SUBJECT_REGISTRY],
+            global: true,
+        };
+    }
+};
+exports.DataSubjectModule = DataSubjectModule;
+exports.DataSubjectModule = DataSubjectModule = DataSubjectModule_1 = __decorate([
+    (0, common_1.Module)({})
+], DataSubjectModule);

package/dist/data-subject.service.d.ts

@@ -0,0 +1,35 @@
+import type { Registry } from './registry';
+import type { ArtifactStorage } from './storage/artifact-storage.interface';
+import type { RequestStorage } from './storage/request-storage.interface';
+import type { DataSubjectRequest, RequestState } from './types';
+export interface DataSubjectServiceDeps {
+    registry: Registry;
+    requestStorage: RequestStorage;
+    artifactStorage: ArtifactStorage;
+    slaDays: number;
+    idFactory?: () => string;
+    clock?: () => Date;
+    publishOutbox?: (type: string, payload: unknown) => Promise<void>;
+    publishAudit?: (event: string, data: Record<string, unknown>) => Promise<void>;
+    runInTransaction?: <T>(work: () => Promise<T>) => Promise<T>;
+}
+export declare class DataSubjectService {
+    private readonly deps;
+    private readonly idFactory;
+    private readonly clock;
+    private readonly publishOutbox;
+    private readonly publishAudit;
+    private readonly runInTransaction;
+    constructor(deps: DataSubjectServiceDeps);
+    export(subjectId: string, tenantId: string): Promise<DataSubjectRequest>;
+    erase(subjectId: string, tenantId: string): Promise<DataSubjectRequest>;
+    getRequest(id: string): Promise<DataSubjectRequest>;
+    listByTenant(tenantId: string, opts?: {
+        state?: RequestState;
+    }): Promise<DataSubjectRequest[]>;
+    listOverdue(): Promise<DataSubjectRequest[]>;
+    private createRequest;
+    private setState;
+    private markFailed;
+    private mustLoad;
+}

package/dist/data-subject.service.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataSubjectService = void 0;
+const node_crypto_1 = require("node:crypto");
+const erase_runner_1 = require("./erase-runner");
+const errors_1 = require("./errors");
+const export_runner_1 = require("./export-runner");
+class DataSubjectService {
+    deps;
+    idFactory;
+    clock;
+    publishOutbox;
+    publishAudit;
+    runInTransaction;
+    constructor(deps) {
+        this.deps = deps;
+        this.idFactory = deps.idFactory ?? (() => (0, node_crypto_1.randomUUID)());
+        this.clock = deps.clock ?? (() => new Date());
+        this.publishOutbox = deps.publishOutbox ?? (async () => { });
+        this.publishAudit = deps.publishAudit ?? (async () => { });
+        this.runInTransaction = deps.runInTransaction ?? (async (work) => work());
+    }
+    async export(subjectId, tenantId) {
+        const request = await this.createRequest('export', subjectId, tenantId);
+        try {
+            await this.setState(request.id, 'processing');
+            const runner = new export_runner_1.ExportRunner(this.deps.registry, this.deps.artifactStorage);
+            const result = await runner.run(request.id, subjectId, tenantId);
+            await this.deps.requestStorage.update(request.id, {
+                state: 'completed',
+                completedAt: this.clock(),
+                artifactHash: result.artifactHash,
+                artifactUrl: result.artifactUrl,
+                stats: result.stats,
+            });
+            await this.publishOutbox('data_subject.request_completed', {
+                requestId: request.id,
+                state: 'completed',
+                artifactHash: result.artifactHash,
+            });
+        }
+        catch (error) {
+            await this.markFailed(request.id, error);
+            await this.publishOutbox('data_subject.request_failed', {
+                requestId: request.id,
+                failureReason: messageFromError(error),
+            });
+        }
+        return this.mustLoad(request.id);
+    }
+    async erase(subjectId, tenantId) {
+        const request = await this.createRequest('erase', subjectId, tenantId);
+        try {
+            await this.runInTransaction(async () => {
+                await this.publishOutbox('data_subject.erasure_requested', {
+                    requestId: request.id,
+                    subjectId,
+                    tenantId,
+                    requestedAt: this.clock().toISOString(),
+                });
+                await this.setState(request.id, 'processing');
+                const runner = new erase_runner_1.EraseRunner(this.deps.registry);
+                const result = await runner.run(subjectId, tenantId);
+                const report = JSON.stringify({ requestId: request.id, stats: result.stats });
+                const artifactHash = (0, node_crypto_1.createHash)('sha256').update(report).digest('hex');
+                await this.deps.requestStorage.update(request.id, {
+                    state: 'completed',
+                    completedAt: this.clock(),
+                    stats: result.stats,
+                    artifactHash,
+                });
+                await this.publishOutbox('data_subject.request_completed', {
+                    requestId: request.id,
+                    state: 'completed',
+                    artifactHash,
+                });
+            });
+        }
+        catch (error) {
+            await this.markFailed(request.id, error);
+            await this.publishOutbox('data_subject.request_failed', {
+                requestId: request.id,
+                failureReason: messageFromError(error),
+            });
+        }
+        return this.mustLoad(request.id);
+    }
+    async getRequest(id) {
+        return this.mustLoad(id);
+    }
+    async listByTenant(tenantId, opts = {}) {
+        return this.deps.requestStorage.listByTenant(tenantId, opts);
+    }
+    async listOverdue() {
+        return this.deps.requestStorage.listOverdue(this.clock());
+    }
+    async createRequest(type, subjectId, tenantId) {
+        const now = this.clock();
+        const dueAt = new Date(now.getTime() + this.deps.slaDays * 86_400_000);
+        const request = {
+            id: this.idFactory(),
+            tenantId,
+            subjectId,
+            type,
+            state: 'created',
+            createdAt: now,
+            dueAt,
+            completedAt: null,
+            failedAt: null,
+            failureReason: null,
+            artifactHash: null,
+            artifactUrl: null,
+            stats: null,
+            requestedBy: null,
+        };
+        await this.deps.requestStorage.insert(request);
+        await this.publishOutbox('data_subject.request_created', {
+            requestId: request.id,
+            type,
+            subjectId,
+            tenantId,
+        });
+        await this.publishAudit('data_subject.request_created', {
+            requestId: request.id,
+            type,
+            tenantId,
+        });
+        return request;
+    }
+    async setState(id, state) {
+        await this.deps.requestStorage.update(id, { state });
+    }
+    async markFailed(id, error) {
+        await this.deps.requestStorage.update(id, {
+            state: 'failed',
+            failedAt: this.clock(),
+            failureReason: messageFromError(error),
+        });
+    }
+    async mustLoad(id) {
+        const request = await this.deps.requestStorage.findById(id);
+        if (!request) {
+            throw new errors_1.DataSubjectError(errors_1.DataSubjectErrorCode.RequestNotFound, `request ${id} not found`);
+        }
+        return request;
+    }
+}
+exports.DataSubjectService = DataSubjectService;
+function messageFromError(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}

package/dist/erase-runner.d.ts

@@ -0,0 +1,10 @@
+import type { Registry } from './registry';
+import type { RequestStats } from './types';
+export interface EraseResult {
+    stats: RequestStats;
+}
+export declare class EraseRunner {
+    private readonly registry;
+    constructor(registry: Registry);
+    run(subjectId: string, tenantId: string): Promise<EraseResult>;
+}