From 09f43139d3141cb77d1a4a77ab80da0533cff070 Mon Sep 17 00:00:00 2001 From: User Date: Sat, 22 Aug 2026 22:24:02 +0200 Subject: [PATCH] docs: record PSD runtime and DWH transport state --- .superpowers/sdd/progress.md | 24 ++++++++++++++++++++++++ brain/codebase/psd-dwh-transport.md | 20 ++++++++++++++++++++ brain/index.md | 1 + 3 files changed, 45 insertions(+) create mode 100644 brain/codebase/psd-dwh-transport.md diff --git a/.superpowers/sdd/progress.md b/.superpowers/sdd/progress.md index 732ac907..d36bc8d2 100644 --- a/.superpowers/sdd/progress.md +++ b/.superpowers/sdd/progress.md @@ -27,3 +27,27 @@ Task 9: PASS at frozen SHA `0c4ff3750d3ecd3fc514e50e511cf7475fbe0446`. Built and Task 10: NOT STARTED and requires a second explicit authorization. Public Nginx cutover, Mac-key delivery/configuration, and legacy revocation have not occurred. Activity 1 remains `IN_DISCUSSION`; external deployment remains `SURVEY_NO_GO`. Final clarification (bookkeeping): initial authorization at `6499d24` stopped before installation because the protected legacy file was missing and a journal-scan finding remained. A secret-safe legacy file was prepared without emit/hash; Nginx metadata remained unchanged and `nginx -t` PASS. Fix commits `6fb4886`, `dee0f9c`, `0c4ff37` received Terra PASS, followed by a detached complete re-freeze PASS at full `0c4ff3750d3ecd3fc514e50e511cf7475fbe0446`. The owner then explicitly authorized Gate 9 at that exact SHA; Gate 9 completed as recorded above. Task 10 remains a separate gate. + +## Project A authentication runtime projection + +Plan: `docs/superpowers/plans/2026-08-21-project-a-server-auth-runtime-projection.md` +Plan commit: `64f46c7019e11a74dae35a7cdb447cd881e17061` +Implementation baseline: `64f46c7019e11a74dae35a7cdb447cd881e17061` +Runtime constraint: source, synthetic tests, and documentation only; Project A, `/srv`, Nginx, +the legacy stack, and shared services remain untouched. + +Task 1: complete (commits `8a8f2c2`, `f9e2950`, `de86760`; independent Terra review PASS after descriptor-relative rewrite, full-history validation, crash recovery, destructive replacement guards, deterministic failure seams, and interrupted-retention recovery). +Task 2: complete (commits `05f8615`, `da2f4a6`, `1e2c4e6`; independent review PASS after exact GID enforcement, bounded descriptor-bound namespace enumeration, strict trailing-slash parity, OIDC coverage, and complete one-retry `CURRENT` publication linearization). +Task 3: complete (commit `903c0b4`; independent Terra review PASS after retained-FD outer locking, cancellable runtime/canonical waits, public transaction-context propagation, deterministic swap/metadata/creator-race tests, and fail-closed pre/post-commit error handling). +Task 4: complete (commit `3d9a9f0`; independent Terra review PASS after moving the Linux/root restore gate before secret-bearing checkpoint creation). Exact focused Go, race, vet, Node 24 focused/full, TypeScript, projected Compose, secret-policy, Windows backup compile, and full serialized tools/tht gates PASS. Historical canonical/unified Compose failures were reproduced as baseline-only documentation/path coupling failures and were not weakened. +Task 5: complete (commit `ef7ae70`; independent Terra review PASS after read-only Vitest gate repair, +remote-Docker/context hardening, and adversarial canonical-mount/`sudo printenv` verifier fixes). +All 14 cross-layer acceptance cases, documentation verifiers, shell syntax, full Go/race/vet, +backend Node 24 Vitest/typecheck, projected Compose, and secret-policy gates PASS. The three known +default/canonical/unified Compose policy failures were reproduced at `a21e2c1` and remain +unmodified baseline debt. Project A has not been started; applying the descriptor or any runtime +root under `/srv/thothii` still requires a new explicit authorization. +Final Project A source review: PASS for `a21e2c1..ef7ae70`; independent Terra review found no +remaining Critical or Important issue after validating restore admission/order, backend path and +identity controls, transaction cancellation, lifecycle gating, portability, dependency scope, and +redaction. Pre-live stop boundary remains in force. diff --git a/brain/codebase/psd-dwh-transport.md b/brain/codebase/psd-dwh-transport.md new file mode 100644 index 00000000..a4391f88 --- /dev/null +++ b/brain/codebase/psd-dwh-transport.md @@ -0,0 +1,20 @@ +# PSD DWH transport + +- Il workspace PSD supporta `rest_api` e `postgres_direct`; il trasporto è scelto dall'installazione. +- Il Mac usa REST/PostgREST; il ThothII installato sul server PSD usa PostgreSQL diretto. +- Il server deve usare un ruolo DWH dedicato: `USAGE` sullo schema e `SELECT` soltanto, verificati sui grant reali. +- La difesa read-only applicativa aggiunge: SQL strutturalmente SELECT-only, transazione `READ ONLY`, timeout, limite e rollback. +- La credenziale DWH REST `X-API-Key` non deve essere fornita al ThothII server. +- REST è il trasporto stabile per il Mac e per future installazioni remote che non possono aprire tunnel SSH. +- L'autenticazione REST target deve dare a ogni installazione un'identità separata, revocabile e auditabile; una chiave globale condivisa non scala. +- La rotazione della chiave globale esposta richiede una finestra dual-key che preservi il Mac prima della revoca. +- Il certificato REST corrente resta invariato: è self-issued e viene presentato anche dall'endpoint esterno; i client che non lo considerano già trusted richiedono `TLS_CA_FILE`. +- Il manuale deve coprire consegna e fingerprint della CA, scadenza/rinnovo coordinato e il fatto che i SAN correnti coprono `.it`, non `.com`. +- Non esiste un ambiente di test PSD: le rotazioni devono usare backup, dual-key, probe read-only e rollback sull'endpoint di produzione. +- Supabase Studio è un pannello amministrativo loopback, non un data-plane o un trasporto per ThothII. +- Le credenziali DWH, session storage e amministrazione Supabase devono restare separate. +- Il collegamento container→PostgreSQL deve usare un endpoint host/rete esplicito e ristretto; il loopback dell'host non è il loopback del container. +- Il nightly ETL PSD delle 03:00 usa PostgreSQL diretto; non è un consumer della route REST `/dwh/`. +- Un preprocessing REST Thoth genera `1 + 3T + Ct + Ce` richieste: una lista tabelle, tre RPC per tabella e due famiglie di campionamento testuale. +- Per PSD nel run 2026-08-13: `T=163` e `Ct+Ce=1180`, quindi 1670 richieste per ciclo; undici rerun spiegano 18.370 richieste. +- I repository server esistenti contengono materiale sensibile hardcoded: non copiarlo; inventariare, rimuovere dal tracking e ruotare i segreti coinvolti. diff --git a/brain/index.md b/brain/index.md index 4b3f8e4d..15288d32 100644 --- a/brain/index.md +++ b/brain/index.md @@ -2,4 +2,5 @@ - [[codebase/datamart-builder-deployment-gotchas]] - [[codebase/pi-model-selection]] +- [[codebase/psd-dwh-transport]] - [[codebase/workflow-ui-contracts]]