Rendered from docs/design/secrets-sgit-ai__mvp-build-brief.md, which is the source of truth and the markdown twin of this page. Rendered at site v0.1.2.

secrets.sgit.ai — MVP build brief

Status: brief, written to be executed · 5 October 2026 · for the Claude Code session working in SGit-AI/SGit-AI__Website__Secrets · CC BY 4.0

A zero-knowledge secrets manager that runs entirely in the browser. The site is static on GitHub Pages. The only cloud is one GCP project per environment, holding Identity Platform (login) and a Cloud Storage bucket (ciphertext). The browser does every cryptographic operation. A full compromise of the GCP project, the Identity Platform admin or the bucket yields ciphertext and login metadata, never a secret. Everything in this repository is public, including the configuration of every environment, because nothing in it is secret.

0. How to use this brief

1. Read sections 1–4 before writing anything. They hold the decisions that are already made; do not reopen them.
2. The build order in section 11 is the plan. Each step has acceptance criteria. Ship the pipeline first, then the content, then the app, then admin and tests. Every push to dev is a release.
3. Copy the four design documents listed in section 2 into docs/design/ on your first commit, unchanged. They are the reasoning; this brief is the instruction.
4. Where this brief says PROPOSED or VERIFY FIRST, test before building on it. Where you find this brief wrong, correct it in docs/design/brief-corrections.md with what you found, and carry on.
5. The house rules are at coding.sgit.ai and nfrs.sgit.ai. Section 7 extracts what applies here. When in doubt, read https://coding.sgit.ai/llms-full.txt and https://nfrs.sgit.ai/llms.txt.

What exists today: the repository, with README, Apache-2.0 LICENSE and a Python .gitignore, on branches dev and main. Nothing else.

1. What this is

One sentence. A password-manager-shaped app where the "passwords" can be anything small and secret — passwords, API keys, sgit vault keys and read keys, PKI private keys, short notes — unlocked by a passkey, stored as ciphertext in a GCP bucket the user's login can reach, and readable by no one else, including the people who run the bucket.

Why it exists. It is the MVP for the key-vault layer under Risk Mandate and sgit: identity plus key storage, with every hard piece (login, browser-direct storage, passkey PRF unlock, keyring format, device enrolment, recovery, sharing) in one small, testable product. If an admin with full GCP access cannot read a stored password, the same model holds for vault keys. sgit's own docs say sgit is not a secrets manager and its partnerships page asks for exactly this: browser first, key kinds kept apart, release only on approval, end-to-end sharing, revocation, keys for agents. This site answers that call from inside the family.

Principles (non-negotiable).

2. Design documents (copy into docs/design/)

These were written before this brief and carry the reasoning. Copy them in verbatim as the first commit's docs/design/*.md.

Decisions carried over from them, so you do not have to re-derive:

• All-GCP, one project per environment and per customer; project is the create/destroy unit.
• Identity Platform for login (Google sign-in + email/password now; OIDC/SAML federation later), Cloud Storage for Firebase with Security Rules for browser-direct storage.
• Passkey with WebAuthn PRF derives the keyring-wrapping key. Recovery code as the second unlock method. Lose both and the data is gone; the site says so.
• Keyring holds the user's private key and every secret; one unlock opens everything.
• Sharing uses a key pair per user, a public-key directory and an inbox of keys encrypted to the recipient. Phase 2 for the UI, but the data model ships in phase 1 (the key pair is generated and stored from the first keyring).
• Name is secrets, not secrets-manager; short nouns match the family and avoid confusion with AWS Secrets Manager and GCP Secret Manager, which are server-side stores for machine secrets.

3. Architecture

3.1 Components

3.2 Flows

First run. Sign in (Identity Platform) → no keyring at users/{uid}/keyring.json → create passkey with PRF → generate keyring key (KEK), key pair, recovery code → write encrypted keyring → show recovery code once → done.

Returning. Sign in → fetch keyring → navigator.credentials.get with PRF eval → HKDF → unwrap KEK → decrypt body into memory → UI. Nothing decrypted is ever written to storage, localStorage, sessionStorage or IndexedDB.

