Lasagna-140726/recover-crypto

.github/workflows/ci.yml

@@ -2,8 +2,8 @@ name: CI
 
 on:
   push:
-    # TEMP: run CI on this branch while it bakes. Revert before merging.
-    branches: [master, main, LASAGNA-090706/soft]
+    # TEMP: run CI on these branches while they bake. Revert before merging.
+    branches: [master, main, LASAGNA-090706/soft, LASAGNA-140726/recover-crypto]
   pull_request:
     branches: [master, main]
 
@@ -53,8 +53,8 @@ jobs:
       - name: Build (core)
         run: npm run build
 
-      - name: Build satellite packages (sso, billing, admin, backup, websockets, reporting, ai)
-        run: npm run build:sso && npm run build:billing && npm run build:admin && npm run build:backup && npm run build:websockets && npm run build:reporting && npm run build:ai
+      - name: Build satellite packages (crypto, sso, billing, admin, backup, websockets, reporting, ai)
+        run: npm run build:crypto && npm run build:sso && npm run build:billing && npm run build:admin && npm run build:backup && npm run build:websockets && npm run build:reporting && npm run build:ai
 
       # The dev-only satellite-test-kit is imported by core's bin/test.integration.ts
       # (and each satellite's), which core's tsconfig typechecks. Build it before the
@@ -201,6 +201,7 @@ jobs:
           npm run test:coverage --workspace @adonisjs-lasagna/websockets
           npm run test:coverage --workspace @adonisjs-lasagna/reporting
           npm run test:coverage --workspace @adonisjs-lasagna/ai
+          npm run test:coverage --workspace @adonisjs-lasagna/crypto
 
       # Satellite ABI compatibility (B5): the reference third-party satellite
       # is built + tested against the freshly-built core above. Its typecheck
@@ -302,6 +303,14 @@ jobs:
           path: coverage/.v8/ai-unit
           if-no-files-found: warn
 
+      - name: Upload raw satellite unit coverage (V8) — crypto
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: c8-raw-crypto-unit
+          path: coverage/.v8/crypto-unit
+          if-no-files-found: warn
+
       # Full report (unused exports / orphaned files / deps) stays informational.
       - name: Knip (unused-code report)
         run: npm run knip
@@ -330,7 +339,7 @@ jobs:
       - name: Package contracts (publint + types resolution)
         run: |
           set -e
