@rehearsal-db/core 0.1.0-beta.10 → 0.1.0-beta.12

package/docs/sanitization.md

@@ -40,9 +40,110 @@ Two policy versions exist:
   Rehearsal can sanitize without project callbacks.
 
 Version 2 supports keyed UUID, email, text, and integer pseudonyms; explicit constant
-replacement; bounded date shifting; and exhaustively classified JSON objects. Unknown
-tables, columns, nested keys, formats, recipes, or missing fields fail closed. It never
-evaluates JavaScript or SQL from the policy.
+replacement; bounded date shifting; approved-owner conditionals; exhaustively classified
+JSON objects; and bounded JSON arrays. Unknown tables, columns, nested keys, formats,
+recipes, or missing required fields fail closed. It never evaluates JavaScript or SQL
+from the policy.
+
+## Approved-owner values
+
+Keep the raw approved owner outside the policy and baseline. The policy stores only its
+environment-variable name and SHA-256 receipt:
+
+```json
+{
+  "bindings": {
+    "approved-owner": {
+      "environmentVariable": "REHEARSAL_APPROVED_OWNER_ID",
+      "approvedValueSha256": "<lowercase sha256 of the exact owner value>"
+    }
+  },
+  "tables": [
+    {
+      "name": "profiles",
+      "sourceRows": "STREAM AND SANITIZE",
+      "ownerBinding": { "binding": "approved-owner", "column": "user_id" },
+      "columns": [
+        {
+          "name": "user_id",
+          "action": "PSEUDONYMIZE",
+          "recipe": { "format": "uuid", "namespace": "account-id" },
+          "generated": "NEVER",
+          "identity": "YES",
+          "foreignKey": null
+        },
+        {
+          "name": "display_name",
+          "action": "DERIVE",
+          "recipe": {
+            "kind": "approved-owner",
+            "approved": { "action": "KEEP" },
+            "otherwise": {
+              "action": "REPLACE",
+              "recipe": { "kind": "constant", "value": "Synthetic account" }
+            }
+          },
+          "generated": "NEVER",
+          "identity": "NO",
+          "foreignKey": null
+        }
+      ]
+    }
+  ]
+}
+```
+
+Generate the receipt without putting the owner value in shell history:
+
+```sh
+node -e 'const {createHash}=require("node:crypto"); process.stdout.write(createHash("sha256").update(process.env.REHEARSAL_APPROVED_OWNER_ID).digest("hex")+"\n")'
+```
+
+Every conditional table names its owner column. Missing bindings, hash mismatches,
+missing owner columns, null/unsupported owner values, and conditionals without an owner
+binding are refused. The owner column must be marked `identity: "YES"` and use
+`PSEUDONYMIZE`, preventing a conditional policy from retaining raw account IDs. Other
+owners take the declared `otherwise` path; every other identity-bearing field still
+needs its own pseudonymization declaration. Supply the binding only to the local
+server-side Rehearsal process; do not put it in the policy, baseline, or tracked files.
+
+## Structured JSON
+
+`json-object` fields are required by default. Set `"required": false` on an explicitly
+optional field. Unknown keys remain errors. `json-array` declares one item recipe and a
+required `maximumItems`. Both recipes accept `maximumDepth`, `maximumBytes`, and
+`allowNull`; defaults are 8 levels, 65,536 bytes, and no null container. Bounds are
+checked before producing the transformed structure. Nested objects and arrays repeat
+the same declarations, and every nested identity uses an explicit pseudonym recipe.
+
+```json
+{
+  "action": "DERIVE",
+  "recipe": {
+    "kind": "json-array",
+    "maximumItems": 25,
+    "maximumDepth": 4,
+    "maximumBytes": 8192,
+    "items": {
+      "action": "DERIVE",
+      "recipe": {
+        "kind": "json-object",
+        "fields": {
+          "actor_id": {
+            "action": "PSEUDONYMIZE",
+            "recipe": { "format": "uuid", "namespace": "account-id" }
+          },
+          "note": {
+            "action": "REPLACE",
+            "required": false,
+            "recipe": { "kind": "constant", "value": "Synthetic note" }
+          }
+        }
+      }
+    }
+  }
+}
+```
 
 The package still exports `validateSanitizationCoverage` and
 `applySanitizationAction` for existing version 1 preparation tools:

package/docs/standalone-workflow.md

@@ -28,6 +28,8 @@ name:
 - whether rows are approved public data or belong to one explicitly approved
   owner;
 - privacy actions and bounded transformation recipes;
+- hashed server-side owner bindings and explicit approved/other-owner branches;
+- bounded nested JSON objects and arrays with required/optional fields;
 - licensed or consented Storage buckets and prefixes;
 - schema and extension prerequisites;
 - local identities and reference locations;

package/docs/troubleshooting.md

@@ -20,6 +20,20 @@ npx rehearsal --help
 
 Do not use `sudo` or require a global install.
 
+## Installation did not create `rehearsal.config.mjs`
+
+Rehearsal intentionally skips automatic creation when install scripts are disabled, the
+install is global or temporary, or more than one workspace application could own the
+config. From the intended application directory, run:
+
+```bash
+npx rehearsal
+```
+
+Choose **Set the stage** and approve the preview. For pnpm and Yarn, use this guided path;
+automatic root generation is currently tested with npm. An existing supported config is
+kept in place, including `infrastructure/rehearsal/rehearsal.config.mjs`.
+
 ## Setup says Node.js 24 is required
 
 Rehearsal intentionally supports one maintained Node.js major in its first beta. Switch
