@nestarc/data-subject 0.1.0 → 0.2.0

package/README.md

@@ -8,19 +8,22 @@ Today the package ships:
 - a `DataSubjectService` for `export`, `erase`, and request lookup
 - a `DataSubjectModule.forRoot(...)` integration for NestJS
 - a lightweight Prisma adapter built on `findMany`, `deleteMany`, and `updateMany`
+- a `PrismaRequestStorage` adapter for persistent request records
 - in-memory request and artifact stores for tests and local development
+- erase evidence artifacts with pre/post scan stats and SHA-256 hashes
+- a `data-subject lint` CLI for Prisma schema/policy checks
 - typed policy validation and typed runtime errors
 
 ## Current Scope
 
-Package version: `0.1.0`
+Package version: `0.2.0`
 
-This repository currently focuses on the execution core. It does **not** currently ship:
+This repository focuses on the execution core plus the minimum production trust layer. 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
+- direct Stripe, Intercom, analytics, or support-tool connectors
+- an admin or end-user portal
 - schema-aware Prisma field deletion beyond `null` assignment
 
 If you need database-specific behavior, you can plug in your own `EntityExecutor`, `RequestStorage`, or `ArtifactStorage`.
@@ -47,17 +50,20 @@ import { PrismaClient } from '@prisma/client';
 import {
   DataSubjectModule,
   InMemoryArtifactStorage,
-  InMemoryRequestStorage,
+  PrismaRequestStorage,
   fromPrisma,
 } from '@nestarc/data-subject';
 
 const prisma = new PrismaClient();
