hazo_env 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # hazo_env
 
-Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/secret config, a `doctor` diagnostic command, and a `hazo-env` CLI.
+Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/secret config, a DB+files migration engine with PII masking, a `doctor` diagnostic command, and a `hazo-env` CLI.
 
 ## What it does
 
@@ -8,8 +8,10 @@ Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/s
 - **Per-env DB config** — `resolveConnectConfig()` maps the current env to its `hazo_connect` config (SQLite or PostgREST) with zero hardcoded connection strings in app code.
 - **Per-env file config** — `resolveFilesConfig()` maps the current env to a `hazo_files` config rooted at the declared `data_root`.
 - **Secrets** — `getSecret()` resolves from `.env.local` only; placeholders in `hazo_env_config.ini` are substituted at runtime without storing secrets.
+- **Migration engine** — `runMigration({ from, to })` copies a DB + files between envs. Validates → snapshots target → copies tables (paged, schema-checked) → copies files → verifies → writes hazo_audit entry. Prod target refused without an explicit confirm token.
+- **PII masking** — masking rules declared per table/column in `hazo_env_masking.ini` (seed) and synced to `hazo_app_config` at runtime. Built-in transforms: `mask_email`, `fake_name`, `mask_phone`, `jitter_date`, `hash`, `tokenize`, `drop`, `nullify`. Custom transforms via `registerMask()`. Applied automatically when the migration target role is `testing` or `staging`.
 - **Doctor** — `doctor()` / `hazo-env doctor` validates pattern, DB reachability, required secrets (no values printed), data_root writability, and schema level.
-- **CLI** — `hazo-env current | doctor | snapshot`.
+- **CLI** — `hazo-env current | doctor | snapshot | migrate | verify | restore | mask`.
 
 ## Installation
 
@@ -18,7 +20,7 @@ npm install hazo_env
 ```
 
 Peer deps (required): `hazo_core`, `hazo_config`.
-Peer deps (optional): `hazo_connect` (for `resolveConnectConfig`), `hazo_files` (for `resolveFilesConfig`).
+Peer deps (optional): `hazo_connect` (for `resolveConnectConfig`), `hazo_files` (for `resolveFilesConfig`), `hazo_secure` (for masking transforms), `hazo_pdf` (for `mask_pdf` transform), `hazo_audit` (for migration audit entries).
 
 ## Quick start
 
@@ -101,12 +103,52 @@ const report = await doctor();
 // report.checks    DoctorCheck[] — { label, ok, message }
 ```
 
+### Migration engine (server-only)
+
+```ts
+import { runMigration, verifyFiles, takeSnapshot, restoreSnapshot } from 'hazo_env';
+
+// Copy prod → staging (with PII masking applied automatically)
+const result = await runMigration({
+  from: 'prod',
+  to: 'staging',
+  dryRun: false,                         // set true for a plan with counts, no writes
+  // allowProdTarget: true,              // required when `to` is 'prod'
+  // confirmToken: '<token>',            // required together with allowProdTarget
+  onProgress: (p) => console.log(p.phase, p.message),
+});
+// result.ok, result.db, result.files, result.snapshotId, result.warnings, result.durationMs
+
+// Stand-alone verification
+await verifyFiles('staging', dataRoot, { hash: 'sample' });
+
+// Manual snapshot / restore
+const snap = takeSnapshot(connectConfig);   // returns { snapshotId }
+restoreSnapshot(connectConfig, snapshotId);
+```
+
+**Masking** — customize per table/column in `config/hazo_env_masking.ini`. Sync to the DB with `hazo-env mask sync`. Register custom transforms with `registerMask(name, fn)`.
+
 ## CLI
 
 ```
 hazo-env current                       # prints env, role, pattern, app, data_root
 hazo-env doctor [--env <e>] [--all]    # red/green validation table
-hazo-env snapshot <env>                # placeholder — full impl arrives in M2
+hazo-env snapshot <env>                # snapshot the target env DB
+
+hazo-env migrate --from <env> --to <env> [options]
+  --transport auto|local|ssh|api       # default auto
+  --no-db | --no-files                 # skip DB or file copy
+  --scrub auto|none                    # default auto (mask when target is test/staging)
+  --tables a,b,c                       # restrict to specific tables
+  --dry-run                            # plan + counts, no writes
+  --allow-prod-target --confirm <tok>  # required when writing prod
+
+hazo-env verify <env> [--hash none|sample|full] [--no-orphans]
+hazo-env restore <env> --snapshot <snapshot-id>
+
+hazo-env mask sync                     # sync hazo_env_masking.ini → hazo_app_config
+hazo-env mask list                     # print active masking rules
 ```
 
 ## Config reference (`hazo_env_config.ini`)