-          for pkg in core sso billing admin backup websockets reporting ai; do
+          for pkg in core sso billing admin backup websockets reporting ai crypto; do
             echo "== @adonisjs-lasagna/$pkg =="
             ( cd "packages/$pkg" \
               && npx -y publint@0.3.21 \
@@ -475,11 +484,11 @@ jobs:
       # with `default_transaction_read_only = on` so a write is denied by Postgres.
       PLUGIN_RO_DB_USER: plugin_ro
       PLUGIN_RO_DB_PASSWORD: plugin_ro
-      # This job HAS a real Postgres service, so the AI real-PG proofs are
+      # This job HAS a real Postgres service, so the crypto/AI real-PG proofs are
       # mandatory here: they must EXECUTE, never self-skip. The satellite real-PG
       # helpers read this flag and turn a would-be self-skip (PG unreachable, role
       # lacks CREATEDB) into a hard failure — the fail-loud twin of RLS_DB_USER,
-      # so a broken/hardened runner can't ship those proofs green.
+      # so a broken/hardened runner can't ship the crypto crown-jewel proofs green.
       REQUIRE_REAL_PG: '1'
 
     steps:
@@ -605,7 +614,9 @@ jobs:
       - name: Test (fault injection) — chaos tier
         if: contains(github.event.head_commit.message, '[chaos]') || contains(github.event.pull_request.title, '[chaos]')
         continue-on-error: true
-        run: npm run test:fault:run --workspace @adonisjs-lasagna/saas-tenancy
+        run: |
+          npm run test:fault:run --workspace @adonisjs-lasagna/saas-tenancy
+          npm run test:fault:run --workspace @adonisjs-lasagna/crypto
 
       # Satellite integration tiers boot through the shared satellite-test-kit,
       # proving the harness end to end on a real satellite. The step above ran
@@ -653,6 +664,14 @@ jobs:
       - name: Test (satellite integration) + coverage — ai
         run: npm run test:integration:coverage --workspace @adonisjs-lasagna/ai
 
+      # crypto's integration tier: the wrapped-DEK store + shred + WORM ledger + the
+      # @encrypted/@searchable decorators against real Postgres via the kit, across
+      # every placement (schema-pg, a real second database for database-pg, and the
+      # shared rowscope table with its RLS stub). The database-pg + rowscope specs
+      # self-skip if the CI role cannot CREATEDB / set the RLS GUC.
+      - name: Test (satellite integration) + coverage — crypto
+        run: npm run test:integration:coverage --workspace @adonisjs-lasagna/crypto
+
       # Consumer canary: boot the shared harness from a fresh satellite (the
       # reference template) against core's fixture. A kit change that breaks a
       # real consumer fails here on an isolated, fast signal instead of buried in
@@ -743,6 +762,18 @@ jobs:
           path: coverage/.v8/ai-integration
           if-no-files-found: warn
 
+      # crypto integration V8 (written by test:integration:coverage to
+      # coverage/.v8/crypto-integration in the "— crypto" step above). The
+      # coverage-report job merges this with crypto's unit V8 so
+      # check-satellite-coverage.mjs gates a real per-satellite MERGED number.
+      - name: Upload raw satellite integration coverage (V8) — crypto
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: c8-raw-crypto-integration
+          path: coverage/.v8/crypto-integration
+          if-no-files-found: warn
+
   test-e2e-demo:
     name: E2E (demo app)
     runs-on: ubuntu-latest
@@ -1223,6 +1254,12 @@ jobs:
           name: c8-raw-ai-integration
           path: coverage/.v8/all
 
+      - name: Download raw satellite integration coverage (V8) — crypto
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: c8-raw-crypto-integration
+          path: coverage/.v8/all
+
       # websockets integration V8 is produced by the test-e2e-websockets job (a
       # different job than test-integration above), now run under c8. This is why
       # test-e2e-websockets is in this job's needs:.
@@ -1278,6 +1315,12 @@ jobs:
           name: c8-raw-ai-unit
           path: coverage/.v8/all
 
+      - name: Download raw satellite unit coverage (V8) — crypto
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: c8-raw-crypto-unit
+          path: coverage/.v8/all
+
       - name: Aggregate coverage report (unit + integration, remapped to src)
         run: npm run coverage:report
 

.github/workflows/publish.yml

@@ -73,15 +73,16 @@ jobs:
             fi
           }
 
-          # Core first so satellites resolve a published peer. Only the six
+          # Core first so satellites resolve a published peer. Only the
           # publishable workspaces belong here: `admin` and `websockets` are
           # `private: true` (npm refuses them with EPRIVATE, which under
-          # `set -euo pipefail` would abort this script mid-release), and the
-          # crypto satellite was removed from the repo. `check-publish-coverage.mjs`
-          # asserts every non-private package appears below.
+          # `set -euo pipefail` would abort this script mid-release).
+          # `check-publish-coverage.mjs` asserts every non-private package
+          # appears below.
           publish_pkg "packages/core"
           publish_pkg "packages/sso"
           publish_pkg "packages/billing"
           publish_pkg "packages/backup"
           publish_pkg "packages/reporting"
           publish_pkg "packages/ai"
+          publish_pkg "packages/crypto"

README.md

@@ -40,7 +40,7 @@ and runs the full e2e suite against it.
 | **Dependency resilience** | Per-dependency fail-open/fail-closed degradation policy via `ResilienceService`. Emits `DependencyDegraded` for alerting and returns a typed 503 (`DependencyUnavailableException`) when fail-closed. |
 | **Lifecycle hooks + 30 typed events** | Declarative `before` / `after` hooks wired into commands and jobs. 20 core (tenant / quota / maintenance / resilience / metrics / data-change / guard-audit lifecycle) + 10 billing. |
 | **Contextual logging** | `tenantId` rides along through HTTP and queue jobs via `AsyncLocalStorage`. |
-| **`tenant:doctor`** | Ten built-in checks (plus `backup_recency` and `backup_encryption` when the backup satellite is installed), `--fix` for auto-recovery, `--json` for CI, `--watch` for a live TUI. |
+| **`tenant:doctor`** | Thirteen built-in checks (plus `backup_recency` and `backup_encryption` when the backup satellite is installed), `--fix` for auto-recovery (heals unmigrated/behind/failed tenants), `--json` for CI, `--watch` for a live TUI. |
 | **Plans and quotas** | Declarative plans, rolling counters, snapshot usage, an `enforceQuota()` middleware that returns 429 and emits `TenantQuotaExceeded`. |
 | **Scheduled backups + retention** | Tier-based intervals and `keepLast`, S3 mirror with purge awareness, idempotent cron command. |
 | **Health probes + Prometheus** | `/livez`, `/readyz`, `/healthz`, `/metrics`. No `prom-client` peer dep. |