+const artifactStorage = new InMemoryArtifactStorage(); // local/dev only; use private durable storage in production
 
 @Module({
   imports: [
     DataSubjectModule.forRoot({
-      requestStorage: new InMemoryRequestStorage(),
-      artifactStorage: new InMemoryArtifactStorage(),
+      requestStorage: new PrismaRequestStorage({
+        delegate: prisma.dataSubjectRequest,
+      }),
+      artifactStorage,
       slaDays: 30,
       strictLegalBasis: true,
       entities: [
@@ -116,6 +122,8 @@ const prisma = new PrismaClient();
 export class AppModule {}
 ```
 
+For tests and local development, `InMemoryRequestStorage` and `InMemoryArtifactStorage` are still available. Do not use in-memory storage for production request history or evidence retention.
+
 Usage:
 
 ```ts
@@ -198,7 +206,7 @@ This prevents `retain` fields from being dropped just because some other fields
 
 Current export artifact shape:
 
-- key: `<requestId>.zip`
+- key: `data-subject/{tenantId}/{requestId}/export.zip`
 - contents: `<EntityName>.json` files
 
 ## Erase Behavior
@@ -206,19 +214,27 @@ Current export artifact shape:
 `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:
+2. transitions the request to `processing`
+3. performs a pre-scan for registered entities
+4. publishes `data_subject.erasure_requested`
+5. executes each registered entity according to its compiled policy
+6. performs a post-scan and residual verification
+7. stores an erase evidence JSON artifact through `ArtifactStorage.put(...)`
+8. records:
    - `stats.entities[]`
    - `stats.retained[]`
    - `stats.verificationResidual[]`
-   - `artifactHash` as a SHA-256 digest of the erase report JSON
+   - `stats.preScan[]`
+   - `stats.postScan[]`
+   - `artifactHash` as a SHA-256 digest of the erase evidence artifact
+   - `artifactUrl` returned by the artifact storage
 
 Important details:
 
-- erase uses `ArtifactStorage` for exports, but **not** for erase reports
+- erase evidence artifacts intentionally exclude raw rows and field values
 - erase verification currently only fails on residual rows after `delete-row`
 - field-level delete and anonymize operations keep rows in place by design
+- `subjectId` is not written into the default erase evidence artifact; it remains connected through the request record
 
 ## NestJS Integration
 
@@ -250,9 +266,22 @@ The package currently exports:
 - `fromPrisma`
 - `InMemoryRequestStorage`
 - `InMemoryArtifactStorage`
+- `PrismaRequestStorage`
+- `lintPrismaSchema`
+- `validateRegistry`
 - all public types from `src/types.ts`
 - typed errors from `src/errors.ts`
 
+## Schema Lint
+
+The package includes a small Prisma schema linter:
+
+```bash
+npx @nestarc/data-subject lint --schema prisma/schema.prisma --config data-subject.config.json
+```
+
+The linter checks for PII-like field names, missing policy fields, missing subject fields, missing tenant metadata, invalid policies, and suppressions without reasons. It is a safety net, not a full data discovery tool.
+
 ## Events and Hooks
 
 ### Outbox Hook
@@ -260,6 +289,7 @@ The package currently exports:
 If `publishOutbox` is provided, the built-in service emits:
 
 - `data_subject.request_created`
+- `data_subject.request_processing` through the audit hook
 - `data_subject.erasure_requested`
 - `data_subject.request_completed`
 - `data_subject.request_failed`
@@ -271,8 +301,9 @@ If `publishOutbox` is provided, the built-in service emits:
 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.
+- `data_subject.request_processing`
+- `data_subject.request_completed`
+- `data_subject.request_failed`
 
 ## Typed Errors
 
@@ -286,6 +317,9 @@ Currently used codes include:
 - `dsr_entity_already_registered`
 - `dsr_request_conflict`
 - `dsr_request_not_found`
+- `dsr_artifact_write_failed`
+- `dsr_invalid_state_transition`
+- `dsr_evidence_report_invalid`
 
 Some additional codes exist in the public enum for future or adapter-specific use.
 
@@ -316,7 +350,7 @@ The current implementation is intentionally small. A few things are important to
 - 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
+- no production cloud artifact adapter is bundled; use a private `ArtifactStorage` implementation for S3, R2, GCS, or equivalent storage
 
 ## Development
 
@@ -334,15 +368,21 @@ GitHub Actions is configured with two workflows:
 
 Release expectations:
 
-- configure repository secret `NPM_TOKEN`
+- configure npm Trusted Publisher for GitHub Actions:
+  - organization/user: `nestarc`
+  - repository: `data-subject`
+  - workflow filename: `release.yml`
+  - environment: `npm`
 - 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`
+- stable versions such as `0.2.0` publish with npm dist-tag `latest`
 
 ## Related Docs
 
 - [docs/prd.md](docs/prd.md)
 - [docs/spec.md](docs/spec.md)
+- [docs/data-subject-0.2.0-feature-proposal.md](docs/data-subject-0.2.0-feature-proposal.md)
+- [docs/data-subject-0.2.0-spec.md](docs/data-subject-0.2.0-spec.md)
 - [docs/compliance.md](docs/compliance.md)
 - [CHANGELOG.md](CHANGELOG.md)
 

package/dist/artifacts.d.ts

@@ -0,0 +1,3 @@
+export declare function sha256Hex(body: Buffer | string): string;
+export declare function exportArtifactKey(tenantId: string, requestId: string): string;
+export declare function erasureEvidenceArtifactKey(tenantId: string, requestId: string): string;

package/dist/artifacts.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Hex = sha256Hex;
+exports.exportArtifactKey = exportArtifactKey;
+exports.erasureEvidenceArtifactKey = erasureEvidenceArtifactKey;
+const node_crypto_1 = require("node:crypto");
+function sha256Hex(body) {
+    return (0, node_crypto_1.createHash)('sha256').update(body).digest('hex');
+}
+function exportArtifactKey(tenantId, requestId) {
+    return dataSubjectArtifactKey(tenantId, requestId, 'export.zip');
+}
+function erasureEvidenceArtifactKey(tenantId, requestId) {
+    return dataSubjectArtifactKey(tenantId, requestId, 'erase-evidence.json');
+}
+function dataSubjectArtifactKey(tenantId, requestId, fileName) {
+    return `data-subject/${keySegment(tenantId)}/${keySegment(requestId)}/${fileName}`;
+}
+function keySegment(value) {
+    return encodeURIComponent(value);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const lint_1 = require("./lint");
+const nodeRequire = (0, node_module_1.createRequire)(__filename);
+void main(process.argv.slice(2)).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});
+async function main(argv) {
+    const opts = parseArgs(argv);
+    if (opts.command !== 'lint') {
+        printHelp();
+        process.exitCode = opts.command ? 1 : 0;
+        return;
+    }
+    if (!opts.schema) {
+        throw new Error('data-subject lint requires --schema');
+    }
+    const schemaSource = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(opts.schema), 'utf8');
+    const config = await loadConfig(opts.config);
+    const report = (0, lint_1.lintPrismaSchema)(schemaSource, config);
+    if (opts.format === 'json') {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log((0, lint_1.formatLintReport)(report));
+    }
+    if ((0, lint_1.shouldFailLint)(report, opts.failOn)) {
+        process.exitCode = 1;
+    }
+}
+function parseArgs(argv) {
+    const opts = {
+        command: argv[0],
+        format: 'text',
+        failOn: 'error',
+    };
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        const next = argv[index + 1];
+        if (arg === '--schema') {
+            opts.schema = requireValue(arg, next);
+            index += 1;
+            continue;
+        }
+        if (arg === '--config') {
+            opts.config = requireValue(arg, next);
+            index += 1;
+            continue;
+        }
+        if (arg === '--format') {
+            const value = requireValue(arg, next);
+            if (value !== 'text' && value !== 'json') {
+                throw new Error('--format must be text or json');
+            }
+            opts.format = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--fail-on') {
+            const value = requireValue(arg, next);
+            if (value !== 'warning' && value !== 'error') {
+                throw new Error('--fail-on must be warning or error');
+            }
+            opts.failOn = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            opts.command = undefined;
+            return opts;
+        }
+        throw new Error(`unknown option: ${arg}`);
+    }
+    return opts;
+}
+function requireValue(flag, value) {
+    if (!value || value.startsWith('--')) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+async function loadConfig(configPath) {
+    if (!configPath) {
+        return {};
+    }
+    const fullPath = (0, node_path_1.resolve)(configPath);
+    const ext = (0, node_path_1.extname)(fullPath);
+    if (ext === '.json') {
+        return JSON.parse((0, node_fs_1.readFileSync)(fullPath, 'utf8'));
+    }
+    if (ext === '.mjs') {
+        const mod = (await Promise.resolve(`${(0, node_url_1.pathToFileURL)(fullPath).href}`).then(s => __importStar(require(s))));
+        return mod.default ?? {};
+    }
+    if (ext === '.js' || ext === '.cjs') {
+        const loaded = nodeRequire(fullPath);
+        if (isConfigModule(loaded)) {
+            return loaded.default ?? {};
+        }
+        return loaded;
+    }
+    throw new Error('data-subject lint supports .json, .js, .cjs, and .mjs config files');
+}
+function isConfigModule(value) {
+    return typeof value === 'object' && value !== null && 'default' in value;
+}
+function printHelp() {
+    console.log(`Usage:
+  data-subject lint --schema prisma/schema.prisma [--config data-subject.config.json]
+
+Options:
+  --schema <path>       Prisma schema path
+  --config <path>       Optional lint config (.json, .js, .cjs, .mjs)
+  --format <text|json>  Output format, defaults to text
+  --fail-on <level>     warning or error, defaults to error`);
+}

package/dist/data-subject.service.js

@@ -2,9 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DataSubjectService = void 0;
 const node_crypto_1 = require("node:crypto");
+const artifacts_1 = require("./artifacts");
 const erase_runner_1 = require("./erase-runner");
+const erasure_evidence_1 = require("./erasure-evidence");
 const errors_1 = require("./errors");
 const export_runner_1 = require("./export-runner");
+const stable_json_1 = require("./stable-json");
 class DataSubjectService {
     deps;
     idFactory;
@@ -24,6 +27,11 @@ class DataSubjectService {
         const request = await this.createRequest('export', subjectId, tenantId);
         try {
             await this.setState(request.id, 'processing');
+            await this.publishAudit('data_subject.request_processing', {
+                requestId: request.id,
+                type: request.type,
+                tenantId: request.tenantId,
+            });
             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, {
@@ -35,15 +43,31 @@ class DataSubjectService {
             });
             await this.publishOutbox('data_subject.request_completed', {
                 requestId: request.id,
+                requestType: request.type,
+                tenantId: request.tenantId,
                 state: 'completed',
                 artifactHash: result.artifactHash,
             });
+            await this.publishAudit('data_subject.request_completed', {
+                requestId: request.id,
+                type: request.type,
+                tenantId: request.tenantId,
+                artifactHash: result.artifactHash,
+            });
         }
         catch (error) {
             await this.markFailed(request.id, error);
             await this.publishOutbox('data_subject.request_failed', {
                 requestId: request.id,
-                failureReason: messageFromError(error),
+                requestType: request.type,
+                tenantId: request.tenantId,
+                failureReason: sanitizeFailureReason(error),
+            });
+            await this.publishAudit('data_subject.request_failed', {
+                requestId: request.id,
+                type: request.type,
+                tenantId: request.tenantId,
+                failureReason: sanitizeFailureReason(error),
             });
         }
         return this.mustLoad(request.id);
@@ -52,35 +76,76 @@ class DataSubjectService {
         const request = await this.createRequest('erase', subjectId, tenantId);
         try {
             await this.runInTransaction(async () => {
-                await this.publishOutbox('data_subject.erasure_requested', {
+                await this.setState(request.id, 'processing');
+                await this.publishAudit('data_subject.request_processing', {
                     requestId: request.id,
-                    subjectId,
-                    tenantId,
-                    requestedAt: this.clock().toISOString(),
+                    type: request.type,
+                    tenantId: request.tenantId,
                 });
-                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');
+                const result = await runner.run(subjectId, tenantId, {
+                    afterPreScan: async () => {
+                        await this.publishOutbox('data_subject.erasure_requested', {
+                            requestId: request.id,
+                            subjectId,
+                            tenantId,
+                            requestedAt: this.clock().toISOString(),
+                        });
+                    },
+                });
+                const artifact = (0, erasure_evidence_1.buildErasureEvidenceArtifact)({
+                    requestId: request.id,
+                    tenantId,
+                    generatedAt: this.clock(),
+                    stats: result.stats,
+                    actions: result.actions,
+                });
+                const body = Buffer.from((0, stable_json_1.stableStringify)(artifact), 'utf8');
+                const artifactHash = (0, artifacts_1.sha256Hex)(body);
+                const artifactUrl = await this.deps.artifactStorage.put((0, artifacts_1.erasureEvidenceArtifactKey)(tenantId, request.id), body, 'application/json');
+                const stats = {
+                    ...result.stats,
+                    evidence: {
+                        schemaVersion: 'data-subject.evidence.v1',
+                        artifactHash,
+                        artifactUrl,
+                    },
+                };
                 await this.deps.requestStorage.update(request.id, {
                     state: 'completed',
                     completedAt: this.clock(),
-                    stats: result.stats,
+                    stats,
                     artifactHash,
+                    artifactUrl,
                 });
                 await this.publishOutbox('data_subject.request_completed', {
                     requestId: request.id,
+                    requestType: request.type,
+                    tenantId: request.tenantId,
                     state: 'completed',
                     artifactHash,
                 });
+                await this.publishAudit('data_subject.request_completed', {
+                    requestId: request.id,
+                    type: request.type,
+                    tenantId: request.tenantId,
+                    artifactHash,
+                });
             });
         }
         catch (error) {
             await this.markFailed(request.id, error);
             await this.publishOutbox('data_subject.request_failed', {
                 requestId: request.id,
-                failureReason: messageFromError(error),
+                requestType: request.type,
+                tenantId: request.tenantId,
+                failureReason: sanitizeFailureReason(error),
+            });
+            await this.publishAudit('data_subject.request_failed', {
+                requestId: request.id,
+                type: request.type,
+                tenantId: request.tenantId,
+                failureReason: sanitizeFailureReason(error),
             });
         }
         return this.mustLoad(request.id);
@@ -116,7 +181,7 @@ class DataSubjectService {
         await this.deps.requestStorage.insert(request);
         await this.publishOutbox('data_subject.request_created', {
             requestId: request.id,
-            type,
+            requestType: type,
             subjectId,
             tenantId,
         });
@@ -134,7 +199,7 @@ class DataSubjectService {
         await this.deps.requestStorage.update(id, {
             state: 'failed',
             failedAt: this.clock(),
-            failureReason: messageFromError(error),
+            failureReason: sanitizeFailureReason(error),
         });
     }
     async mustLoad(id) {
@@ -146,6 +211,12 @@ class DataSubjectService {
     }
 }
 exports.DataSubjectService = DataSubjectService;
+function sanitizeFailureReason(error) {
+    const message = messageFromError(error)
+        .replace(/\s+/g, ' ')
+        .trim();
+    return message.length > 500 ? `${message.slice(0, 497)}...` : message;
+}
 function messageFromError(error) {
     if (error instanceof Error && error.message) {
         return error.message;

package/dist/erase-runner.d.ts

@@ -1,10 +1,14 @@
 import type { Registry } from './registry';
-import type { RequestStats } from './types';
+import type { ErasureEvidenceAction, RequestStats } from './types';
 export interface EraseResult {
     stats: RequestStats;
+    actions: ErasureEvidenceAction[];
+}
+export interface EraseRunOptions {
+    afterPreScan?: (preScan: NonNullable<RequestStats['preScan']>) => Promise<void>;
 }
 export declare class EraseRunner {
     private readonly registry;
     constructor(registry: Registry);
-    run(subjectId: string, tenantId: string): Promise<EraseResult>;
+    run(subjectId: string, tenantId: string, opts?: EraseRunOptions): Promise<EraseResult>;
 }