New device. Sign in → fetch keyring → unlock via a synced passkey, cross-device passkey (QR) or the recovery code → register a new passkey → add a wrapped-KEK entry → write keyring (with optimistic concurrency, see 8.5).

Admin. Open /admin/ → choose environment → "Sign in with Google for admin" (OAuth implicit flow, scope cloud-platform, token in memory only) → each check calls a GCP API; green/red/fix.

3.3 Origins and the passkey scope (the single most important decision)

• RP ID is exactly secrets.sgit.ai. Never sgit.ai: a passkey scoped to the apex can be asserted by any of the 27+ sibling sites, and a compromise of any sibling repo would unlock every user's secrets.
• The app runs on one origin and loads nothing from any other origin except Google's auth endpoints (popup/redirect, no script injection). All libraries are vendored (section 7.3).
• riskmandate.ai and other consumers will use their own passkey or WebAuthn Related Origin Requests later. Out of scope for the MVP.

3.4 What a compromised party gets

The last row is why section 9.5 exists. Say this on the site's security page in plain words.

4. GCP environments

4.1 Environments and naming

One site serves all environments. The environment is chosen at runtime by browser configuration (section 5), with prod as the default on secrets.sgit.ai. A customer running their own project either uses the public site pointed at their project (config) or forks the repo and changes config/environments.json.

4.2 Per-project resources (what Terraform creates)

Terraform lives in infra/terraform/, one module modules/secrets-env, one root per environment in infra/terraform/envs/{dev,main,prod}/. State in a GCS bucket in a separate bootstrap project (sgit-secrets-tfstate, PROPOSED), one prefix per env.

1. Project services: identitytoolkit.googleapis.com, firebase.googleapis.com, firebasestorage.googleapis.com, storage.googleapis.com, firebaserules.googleapis.com, cloudresourcemanager.googleapis.com, serviceusage.googleapis.com, iam.googleapis.com.
2. Firebase project link: google_firebase_project (google-beta provider).
3. Web app registration: google_firebase_web_app → yields appId; read google_firebase_web_app_config for apiKey, authDomain, storageBucket. These are public identifiers, written into config/environments.json by the pipeline. Restrict the API key by HTTP referrer to https://secrets.sgit.ai/* and http://localhost:* (dev only).
4. Identity Platform: google_identity_platform_config with sign_in { email { enabled = true } }, authorized_domains = ["secrets.sgit.ai", "localhost"], multi-tenancy off for the MVP (on for customers that want several user pools in one project; the app already passes tenantId when configured).
5. Google provider: google_identity_platform_default_supported_idp_config with idp_id = "google.com", client_id, client_secret. The client is a Web application OAuth client in the same project, authorised JavaScript origin https://secrets.sgit.ai, authorised redirect https://<authDomain>/__/auth/handler. The client secret is a GitHub Actions environment secret, passed as a Terraform variable; it never enters the repo. (The secret is only ever used by Google's own token exchange; it is not a secret the app holds.)
6. Admin OAuth client: a second Web application client, used only by /admin/ and /tests/ for the cloud-platform scope, authorised JavaScript origin https://secrets.sgit.ai (plus http://localhost:8000 on dev), authorised redirect https://secrets.sgit.ai/admin/oauth-return.html. Its client id is public and goes into config/environments.json. Its secret is unused (implicit flow) and stays in the project.
7. Bucket: google_storage_bucket with uniform bucket-level access, versioning on, a soft-delete retention of 30 days, CORS for https://secrets.sgit.ai (methods GET, PUT, POST, DELETE, HEAD; response headers Content-Type, x-goog-meta-*, ETag, x-goog-generation), lifecycle: keep 10 noncurrent versions. Link to Firebase with google_firebase_storage_bucket.
8. Security Rules: google_firebaserules_ruleset + google_firebaserules_release named firebase.storage/{bucket} from infra/rules/storage.rules (section 8.6).
9. IAM: the Terraform service account tf-secrets@… with Editor on the project (narrow later); a secrets-admins Google group (or named accounts) with roles/owner on the project, which is what makes the admin pages work for those people; nothing else. No service account keys, anywhere.
10. Workload Identity Federation: pool github, provider github-actions restricted to assertion.repository == "SGit-AI/SGit-AI__Website__Secrets" and the dev/main branches or the environment name; binding roles/iam.workloadIdentityUser to the Terraform service account.