package/SETUP_CHECKLIST.md

@@ -8,6 +8,8 @@ Follow these steps when adding `hazo_env` to a consuming application.
 npm install hazo_env hazo_core hazo_config
 # optional — only if you use resolveConnectConfig / resolveFilesConfig:
 npm install hazo_connect hazo_files
+# optional — only if you use the migration engine with masking + PDF scrub + audit trail:
+npm install hazo_secure hazo_pdf hazo_audit
 ```
 
 ## 2. Create `hazo_env_config.ini`
@@ -90,3 +92,48 @@ const nextConfig = {
   transpilePackages: ['hazo_env', 'hazo_core', /* … */],
 };
 ```
+
+## 9. (Optional) Set up the migration engine
+
+Skip this section if you only need env resolution and resolvers.
+
+### 9a. Create `hazo_env_masking.ini`
+
+Copy `node_modules/hazo_env/config/hazo_env_masking.ini.sample` to your app's `config/` directory and declare per-table masking rules:
+
+```ini
+[hazo_users]
+email         = mask_email
+full_name     = fake_name
+password_hash = drop
+
+[my_app_clients]
+notes = redact_pii
+dob   = jitter_date
+```
+
+Sync to the DB so the runtime engine can read them:
+
+```bash
+npx hazo-env mask sync
+```
+
+### 9b. Set `HAZO_ENV_MASK_KEY` in `.env.local`
+
+Required for deterministic masking transforms (`hash`, `tokenize`). If absent, migration aborts when scrub mode is `auto`.
+
+```
+HAZO_ENV_MASK_KEY=<random-32-char-hex>
+```
+
+### 9c. Run a dry-run migration to verify the plan
+
+```bash
+npx hazo-env migrate --from prod --to staging --dry-run
+```
+
+Review row counts and scrub counts before running without `--dry-run`. The migration will snapshot the target env before writing so you can restore if needed:
+
+```bash
+npx hazo-env restore staging --snapshot <snapshot-id>
+```

package/config/hazo_env_masking.ini.sample

@@ -1,19 +1,19 @@
 ; hazo_env masking ruleset sample
-; Copy to hazo_env_masking.ini and customize.
-; This file seeds the masking engine with default rules for PII fields.
-; The runtime source of truth (once hazo_admin is available) is the DB-backed ruleset.
+; Copy to config/hazo_env_masking.ini and customise.
+; Load into hazo_app_config with: hazo-env mask sync
+;
+; Format: [table_name] then column = transform_name
+; Transforms: mask_email, mask_phone, fake_name, jitter_date, hash, tokenize, drop, nullify
+; Custom transforms can be registered via registerMask() in your app.
 
-[rule.users_email]
-table   = hazo_auth_users
-column  = email
-strategy = mask_email
+[hazo_users]
+email = mask_email
+full_name = fake_name
+phone = mask_phone
+dob = jitter_date
+password_hash = drop
 
-[rule.users_name]
-table   = hazo_auth_users
-column  = full_name
-strategy = fake_name
-
-[rule.api_keys]
-table   = hazo_api_keys
-column  = key_hash
-strategy = drop
+[hazo_auth_users]
+email = mask_email
+full_name = fake_name
+password_hash = drop

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// hazo_env/src/cli.ts — CLI entry: hazo-env current | doctor | snapshot
+// hazo_env/src/cli.ts — CLI entry: hazo-env current | doctor | snapshot | migrate | verify | restore
 import pc from 'picocolors';
 import { getEnv, getEnvRole } from './index.client.js';
 import { describeEnv } from './env.server.js';