@@ -132,9 +146,31 @@ changes.
 
 ## Local authentication fails
 
-Confirm the provider is enabled in the dedicated local Supabase config, the allowlisted
-service environment file exists with owner-only permissions, and the provider callback
-is the local Auth callback. Do not paste provider secrets into config or terminal output.
+For Google or GitHub, confirm `supabase.authentication` is declared in
+`rehearsal.config.mjs`, its ignored environment file exists with `chmod 600`, and the
+provider has the printed local Auth callback registered. Rehearsal generates the
+disposable Supabase provider block.
+
+When migrating from the legacy service environment fields, replace those fields together
+with `supabase.authentication` and rerun `rehearsal doctor`. A compatible Google or
+GitHub provider section may remain in the tracked template: Rehearsal supersedes it only
+inside the generated runtime copy. Doctor refuses unknown provider settings, duplicate
+or nested provider sections, and nonce or optional-email settings that do not match the
+new declaration. Keep both options false unless there is a reviewed provider-specific
+need; skipping nonce validation reduces replay protection. Otherwise keep using the
+documented legacy configuration.
+Never paste provider secrets into tracked config or terminal output.
+
+If `identity plan` refuses the matcher, read the message literally:
+
+- **Provider or matcher type is unsupported:** use only the combinations documented in
+  [Runtime and identity policies](runtime-policies.md).
+- **No verified identity matches:** complete an ordinary local sign-in, confirm the
+  correct environment value is present, then run the plan again.
+- **More than one identity matches:** narrow the provider allowlist or use a hashed
+  provider-subject matcher. Rehearsal will not guess between accounts.
+- **Provider subject conflicts:** the local Auth identity disagrees with itself; remove
+  and recreate that disposable local sign-in instead of forcing a claim.
 
 ## Runtime changes disappeared
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.10",
+  "version": "0.1.0-beta.12",
   "private": false,
   "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
   "repository": {
@@ -10,7 +10,7 @@
   "bugs": {
     "url": "https://github.com/Ddupasquier/rehearsal-db/issues"
   },
-  "homepage": "https://github.com/Ddupasquier/rehearsal-db#readme",
+  "homepage": "https://ddupasquier.github.io/rehearsal-db/",
   "publishConfig": {
     "access": "public",
     "tag": "beta",
@@ -40,6 +40,7 @@
   },
   "files": [
     "src",
+    "scripts/install/create_root_config.mjs",
     "scripts/runtime/manage_database.mjs",
     "docs/*.md",
     "README.md",
@@ -51,6 +52,9 @@
     "LICENSE"
   ],
   "scripts": {
+    "postinstall": "node scripts/install/create_root_config.mjs",
+    "docs:build": "node scripts/docs/build.mjs",
+    "docs:preview": "node scripts/docs/serve.mjs",
     "test": "vitest run",
     "test:unit": "vitest run tests/unit",
     "test:integration": "vitest run tests/integration tests/contracts",
@@ -58,8 +62,10 @@
     "test:fixture": "node scripts/verification/fixtures/supabase.mjs",
     "test:fixture:postgresql": "node scripts/verification/fixtures/postgresql.mjs",
     "test:fixture:dependent": "node scripts/verification/fixtures/dependent.mjs",
+    "test:fixture:onboarding": "node scripts/verification/fixtures/onboarding.mjs",
     "test:fixture:standalone": "node scripts/verification/fixtures/standalone.mjs",
-    "check": "npm run check:syntax && npm run test && npm run format:check && npm run package:audit",
+    "test:fixture:privacy": "node scripts/verification/fixtures/privacy.mjs",
+    "check": "npm run check:syntax && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
     "check:syntax": "find src scripts tests -type f -name '*.mjs' -exec node --check {} +",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -78,7 +84,10 @@
     "pg": "^8.23.1"
   },
   "devDependencies": {
+    "@fontsource-variable/dm-sans": "^5.3.0",
+    "@fontsource-variable/fraunces": "^5.3.0",
     "@lydell/node-pty": "^1.2.0-beta.15",
+    "marked": "^18.0.14",
     "prettier": "^3.9.6",
     "vitest": "^5.0.2"
   }

package/scripts/install/create_root_config.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/** Create safe project-root Rehearsal scaffolding during a local install. */
+
+import { fileURLToPath } from "node:url";
+import { createInstalledRehearsalScaffold } from "../../src/project/install_scaffold.mjs";
+
+const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
+
+try {
+  const result = await createInstalledRehearsalScaffold({ packageRoot });
+  if (result.status === "ready") {
+    const changed = result.files.filter((file) => file.action !== "unchanged");
+    console.log(
+      [
+        "Rehearsal is ready in this project.",
+        ...(changed.length
+          ? [
+              ...changed.map(
+                (file) =>
+                  `  ${file.action === "create" ? "+" : "~"} ${file.path}`,
+              ),
+            ]
+          : ["  Existing Rehearsal configuration preserved."]),
+        "Next: review rehearsal.config.mjs, then run npx rehearsal.",
+      ].join("\n"),
+    );
+  } else {
+    console.log(
+      `Rehearsal did not create project files: ${result.reason}.\nNext: run npx rehearsal from the application directory.`,
+    );
+  }
+} catch (error) {
+  console.warn(
+    `Rehearsal could not safely create project files during installation: ${String(error?.message ?? error)}\nNext: run npx rehearsal from the application directory.`,
+  );
+}