4.3 Bootstrap (done once, by a human, documented in docs/ops/bootstrap.md)

The first project and the WIF pool cannot be created by the pipeline that depends on them. The bootstrap is a short gcloud script in infra/bootstrap/bootstrap.sh, run by Dinis locally, that creates the tfstate project and bucket, the three env projects, enables billing, creates the Terraform service account and the WIF pool, and prints the values that go into GitHub environment variables. The script is idempotent and prints what it would do with --dry-run. Everything after bootstrap is Terraform.

4.4 What a customer runs

docs/ops/new-environment.md: "You have a GCP org and a billing account. Run bootstrap for one project, add your domain to authorized_domains, run Terraform, paste the printed config into the site's Environment page (or into your fork's config/environments.json)." Target: under thirty minutes with no support. The admin pages' setup checklist (section 6.3) verifies each step.

4.5 Identity Platform notes

• Use popup sign-in (signInWithPopup) by default; redirect sign-in relies on the authDomain helper and third-party cookies, which fail on GitHub Pages in Safari and increasingly in Chrome. Offer signInWithRedirect only as a fallback switch on the Environment page.
• Add secrets.sgit.ai and localhost to Identity Platform authorised domains, or every sign-in fails with auth/unauthorized-domain. The admin checklist tests this.
• Identity Platform's own passkey support is not used. The unlock passkey is a plain WebAuthn credential registered by our page.
• Pricing reference: free to 50,000 MAU on basic providers; SAML/OIDC free only to 50 MAU.

4.6 The one external dependency: Google's auth endpoints

The app contacts https://<project>.firebaseapp.com/__/auth/* (the Firebase auth helper, in a popup) and https://accounts.google.com (the OAuth consent, in a popup or redirect). Both are separate browsing contexts; neither injects a script into our origin. That is the whole external surface of the app pages. Admin pages add https://*.googleapis.com REST calls with the user's own token. No Google Identity Services script, no gapi, no analytics, no fonts from CDNs.

5. Browser-side environment configuration

The site ships config/environments.json (generated by the pipeline from Terraform outputs; validated by the gate):

{
  "version": 1,
  "default": "prod",
  "environments": {
    "prod": {
      "label":              "secrets.sgit.ai (production)",
      "projectId":          "sgit-secrets-prod",
      "apiKey":             "AIza…public web api key…",
      "authDomain":         "sgit-secrets-prod.firebaseapp.com",
      "storageBucket":      "sgit-secrets-prod.firebasestorage.app",
      "appId":              "1:…:web:…",
      "adminOauthClientId": "….apps.googleusercontent.com",
      "tenantId":           null,
      "region":             "europe-west2",
      "signInMethod":       "popup"
    },
    "main": { "…": "…" },
    "dev":  { "…": "…" }
  }
}

Rules:

• Every value in this file is a public identifier. The leak tripwire (section 9.3) must not flag AIza… web API keys from this file; add a line-level allow for config/environments.json and document why (Firebase web API keys are not secrets; they are restricted by referrer).
• The app reads the active config from localStorage['sgit.secrets.config.v1'] if present, else from the file's default. The Environment page (/app/environment.html) lets the user pick a built-in environment or enter a custom one (all fields above), export it as JSON, import one, and reset. ?env=dev in the URL selects a built-in environment for that load and persists it.
• Nothing secret is ever stored in localStorage. The only other localStorage keys are UI conveniences (sgit.secrets.ui.theme, sgit.secrets.ui.lastEnv). Every read is wrapped in try/catch and the app works when storage is empty.
• Changing environment signs the user out and clears every in-memory key.
• The active environment is shown in the app header at all times (prod in neutral, anything else in a coloured badge) so nobody enters a real secret into dev by mistake.

6. The site

6.1 Structure