apps/rental/.env.example

@@ -0,0 +1,56 @@
+# ─── App ──────────────────────────────────────────────────────────
+NODE_ENV=development
+PORT=3333
+HOST=127.0.0.1
+LOG_LEVEL=info
+APP_KEY=karimoto-dev-app-key-please-change-32ch
+
+# ─── Multitenancy ────────────────────────────────────────────────
+# Companies are addressed as <slug>.localhost (stored as custom_domain) and
+# resolved via domain-or-subdomain, with x-tenant-id (UUID) as the API fallback.
+TENANT_HEADER_KEY=x-tenant-id
+APP_DOMAIN=localhost
+IMPERSONATION_SECRET=karimoto-dev-impersonation-secret-change-me-0123456789
+
+# Webhook-delivery tests post to an in-process listener on loopback, so the SSRF
+# guard must exempt loopback for the suite. Keep OFF in any real deployment.
+WEBHOOKS_ALLOW_LOOPBACK_TARGETS=true
+
+# ─── PostgreSQL (matches docker-compose.yml) ──────────────────────
+DB_HOST=127.0.0.1
+DB_PORT=55433
+DB_USER=karimoto
+DB_PASSWORD=karimoto
+DB_DATABASE=karimoto
+
+# ─── Redis (matches docker-compose.yml) ───────────────────────────
+REDIS_HOST=127.0.0.1
+REDIS_PORT=56380
+
+QUEUE_REDIS_HOST=127.0.0.1
+QUEUE_REDIS_PORT=56380
+QUEUE_REDIS_DB=1
+
+CACHE_REDIS_HOST=127.0.0.1
+CACHE_REDIS_PORT=56380
+CACHE_REDIS_DB=2
+
+# ─── Seed a demo owner into every company schema at migrate time ──
+DEMO_SEED_TENANT_USERS=true
+
+# ─── Backups (optional) ──────────────────────────────────────────
+BACKUP_STORAGE_PATH=./storage/backups
+
+# ─── Billing (Stripe) — leave unset to run the offline mock ──────
+# BILLING_DRIVER=stripe
+# STRIPE_API_KEY=sk_test_...
+# STRIPE_WEBHOOK_SECRET=whsec_...
+
+# ─── AI (Anthropic) — leave unset to run the offline mock ────────
+# ANTHROPIC_API_KEY=sk-ant-...
+
+# ─── Mail (MailCatcher in dev, real SMTP in prod) ────────────────
+MAILCATCHER_HOST=127.0.0.1
+MAILCATCHER_PORT=1025
+MAIL_FROM_ADDRESS=noreply@karimoto.test
+MAIL_FROM_NAME=Karimoto

apps/rental/.gitignore

@@ -0,0 +1,7 @@
+node_modules
+build
+coverage
+.env
+storage
+tmp
+*.log

apps/rental/README.md