@@ -60,10 +60,151 @@ async function runDoctor() {
 }
 async function runSnapshot() {
     const targetEnv = args[0] ?? getEnv();
-    console.log(`\n${pc.yellow('snapshot')} — not implemented until Phase 2 (migration engine)\n`);
-    console.log(`  Requested snapshot of env: ${pc.bold(targetEnv)}`);
-    console.log(`  Run "hazo-env snapshot" again after the migration engine is built.\n`);
-    process.exit(1);
+    console.log(`\n${pc.bold('hazo-env snapshot')} ${pc.dim(targetEnv)}\n`);
+    const { takeSnapshot } = await import('./migrate/snapshot.js');
+    const { resolveConnectConfig } = await import('./resolve/connect.js');
+    const toConfig = resolveConnectConfig({ env: targetEnv, allowOtherEnv: true });
+    const result = takeSnapshot(toConfig);
+    console.log(`  ${pc.green('✓')} Snapshot: ${result.snapshotId}\n`);
+}
+async function runMigrate() {
+    const fromIdx = args.findIndex((a) => a === '--from');
+    const toIdx = args.findIndex((a) => a === '--to');
+    const from = fromIdx >= 0 ? args[fromIdx + 1] : undefined;
+    const to = toIdx >= 0 ? args[toIdx + 1] : undefined;
+    const dryRun = args.includes('--dry-run');
+    const noFiles = args.includes('--no-files');
+    const noDb = args.includes('--no-db');
+    const allowProdTarget = args.includes('--allow-prod-target');
+    const confirmIdx = args.findIndex((a) => a === '--confirm');
+    const confirmToken = confirmIdx >= 0 ? args[confirmIdx + 1] : undefined;
+    const tablesIdx = args.findIndex((a) => a === '--tables');
+    const tablesArg = tablesIdx >= 0 ? args[tablesIdx + 1] : undefined;
+    const tables = tablesArg ? tablesArg.split(',').map((t) => t.trim()) : undefined;
+    if (!from || !to) {
+        console.error(pc.red('Error: migrate requires --from <env> and --to <env>'));
+        process.exit(1);
+    }
+    console.log(`\n${pc.bold('hazo-env migrate')}  ${pc.dim(`${from} → ${to}${dryRun ? ' (dry-run)' : ''}`)}\n`);
+    const { runMigration } = await import('./migrate/run.js');
+    try {
+        const result = await runMigration({
+            from,
+            to,
+            include: { db: !noDb, files: !noFiles },
+            tables: tables ?? '*',
+            dryRun,
+            allowProdTarget,
+            confirmToken,
+            onProgress: (p) => {
+                const pct = p.percent != null ? `${p.percent}%`.padStart(4) + ' ' : '     ';
+                console.log(`  ${pct}${pc.dim(p.phase.padEnd(12))} ${p.message}`);
+            },
+        });
+        if (result.ok) {
+            console.log(`\n  ${pc.green('✓')} Migration ${dryRun ? 'plan built (dry-run)' : 'complete'}`);
+            if (result.db)
+                console.log(`  ${pc.dim('DB:')} ${result.db.tables} tables, ${result.db.rows} rows${result.db.scrubbed ? `, ${result.db.scrubbed} scrubbed` : ''}`);
+            if (result.files)
+                console.log(`  ${pc.dim('Files:')} ${result.files.copied} copied`);
+            if (result.snapshotId && !result.snapshotId.startsWith('no-db:'))
+                console.log(`  ${pc.dim('Snapshot:')} ${result.snapshotId}`);
+            if (result.warnings.length)
+                result.warnings.forEach((w) => console.log(`  ${pc.yellow('⚠')} ${w}`));
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`\n  ${pc.red('✗')} ${msg}\n`);
+        process.exit(1);
+    }
+    console.log('');
+}
+async function runVerify() {
+    const targetEnv = args[0] ?? getEnv();
+    console.log(`\n${pc.bold('hazo-env verify')} ${pc.dim(targetEnv)}\n`);
+    const { verifyFiles } = await import('./migrate/verify.js');
+    const { resolveFilesConfig } = await import('./resolve/files.js');
+    const dataRoot = resolveFilesConfig().local.basePath;
+    const report = await verifyFiles(targetEnv, dataRoot, { hash: 'sample', checkOrphans: true });
+    console.log(`  Checked: ${report.checked} files`);
+    if (report.ok) {
+        console.log(`  ${pc.green('✓')} All files verified\n`);
+    }
+    else {
+        if (report.missing.length)
+            console.log(`  ${pc.red('✗')} Missing: ${report.missing.join(', ')}`);
+        if (report.sizeMismatch.length)
+            console.log(`  ${pc.yellow('⚠')} Size mismatch: ${report.sizeMismatch.join(', ')}`);
+        console.log('');
+        process.exit(1);
+    }
+}
+async function runRestore() {
+    const targetEnv = args[0];
+    const snapshotIdx = args.findIndex((a) => a === '--snapshot');
+    const snapshotId = snapshotIdx >= 0 ? args[snapshotIdx + 1] : undefined;
+    if (!targetEnv || !snapshotId) {
+        console.error(pc.red('Error: restore requires <env> --snapshot <snapshot-id>'));
+        process.exit(1);
+    }
+    console.log(`\n${pc.bold('hazo-env restore')} ${pc.dim(`${targetEnv} ← ${snapshotId}`)}\n`);
+    const { restoreSnapshot } = await import('./migrate/snapshot.js');
+    const { resolveConnectConfig } = await import('./resolve/connect.js');
+    const toConfig = resolveConnectConfig({ env: targetEnv, allowOtherEnv: true });
+    restoreSnapshot(toConfig, snapshotId);
+    console.log(`  ${pc.green('✓')} Restored\n`);
+}
+async function runMask() {
+    const subCmd = args[0];
+    if (subCmd === 'sync') {
+        console.log(`\n${pc.bold('hazo-env mask sync')}\n`);
+        try {
+            const connectMod = await import('hazo_connect/server').catch(() => null);
+            if (!connectMod) {
+                console.error(pc.red('Error: hazo_connect is required for mask sync.'));
+                process.exit(1);
+            }
+            const { resolveConnectConfig } = await import('./resolve/connect.js');
+            const { syncRulesetFromIni } = await import('./mask/ruleset.js');
+            const dbConfig = resolveConnectConfig({ allowOtherEnv: false });
+            if (dbConfig.type !== 'sqlite' || !dbConfig.sqlite) {
+                console.error(pc.red('Error: mask sync only supports SQLite databases.'));
+                process.exit(1);
+            }
+            const adapter = connectMod.createHazoConnect({
+                type: 'sqlite',
+                sqlite: { database_path: dbConfig.sqlite.database_path },
+            });
+            const count = await syncRulesetFromIni(adapter);
+            console.log(`  ${pc.green('✓')} Synced ${count} rules into hazo_app_config\n`);
+        }
+        catch (e) {
+            console.error(`\n  ${pc.red('✗')} ${e instanceof Error ? e.message : String(e)}\n`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (subCmd === 'list') {
+        console.log(`\n${pc.bold('hazo-env mask list')}\n`);
+        const { listTransforms } = await import('./mask/registry.js');
+        const transforms = await listTransforms();
+        if (transforms.length === 0) {
+            console.log('  (no transforms registered)\n');
+        }
+        else {
+            for (const name of transforms)
+                console.log(`  ${pc.dim('•')} ${name}`);
+            console.log('');
+        }
+        return;
+    }
+    console.log(`
+${pc.bold('hazo-env mask')} — masking commands
+
+  hazo-env mask sync    Load hazo_env_masking.ini into hazo_app_config
+  hazo-env mask list    List registered transform functions
+`);
 }
 function printHelp() {
     console.log(`
@@ -75,7 +216,15 @@ Usage:
   hazo-env doctor --all                     Run health checks for all declared environments
   hazo-env doctor --env <env>               Run health checks for a specific environment
   hazo-env doctor --probe                   Also probe live DB reachability
-  hazo-env snapshot <env>                   (Phase 2 — not yet implemented)
+  hazo-env migrate --from <env> --to <env>  Migrate DB + files between environments
+    --dry-run                               Show plan without executing
+    --no-db / --no-files                    Skip DB or file copy
+    --allow-prod-target --confirm <token>   Override prod-target safety
+  hazo-env verify <env>                     Verify files for an environment
+  hazo-env restore <env> --snapshot <id>   Restore a snapshot
+  hazo-env snapshot <env>                   Take a snapshot of an environment
+  hazo-env mask sync                        Load masking ruleset from INI into DB
+  hazo-env mask list                        List registered mask transforms
 `);
 }
 (async () => {
@@ -89,6 +238,18 @@ Usage:
         else if (command === 'snapshot') {
             await runSnapshot();
         }
+        else if (command === 'migrate') {
+            await runMigrate();
+        }
+        else if (command === 'verify') {
+            await runVerify();
+        }
+        else if (command === 'restore') {
+            await runRestore();
+        }
+        else if (command === 'mask') {
+            await runMask();
+        }
         else {
             printHelp();
         }

package/dist/index.d.ts

@@ -5,4 +5,10 @@ export * from './resolve/secrets.js';
 export * from './resolve/connect.js';
 export * from './resolve/files.js';
 export * from './doctor.js';
+export { runMigration } from './migrate/run.js';
+export { verifyFiles } from './migrate/verify.js';
+export { takeSnapshot, restoreSnapshot } from './migrate/snapshot.js';
+export { registerMask } from './mask/registry.js';
+export type { MaskTransform } from './types/index.js';
+export * from './lib/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEzF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE/E,cAAc,kBAAkB,CAAC;AAEjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEzF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE/E,cAAc,kBAAkB,CAAC;AAEjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,aAAa,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -11,3 +11,11 @@ export * from './resolve/connect.js';
 export * from './resolve/files.js';
 // Doctor
 export * from './doctor.js';
+// Migration engine (Phase 2)
+export { runMigration } from './migrate/run.js';
+export { verifyFiles } from './migrate/verify.js';
+export { takeSnapshot, restoreSnapshot } from './migrate/snapshot.js';
+// Masking registry
+export { registerMask } from './mask/registry.js';
+// Lib
+export * from './lib/index.js';

package/dist/lib/index.d.ts

@@ -1,2 +1,2 @@
-export {};
+export * from './secret_columns.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,qBAAqB,CAAC"}

package/dist/lib/index.js

@@ -1 +1,2 @@
-export {};
+// hazo_env/src/lib/index.ts — Core library exports
+export * from './secret_columns.js';

package/dist/lib/secret_columns.d.ts

@@ -0,0 +1,3 @@
+export declare function isSecretColumn(columnName: string): boolean;
+export declare const SECRET_COLUMNS_LIST: string[];
+//# sourceMappingURL=secret_columns.d.ts.map

package/dist/lib/secret_columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret_columns.d.ts","sourceRoot":"","sources":["../../src/lib/secret_columns.ts"],"names":[],"mappings":"AAYA,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,eAAO,MAAM,mBAAmB,UAAsB,CAAC"}

package/dist/lib/secret_columns.js

@@ -0,0 +1,14 @@
+// hazo_env/src/lib/secret_columns.ts — columns that must never be copied as data
+const SECRET_COLUMNS = new Set([
+    'password', 'password_hash', 'hashed_password',
+    'api_key', 'api_secret', 'secret', 'secret_key',
+    'token', 'access_token', 'refresh_token', 'auth_token',
+    'private_key', 'session_token', 'session_secret',
+    'otp_secret', 'totp_secret', 'mfa_secret',
+    'client_secret', 'signing_key', 'encryption_key',
+    'webhook_secret', 'stripe_key', 'twilio_auth_token',
+]);
+export function isSecretColumn(columnName) {
+    return SECRET_COLUMNS.has(columnName.toLowerCase());
+}
+export const SECRET_COLUMNS_LIST = [...SECRET_COLUMNS];

package/dist/mask/registry.d.ts

@@ -0,0 +1,8 @@
+import type { MaskTransform } from '../types/index.js';
+/** Register a custom transform (or override a built-in). */
+export declare function registerMask(name: string, fn: MaskTransform): void;
+/** Get the transform function for a given name. Returns undefined if not registered. */
+export declare function getTransform(name: string): Promise<MaskTransform | undefined>;
+/** List all registered transform names. */
+export declare function listTransforms(): Promise<string[]>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/mask/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/mask/registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAiBvD,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,GAAG,IAAI,CAElE;AAED,wFAAwF;AACxF,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAGnF;AAED,2CAA2C;AAC3C,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAGxD"}

package/dist/mask/registry.js

@@ -0,0 +1,29 @@
+// hazo_env/src/mask/registry.ts — mask transform registry
+import { optional_import } from 'hazo_core';
+const _registry = new Map();
+let _seeded = false;
+async function ensureSeeded() {
+    if (_seeded)
+        return;
+    _seeded = true;
+    const maskModule = await optional_import('hazo_secure/mask');
+    if (maskModule?.BUILTIN_TRANSFORMS) {
+        for (const [name, fn] of Object.entries(maskModule.BUILTIN_TRANSFORMS)) {
+            _registry.set(name, fn);
+        }
+    }
+}
+/** Register a custom transform (or override a built-in). */
+export function registerMask(name, fn) {
+    _registry.set(name, fn);
+}
+/** Get the transform function for a given name. Returns undefined if not registered. */
+export async function getTransform(name) {
+    await ensureSeeded();
+    return _registry.get(name);
+}
+/** List all registered transform names. */
+export async function listTransforms() {
+    await ensureSeeded();
+    return [..._registry.keys()].sort();
+}

package/dist/mask/ruleset.d.ts

@@ -0,0 +1,15 @@
+import type { HazoConnectAdapter } from 'hazo_connect';
+export interface MaskRule {
+    table: string;
+    column: string;
+    transform: string;
+    params?: Record<string, unknown>;
+}
+export declare function ensureAppConfigTable(adapter: HazoConnectAdapter): Promise<void>;
+/** Load rules from hazo_env_masking.ini into hazo_app_config. */
+export declare function syncRulesetFromIni(adapter: HazoConnectAdapter, iniPath?: string): Promise<number>;
+/** Read the effective ruleset from hazo_app_config. */
+export declare function loadRuleset(adapter: HazoConnectAdapter): Promise<MaskRule[]>;
+/** Parse INI-format masking rules. Format: [table_name] / column = transform */
+export declare function parseIniRules(content: string): MaskRule[];
+//# sourceMappingURL=ruleset.d.ts.map

package/dist/mask/ruleset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleset.d.ts","sourceRoot":"","sources":["../../src/mask/ruleset.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AASD,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYrF;AAED,iEAAiE;AACjE,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAED,uDAAuD;AACvD,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAYlF;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE,CAkBzD"}

package/dist/mask/ruleset.js

@@ -0,0 +1,77 @@
+// hazo_env/src/mask/ruleset.ts — ruleset persistence (hazo_app_config)
+import path from 'node:path';
+import fs from 'node:fs';
+const CONFIG_SECTION = 'hazo_env_masking';
+// Ensure hazo_app_config table exists in the given SQLite adapter
+function rawQuery(adapter, sql, params = []) {
+    return adapter.rawQuery(sql, { params });
+}
+export async function ensureAppConfigTable(adapter) {
+    await rawQuery(adapter, `
+    CREATE TABLE IF NOT EXISTS hazo_app_config (
+      id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+      config_section TEXT NOT NULL,
+      config_name TEXT NOT NULL,
+      config_value_json TEXT,
+      created_at TEXT DEFAULT (datetime('now')),
+      updated_at TEXT DEFAULT (datetime('now')),
+      UNIQUE(config_section, config_name)
+    )
+  `);
+}
+/** Load rules from hazo_env_masking.ini into hazo_app_config. */
+export async function syncRulesetFromIni(adapter, iniPath) {
+    const resolvedPath = iniPath ?? path.resolve(process.cwd(), 'config', 'hazo_env_masking.ini');
+    if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`hazo_env_masking.ini not found at ${resolvedPath}`);
+    }
+    const content = fs.readFileSync(resolvedPath, 'utf-8');
+    const rules = parseIniRules(content);
+    await ensureAppConfigTable(adapter);
+    let count = 0;
+    for (const rule of rules) {
+        const name = `${rule.table}.${rule.column}`;
+        const valueJson = JSON.stringify({ transform: rule.transform, params: rule.params ?? {} });
+        await rawQuery(adapter, `
+      INSERT INTO hazo_app_config (config_section, config_name, config_value_json)
+      VALUES (?, ?, ?)
+      ON CONFLICT(config_section, config_name) DO UPDATE SET
+        config_value_json = excluded.config_value_json,
+        updated_at = datetime('now')
+    `, [CONFIG_SECTION, name, valueJson]);
+        count++;
+    }
+    return count;
+}
+/** Read the effective ruleset from hazo_app_config. */
+export async function loadRuleset(adapter) {
+    await ensureAppConfigTable(adapter);
+    const rows = await rawQuery(adapter, `SELECT config_name, config_value_json FROM hazo_app_config WHERE config_section = ? ORDER BY config_name`, [CONFIG_SECTION]);
+    return rows.map((row) => {
+        const [table, column] = row.config_name.split('.');
+        const parsed = JSON.parse(row.config_value_json ?? '{}');
+        return { table, column, transform: parsed.transform, params: parsed.params };
+    });
+}
+/** Parse INI-format masking rules. Format: [table_name] / column = transform */
+export function parseIniRules(content) {
+    const rules = [];
+    let currentTable = '';
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith(';') || line.startsWith('#'))
+            continue;
+        if (line.startsWith('[') && line.endsWith(']')) {
+            currentTable = line.slice(1, -1).trim();
+        }
+        else if (currentTable && line.includes('=')) {
+            const eqIdx = line.indexOf('=');
+            const column = line.slice(0, eqIdx).trim();
+            const transform = line.slice(eqIdx + 1).trim();
+            if (column && transform) {
+                rules.push({ table: currentTable, column, transform });
+            }
+        }
+    }
+    return rules;
+}

package/dist/migrate/audit.d.ts

@@ -0,0 +1,21 @@
+import type { HazoConnectAdapter } from 'hazo_connect';
+export interface AuditMigrationPayload {
+    from: string;
+    to: string;
+    scrub: string;
+    db?: {
+        tables: number;
+        rows: number;
+        scrubbed: number;
+    };
+    files?: {
+        copied: number;
+        bytes: number;
+    };
+    verify?: {
+        ok: boolean;
+        checked: number;
+    };
+}
+export declare function auditMigration(adapter: HazoConnectAdapter, payload: AuditMigrationPayload): Promise<void>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/migrate/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/migrate/audit.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAOD,wBAAsB,cAAc,CAClC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/migrate/audit.js

@@ -0,0 +1,36 @@
+// hazo_env/src/migrate/audit.ts — emit audit intent event (wrapped, never fails migration)
+import { optional_import } from 'hazo_core';
+// Cast helper for SQLite rawQuery params extension
+function rawQuery(adapter, sql, params = []) {
+    return adapter.rawQuery(sql, { params });
+}
+export async function auditMigration(adapter, payload) {
+    try {
+        // Ensure hazo_audit_intent table exists (CREATE TABLE IF NOT EXISTS)
+        await rawQuery(adapter, `
+      CREATE TABLE IF NOT EXISTS hazo_audit_intent (
+        id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+        event_name TEXT NOT NULL,
+        payload TEXT,
+        subject_kind TEXT,
+        subject_id TEXT,
+        created_at TEXT DEFAULT (datetime('now'))
+      )
+    `).catch(() => { });
+        const auditModule = await optional_import('hazo_audit/server');
+        if (auditModule?.emitIntentEvent) {
+            await auditModule.emitIntentEvent(adapter, {
+                event_name: 'hazo_env.migration',
+                payload: payload,
+            });
+        }
+        else {
+            // Fallback: insert directly
+            await rawQuery(adapter, `INSERT INTO hazo_audit_intent (event_name, payload, subject_kind) VALUES (?, ?, ?)`, ['hazo_env.migration', JSON.stringify(payload), 'migration']);
+        }
+    }
+    catch (e) {
+        // Audit write failure never fails the migration
+        console.warn('[hazo_env] audit write failed (non-fatal):', e instanceof Error ? e.message : String(e));
+    }
+}