/                         index.html + index.md     what it is, what is shipped, the three-step demo
/how-it-works/            the flows, drawn; what each party can and cannot see
/security/                the threat model (3.4), the RP ID decision, the code-is-the-boundary statement, what we ask you to trust
/keyring/                 the file format (section 8), published as a specification with versions
/sharing/                 the sharing scheme, marked PROPOSED until the UI ships
/environments/            how environments and customer deployments work; the setup guide
/shipped/                 what is built vs proposed vs absent, per feature, generated from data/features.json
/app/                     the application (6.2)
/admin/                   admin pages (6.3)
/tests/                   test and probe pages (6.4)
/docs/design/             the four design docs, rendered
/admin/versions.html      release history, generated
/llms.txt  /llms-full.txt /index.md  /sitemap.xml  /robots.txt  CNAME
/.well-known/             reserved for sgit-agents.json (agent contact) later; not in MVP

Every HTML page has a .md twin generated from the same source. The chrome (nav, footer, version badge, environment badge on app pages) is one definition in admin/build/chrome.py.

6.2 App pages (/app/)

Entry kinds (the "kinds kept apart" rule): password, api-key, sgit-vault-key, sgit-read-key, pki-private-key, note. Each kind has its own fields and its own reveal behaviour; an sgit-vault-key entry displays its prefix (sgit_private_vault_…) and refuses to be put in a shareable (phase 2) set without a confirmation. Kinds are a closed list in app/kinds.js, frozen.

Lock behaviour: keys cleared from memory on sign-out, environment change, tab hidden for more than 5 minutes (configurable), and on beforeunload. Clipboard copies clear after 30 s where the Clipboard API allows.

6.3 Admin pages (/admin/)

Admin pages work only when the visitor signs in with a Google account that has IAM on the selected environment's GCP project. There is no "admin role" in the app: the GCP project's IAM is the role, and the pages are a client for GCP's own APIs.

Auth. admin/oauth.js implements the OAuth 2.0 implicit flow by redirect to https://accounts.google.com/o/oauth2/v2/auth with response_type=token, scope=https://www.googleapis.com/auth/cloud-platform, client_id from config, redirect_uri=https://secrets.sgit.ai/admin/oauth-return.html, a random state kept in sessionStorage; the return page reads the fragment, validates state, keeps the access token in memory only (never storage), and clears the fragment from history. No external script. Token lifetime is about an hour; the pages re-prompt when a call returns 401. VERIFY FIRST: that Google still issues implicit-flow tokens for a Web application client with these origins; if not, switch to Authorization Code with PKCE using a client of type "Desktop" (no secret required) and note the change.

Every write action shows the exact request it will send before sending it, and logs the response on the page. Admin pages never touch a keyring's contents (they cannot; they are ciphertext) and never store the token.

Hardening noted for later, not MVP: move /admin/ and /tests/ to their own origin (admin.secrets.sgit.ai, second repo) so that nothing with cloud-platform tokens runs in the vault's origin.

6.4 Test and probe pages (/tests/)

Each page is self-contained, runs in the browser, needs no secrets, and prints a result table with PASS/FAIL/SKIP and the raw values behind each row. They double as the compatibility matrix: a visitor can run them on any device and paste the result into an issue.

6.5 The content pages: what they say

The site publishes its argument before the thing is finished, in the family's manner. Each content page carries a status line (shipped vX.Y.Z / proposed / absent) generated from data/features.json. The homepage leads with the three-step demo (sign in, passkey, see your secret) and a one-line statement of the model, then the "what a compromised admin gets" table, then the shipped/proposed table. No feature is described in the present tense until features.json says shipped.

7. House style (from coding.sgit.ai and nfrs.sgit.ai)

7.1 JavaScript

• Native web components, no framework, no build step, ESM everywhere (<script type="module">).
• The three-file triplet per component: sg-secrets-<name>.js/.html/.css under components/sg-secrets-<name>/v0/v0.1/v0.1.0/; static jsUrl = import.meta.url; get resourceName(); get sharedCssPaths(); onReady() not connectedCallback.
• 4-space indent, single quotes, no semicolons, trailing commas in multi-line literals, aligned object keys, _ prefix for private, Object.freeze on exported constants, JSDoc banner on components.
• Events namespaced sg-secrets: through document with bubbles: true, composed: true.
• Shared state via small modules (app/state/session.js holds the unlocked keyring in a closure; nothing exports the raw keys).

7.2 HTML / CSS / Python