@@ -0,0 +1,87 @@
+# Karimoto
+
+A real car-rental SaaS built on `@adonisjs-lasagna/*`, exercising the whole
+platform: two auth realms, schema-per-tenant isolation, the nine satellites
+(admin, billing, ai, crypto, sso, backup, websockets, reporting) plus the core
+feature set, a `telematics` plugin, and two Inertia + React consoles (the
+platform operator and the rental company).
+
+- **Operator** lives on the apex host `localhost:3333`.
+- **Companies** live on a vanity host `<slug>.localhost:3333` (e.g.
+  `acme.localhost:3333`), stored as the tenant's `custom_domain`.
+
+## Runtime processes
+
+A real deployment runs three processes. In dev:
+
+- `npm run dev` — the HTTP server (Vite is auto-started, no `--hmr` needed).
+- `npm run dev:worker` — the queue worker (`queue:work`). **Required** for
+  tenant provisioning: company creation dispatches an `InstallTenant` job, and
+  the schema only exists once the worker has run it.
+
+Infrastructure (Postgres `pgvector/pgvector:pg16` + Redis + MailCatcher) comes
+up with `npm run infra:up`. Ports are 55433 / 56380 / 1025+1080, distinct from
+the core demo so both run side by side.
+
+## Setup from a clean database
+
+Provisioning is asynchronous, so setup is two passes with the worker running in
+between. From `apps/rental`:
+
+```bash
+npm run infra:up                     # Postgres + Redis + MailCatcher
+
+# 1. Control plane: operator account, central car catalog, and the two demo
+#    companies (each dispatches InstallTenant).
+npm run setup                        # backoffice:setup + central migrate + rental:seed
+
+# 2. Materialise the schemas: start the worker (leave it running) so it drains
+#    the InstallTenant jobs. The AI provider's after('provision') hook installs
+#    pgvector into the `extensions` schema as each company is provisioned.
+npm run dev:worker                   # in a second terminal; wait for the jobs to drain
+
+# 3. Data plane: migrate each tenant schema, then fill it with demo data.
+npm run setup:demo                   # tenant:vector:provision + migration:tenant:run + rental:seed:demo
+```
+
+`setup:demo` runs `tenant:vector:provision` first as a belt-and-suspenders step:
+it is idempotent, and it guarantees the `vector` extension exists on a
+pre-existing database (or one whose schemas were provisioned before the AI
+provider's hook was in place) before the `ai_embeddings vector(N)` migration runs.
+
+Then start the server:
+
+```bash
+npm run dev                          # http://localhost:3333
+```
+
+### Logins (dev only, refused in production)
+
+| Realm | Host | Email | Password |
+|---|---|---|---|
+| Operator | `localhost:3333` | `operator@karimoto.test` | `operator-demo-password` |
+| Company staff | `acme.localhost:3333` | `owner@karimoto.test` | `owner-demo-password` |
+| Company staff | `sahara-cars.localhost:3333` | `owner@karimoto.test` | `owner-demo-password` |
+
+## The two seed commands
+
+- **`rental:seed`** (control plane) — the operator account, the shared central
+  car catalog, and the demo company rows (dispatching provisioning). Idempotent.
+- **`rental:seed:demo`** (data plane) — fills each already-migrated company with
+  branches, a rate card, a fleet drawn from the catalog, renters with encrypted
+  PII, bookings across the lifecycle (invoices + payments for completed ones),
+  and a small RAG corpus of policy docs whose bodies are embedded into the tenant
+  vector store. Idempotent; safe to re-run to top up missing rows. Sizing follows
+  the company plan (`fleet`/`enterprise` get a full fleet, `starter` a smaller one
+  that stays under its `vehiclesPerTenant` quota).
+
+## The fleet assistant (RAG)
+
+The assistant streams over SSE at `POST /ai/chat`. Retrieval is opt-in
+(`retrieve: true`): it embeds the query and searches the tenant's `ai_embeddings`
+store, which `rental:seed:demo` populates from the policy docs. Offline (no
+`ANTHROPIC_API_KEY`) the chat and embeddings run on the in-process mocks, so
+retrieval returns real matches but the ranking is a deterministic hash, not
+semantic relevance. Set `ANTHROPIC_API_KEY` (and a real embedding backend) in
+`.env` and the same path uses the real model with no code change — re-run
+`rental:seed:demo` so the corpus is re-embedded into the real vector space.

apps/rental/ace.ts

@@ -0,0 +1,29 @@
+/**
+ * AdonisJS ace entrypoint. Boots the Ignitor in a console environment so
+ * commands can be discovered and executed via `npm run ace -- <command>`.
+ */
+import 'reflect-metadata'
+import { Ignitor, prettyPrintError } from '@adonisjs/core'
+
+const APP_ROOT = new URL('./', import.meta.url)
+const IMPORTER = (filePath: string) => {
+  if (filePath.startsWith('./') || filePath.startsWith('../')) {
+    return import(new URL(filePath, APP_ROOT).href)
+  }
+  return import(filePath)
+}
+
+new Ignitor(APP_ROOT, { importer: IMPORTER })
+  .tap((app) => {
+    app.booting(async () => {
+      await import('#start/env')
+    })
+    app.listen('SIGTERM', () => app.terminate())
+    app.listenIf(app.managedByPm2, 'SIGINT', () => app.terminate())
+  })
+  .ace()
+  .handle(process.argv.splice(2))
+  .catch((error) => {
+    process.exitCode = 1
+    prettyPrintError(error)
+  })