• HTML fragments 2-space indented; ARIA on controls; data-* as the behaviour hook; the chrome is injected by the generator.
• CSS: design tokens in assets/sg-tokens.css (copy the family's tokens, pin the version in a comment); :host scoping; per-block value alignment.
• Python (generators and tests): TypeSafe style, one class per file, banner comments, no docstrings, `init.py empty; test files test*.py` with no mocks (the generators are tested by running them on the tree).

7.3 Dependencies: vendored, pinned, hashed

vendor/ holds every third-party file the app loads, with vendor/MANIFEST.json listing source URL, version, SHA-256, licence. The gate (9.3) recomputes the hashes. Expected contents:

• sg-component.js (the family base class, copied from the CDN path and pinned) and sg-tokens.css.
• Firebase JS SDK modular ESM bundles for app, auth, storage (the firebase-*.js files from the pinned gstatic path), referenced by relative import. No runtime fetch from gstatic.
• Nothing else. No crypto libraries: WebCrypto only. No base32/base64 libraries: write the forty lines.

7.4 Documentation rules

• Every page has a .md twin; index.md and llms.txt are generated; llms-full.txt concatenates every page and every design doc.
• "If the reality document doesn't list it, it does not exist": docs/reality.md is the list of what is built, regenerated from data/features.json on every release. Briefs are aspirations; this brief is an aspiration until reality.md says otherwise.
• Every number on a page comes from a data file or carries an as-of date.
• Agents never push to dev directly from a session branch without the gate passing; branch naming claude/<description>-<session-id>.

8. Keyring and crypto specification (v1)

Publish this at /keyring/ as the format spec. Known-answer fixtures live in tests/fixtures/keyring-v1/ and the crypto test page checks them.

8.1 Objects in the bucket

users/{uid}/keyring.json          the encrypted keyring (one object, versioned by GCS)
users/{uid}/meta.json             { "v":1, "createdAt", "keyringRev", "devices":[{"id","name","createdAt","lastUsedAt"}] }   (not secret)
directory/{uid}.pub.json          the user's public-key bundle, signed (phase 1 writes it; phase 2 reads it)
inbox/{uid}/{shareId}.json        keys encrypted to this user (phase 2)

8.2 Key hierarchy

passkey PRF output (32 bytes, from authenticator, never stored)
  └─ HKDF-SHA256(ikm=prf, salt=keyring.prfSalt, info="sgit-secrets/v1/wrap/<credentialId>") → WK_passkey (AES-256-GCM key)
recovery code (26 chars base32, 128 bits, shown once)
  └─ HKDF-SHA256(ikm=code bytes, salt=keyring.prfSalt, info="sgit-secrets/v1/wrap/recovery") → WK_recovery
KEK (32 random bytes)             wrapped once per unlock method, under WK_*
  └─ decrypts body
body (AES-256-GCM under KEK)     { privateKeys, entries[] }

PRF input salt: keyring.prfSalt (32 random bytes, fixed for the keyring's life) is passed as prf.eval.first. One salt for all passkeys; the per-credential HKDF info keeps the wrapping keys apart. (The authenticator's PRF is already per-credential; the info string is belt and braces.)

Recovery-code KDF: HKDF alone is fast; an attacker holding the keyring can brute-force a weak code. 128 bits of entropy makes that irrelevant, which is why the code is long and machine-generated, never user-chosen. Do not add PBKDF2 "for safety"; it only slows legitimate recovery.

8.3 keyring.json

{
  "v": 1,
  "keyringId": "uuid",
  "rev": 7,
  "prfSalt": "base64(32)",
  "wraps": [
    { "id": "pk-<credentialId b64url>", "kind": "passkey",  "name": "MacBook Chrome", "createdAt": "…", "iv": "b64", "ct": "b64" },
    { "id": "recovery-1",               "kind": "recovery", "createdAt": "…",                            "iv": "b64", "ct": "b64" }
  ],
  "body": { "iv": "b64", "ct": "b64", "aad": "keyringId|rev" }
}

• wraps[].ct is AES-256-GCM of the 32-byte KEK under WK_*, AAD = keyringId|wrap.id.
• body.ct is AES-256-GCM of the UTF-8 JSON body under KEK, AAD = keyringId|rev, so a body cannot be transplanted between keyrings or revisions.
• Decrypted body:

{
  "v": 1,
  "keys": {
    "encrypt": { "alg": "RSA-OAEP-4096", "jwk": { "…private…" } },
    "sign":    { "alg": "ECDSA-P256",    "jwk": { "…private…" } }
  },
  "entries": [
    { "id": "uuid", "kind": "password", "title": "…", "createdAt": "…", "updatedAt": "…", "fields": { "username": "…", "password": "…", "url": "…", "notes": "…" }, "tags": [] }
  ]
}

The key pair algorithms match sgit pki (RSA-OAEP 4096 for encryption, ECDSA P-256 for signing) so that a phase-2 share envelope can be the sgit hybrid envelope and sgit pki decrypt can open what the browser sealed. The public bundle written to directory/{uid}.pub.json uses sgit's JSON bundle shape {v, encrypt, sign, label, fingerprint, signing_fingerprint} with PEM blocks; VERIFY FIRST against https://sgit.ai/docs/pki.md before freezing.

8.4 Entry size and documents

Entries are small (soft limit 16 KB each, keyring soft limit 1 MB). Documents are not stored in the keyring: a document kind is absent in the MVP and, when it comes, will be a pointer to an sgit vault plus that vault's key. Say so on /shipped/.

8.5 Concurrency

Writes use GCS preconditions: x-goog-if-generation-match (via the Firebase SDK's metadata or the JSON API) against the generation read at unlock. On mismatch, re-fetch, re-unlock with the in-memory KEK (no new gesture: the KEK is already in memory), three-way merge entries by id and updatedAt, bump rev, retry once, else surface a conflict page. rev is also in the AAD so a stale body fails to decrypt rather than silently winning.

8.6 Security Rules (infra/rules/storage.rules)

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    function signedIn()        { return request.auth != null; }
    function isOwner(uid)      { return signedIn() && request.auth.uid == uid; }
    function sameTenant()      { return true; }   // tenant check added when multi-tenancy is on; see admin checklist

    match /users/{uid}/{file=**}   { allow read, delete: if isOwner(uid) && sameTenant();
                                     allow write:        if isOwner(uid) && sameTenant() && request.resource.size < 2 * 1024 * 1024; }
    match /directory/{uid}.pub.json { allow read: if signedIn(); allow write: if isOwner(uid) && request.resource.size < 16 * 1024; }
    match /inbox/{uid}/{shareId}    { allow create: if signedIn() && request.resource.size < 64 * 1024; allow read, delete: if isOwner(uid); }
  }
}

The tests/storage.html page asserts the owner path works and a foreign path returns 403; rules.html in admin diffs this file against what is deployed. VERIFY FIRST the exact rule syntax for the size and null checks; simplify rather than guess.

8.7 Passkey details

• create: rp: { id: 'secrets.sgit.ai', name: 'secrets.sgit.ai' }, user.id = 32 random bytes stored in meta.json (not the Firebase uid, which is not a secret but should not be a WebAuthn handle either), pubKeyCredParams ES256 then RS256, authenticatorSelection: { residentKey: 'required', userVerification: 'required' }, extensions: { prf: {} }. Check prf.enabled; if false, tell the user this authenticator cannot be used for unlock and offer recovery-code-only or another authenticator.
• get: rpId, allowCredentials from meta.json devices, userVerification: 'required', extensions: { prf: { eval: { first: prfSalt } } }. Read getClientExtensionResults().prf.results.first.
• Store the credential id and the public key only in meta.json for display and allowCredentials; we never verify the assertion signature (there is no server to verify it for; the PRF output is the proof that matters). Say this on /security/ so nobody assumes a WebAuthn login happened.
• Known support (dated 2026-10-05, re-check on /tests/webauthn-prf.html): Chrome/Edge on macOS, Windows and Android with Google Password Manager; Safari 18+ with iCloud Keychain; hardware keys with hmac-secret. Build the matrix page before promising more.

9. CI/CD and DevOps pipelines

All workflows in .github/workflows/. Branch model: work on claude/* or feature branches → PR to dev → push to dev is a release → main is promoted from dev and is deploy-only (no tag), used as a fallback and as the branch main environment tests against.

9.1 deploy-pages.yml — validate → tag-release → deploy (the house pipeline)

Triggers: push to dev and main, PR to either, manual dispatch.

The release commit is not always HEAD (merge commits); anchor on the newest versioned subject. Every push to dev is a minor bump; patch versions are for a same-day fix and must still be in the subject.

9.2 infra.yml — Terraform per environment

Triggers: PR touching infra/** (plan only, posted as a PR comment per env), manual dispatch with inputs environment ∈ {dev, main, prod, custom} and action ∈ {plan, apply}, and push to dev for dev apply.

• Auth: google-github-actions/auth@v2 with workload_identity_provider and service_account from GitHub environment variables (dev, main, prod environments; prod requires a reviewer).
• terraform fmt -check, validate, plan -out, apply the saved plan only.
• After apply: run infra/scripts/export_env_config.py which reads Terraform outputs and rewrites that env's block in config/environments.json; open a PR to dev with the change (never commit directly). The validate gate will refuse a config whose values do not match the environment's Terraform state file hash recorded in the file (_source field).
• Secrets: GOOGLE_OAUTH_CLIENT_SECRET per GitHub environment. No JSON key files.

9.3 The gate: admin/build/validate.js (no dependencies)

1. Version agreement: version.txt == every page badge == versions table row == llms.txt == llms-full.txt == index.md == config/environments.json#siteVersion; no version listed twice.
2. Internal links and fragments resolve, in every HTML and MD file.
3. Canonical host: every page has rel=canonical and og:url on the host in CNAME.
4. Leak tripwire on every file in the tree: sgit vault keys (sgit_private_vault_, sgit_private_read_, passphrase:uuid shape), AWS AKIA/ASIA, GitHub gh[pousr]_, sk-/sk-ant-, PEM private key blocks, Slack xox[bpa]-, Google OAuth client secrets (GOCSPX-), service-account JSON ("private_key_id"), bare 12-digit numbers. Allow-list: validate.js itself and config/environments.json for AIza web keys only. The fix for a trip is always a redaction, never a wider pattern.
5. Vendor manifest: every file under vendor/ matches its SHA-256 in MANIFEST.json; no <script src="http or import 'http anywhere under app/, components/, admin/, tests/ except the allow-listed Google auth hosts in app/auth/.
6. Storage rules in sync: infra/rules/storage.rules hash equals the hash recorded in data/features.json#rulesHash (so a rules change without a release note fails).
7. Reality: docs/reality.md regenerated from data/features.json with --check.
8. No storage of secrets in code: grep for localStorage.setItem( and assert each key is in the allowed list in app/config/storage-keys.js.

9.4 Other workflows

• tests-browser.yml: on PR and nightly, Playwright (Chromium) runs tests/e2e/ against a local python3 -m http.server of the tree with ?env=dev, using a Firebase email/password test user created by Terraform in dev only and a virtual authenticator (CDP WebAuthn.addVirtualAuthenticator with hasPrf: true VERIFY FIRST; if the virtual authenticator cannot do PRF, the e2e covers everything up to the gesture and the PRF path stays on the manual matrix). Credentials for the test user are GitHub environment secrets; they protect nothing but dev.
• rules.yml: manual dispatch deploy rules to <env>; same WIF auth; firebase deploy --only storage or the Rules API; posts the ruleset name.
• link-check.yml: weekly external link check, opens an issue.
• dependabot.yml is off (no package.json for the app); vendor/ updates are a manual, reviewed PR with hash changes.

9.5 Repository protections (the boundary, section 3.4)

Set on day one and listed on /security/:

• dev and main protected: PR required, one review, no force-push, linear history; status checks validate required.
• All org members with write: hardware-key 2FA (org setting).
• Actions: pin every third-party action by commit SHA; permissions: minimal per job (contents: read, pages: write, id-token: write only where needed); environment prod with required reviewers; GITHUB_TOKEN not allowed to approve PRs.
• Verified domain sgit.ai in the GitHub org (subdomain-takeover guard). DNS: registrar lock, DNSSEC and a CAA record are the DNS owner's job; the security page says whether they are in place (dated).
• <meta http-equiv="Content-Security-Policy"> on every app/admin/test page: default-src 'self'; connect-src 'self' https://*.googleapis.com https://*.firebaseapp.com https://accounts.google.com https://securetoken.googleapis.com https://identitytoolkit.googleapis.com; frame-src https://*.firebaseapp.com https://accounts.google.com; img-src 'self' data:; style-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'; form-action 'none'. Plus a frame-busting check (if (top !== self) …) since frame-ancestors cannot be set in a meta tag. Keep the list exact and tested on tests/config.html.

10. Testing

No mocks: the unit tests run the real WebCrypto; the e2e runs the real dev project. The only stand-in is the virtual authenticator, and only if it does PRF.

11. Build order

Every step ends with a release (site vX.Y.Z : …) and an entry in data/features.json so /shipped/ and docs/reality.md are true at every version.

Do not start step 4 until step 3's probe pages are green on a real dev project; do not start step 7 before step 6, because the admin users page needs meta.json.

12. Open questions, and what not to do

Open (test, then record the answer in docs/design/brief-corrections.md):

• Does the Playwright virtual authenticator support PRF? Decides how much of the e2e is automated.
• Does Google's implicit flow still work for a Web client with our origins? Decides the admin auth implementation (6.3).
• Exact Security Rules syntax for size/null checks (8.6), and whether request.auth.token.firebase.tenant is available in Storage rules.
• Where Identity Platform stores user records (data residency note for /environments/).
• Does sgit pki import accept a browser-generated bundle (8.3)? Decides whether phase-2 envelopes are sgit-native.

Do not:

• Do not add a server, a Cloud Function, a proxy or "just a small API". If something needs one, it is out of scope and goes in docs/design/brief-corrections.md as a proposal.
• Do not store anything derived from a key in any browser storage, even "encrypted".
• Do not load any script from any origin at runtime. Vendor it, hash it, or do without.
• Do not use the apex domain as RP ID, ever, even on localhost testing (use localhost as RP ID there).
• Do not put a document kind, a browser extension, autofill, or an agent API in the MVP. Each is a later site or a later version.
• Do not describe a feature in the present tense before features.json says shipped.

13. The prompt to paste into the Claude Code session

You are working in SGit-AI/SGit-AI__Website__Secrets, the repository for secrets.sgit.ai, a static site on GitHub Pages that is also a zero-knowledge, browser-only secrets manager backed by one GCP project per environment (Identity Platform + Cloud Storage for Firebase). Read docs/design/secrets-sgit-ai__mvp-build-brief.md in full first; it is the instruction set, and sections 1–4 hold decisions that are closed. Then read the four design documents it names in docs/design/. House style is https://coding.sgit.ai/llms-full.txt and https://nfrs.sgit.ai/llms.txt; section 7 of the brief extracts what applies.

Rules you never break: no server-side code of any kind; plaintext only in the browser after a passkey gesture; nothing secret in the repo; no build step and no runtime script from any other origin (vendor and hash instead); the passkey RP ID is exactly secrets.sgit.ai; every push to dev is a release tagged by CI from admin/build/version.txt and a commit subject of the form "site vX.Y.Z : <what>"; a release that fails the gate locally fails the same way in CI; every claim on the site carries a status from data/features.json.

Work through section 11 in order. Step 1 is the pipeline before the site: layout, version file, chrome generator, the eight-check gate in admin/build/validate.js, deploy-pages.yml with validate → tag-release → deploy → verify-live, CNAME, branch protection notes, and docs/design/ populated. Do not begin step 4 until the dev GCP project exists and tests/auth.html, tests/storage.html and tests/webauthn-prf.html are green against it. When the brief is wrong, write what you found in docs/design/brief-corrections.md and continue; when something needs a human (DNS, billing, bootstrap, reviewer approval), stop and list exactly what you need in docs/ops/needs.md.

Start by printing the repository layout you intend to create and the contents of version.txt, then create step 1.

Written from the Risk Mandate / sgit design session of 4–5 October 2026. Companion documents: the four design docs in section 2. This brief is itself to be published at /docs/design/ on the site, with its corrections file beside it.