Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Write ADR 0027 — confidential verified-serving tier (universal image in a Dstack CVM)

Aperta
  • Qualcosa non va?
#490 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
54/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
docker, github, postgresql, typescript
Ambito
documentation, infrastructure, security

Direzione di ricerca

Read docs/adr/0021-universal-runtime-image.md, docs/adr/0020-child-bundle-storage-r2.md, and docs/adr/README.md for the existing decisions and ADR style. Write docs/adr/0027-confidential-verified-serving-tier.md with the two verification channels, both boot paths, attestation flow, and required honest limits; then add its index row and bump the next-free note to 0027. Done when the acceptance criteria are met.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation ready-for-agent

What to build

Write docs/adr/0027-confidential-verified-serving-tier.md — a decision doc recording a new optional runtime tier: the universal image (ADR 0021) run inside a Phala Dstack CVM (Intel TDX), providing end-to-end verifiability of the serving process — SSR output, API/auth behavior, key custody — which SRI pins alone cannot cover. Update docs/adr/README.md (index row + "next free" note bumped to 0027).

Core framing: two verification channels

End-to-end verifiability decomposes into two channels, one already owned by the repo:

Channel Covers Mechanism Status
Static bytes UI/plugin bundles the browser loads SRI pins in the on-chain FastKV config (ADR 0020 amendments), browser-enforced; host-side SRI-before-load (beta-v2 map decision #5) Already designed
Serving process SSR HTML, API/auth behavior, key custody Hardware attestation of the universal image running in a Dstack CVM This ADR

The naive proposal ("verify the container hash matches the JS you see") conflates the two — the ADR decomposes them honestly, then binds them together.

Decision points to record
  1. New optional tier: confidential instance. Same universal image, digest-pinned Dstack compose; a hosting mode selected at deploy, not a second architecture. Root stays on Railway/CDN; opt-in per tenant.
  2. Digest-pinned compose. The Dstack compose pins the image by GHCR digest — the deploy train already produces BOS_IMAGE_DIGEST, and Dstack best practice is digest pinning so RTMR3's compose-hash traces to exact bytes.
  3. Boot paths — both designed, Path A is the default:
    • Path A (default): self-contained boot. Own namespace staged in the image (ADR 0021 tier detection); the measurement covers every served byte. Changes require an image redeploy.
    • Path B: CDN-fetch boot, pin-gated. Registry-tier boot allowed for confidential instances: the enclave hard-gates every fetched/served bundle against the FastKV config's SRI pins (beta-v2 #5's host-side SRI-before-load promoted to a hard gate in this tier) and reports the resolved config hash in runtime data. Minute-level config flips preserved; the measurement covers the verifier rather than the bytes, trust anchored in on-chain pins.
  4. TLS terminated inside the CVM. Dstack's ZT-TLS pattern: keys generated in the TEE, ACME with enclave-held private keys, evidence at /evidences/ bound to the quote's report_data, CAA DNS records on the domain. One origin + one start-stack process means one measurement covers the whole surface: SSR, API, and auth (browser API calls ride the same attested TLS). Gateway-managed *.phala.network TLS is explicitly NOT used — sovereign mode is own domain + own enclave-held TLS.
  5. The differentiating move: config-hash runtime-data binding. The enclave reports the resolved FastKV config hash (+ registry height) in attestation runtime data. The full verification chain — every link a primitive the repo already ships:
    hardware signature → compose-hash ↔ GHCR digest ↔ CI-validated SHA → config hash ↔ FastKV entry at bos://<account>/<gateway> → SRI pins ↔ bytes in the browser
  6. Attestation surface + three verification audiences. Expose /.well-known/attestation (Dstack convention: quote + event log + VM config, nonce freshness via reportData). Audiences: (a) trustless local verification (dcap-qvl / dstack-verifier) for power users and agents — natural future bos verify <domain>; (b) a monitor-backed UI badge for normal users, framed honestly as auditable, not in-browser math; (c) CI verification after each deploy. Future options: on-chain DCAP verification (Automata-style), a FastKV-published measurement allowlist mirroring DstackKms governance on NEAR.
  7. Secret custody as a secondary benefit (not the goal, recorded as such): BETTER_AUTH_SECRET, the relayer/Sponsor ephemeral key, and storage credentials KMS-released only to the whitelisted measurement. Postgres stays outside the enclave; boundary documented honestly.
Honest-limits section (required)
  • Verifier bootstrap circularity (the verifier is served by the enclave it verifies — resolved by vendor-root-anchored quote verification + evidence binding, but stated explicitly).
  • Browsers don't verify attestation natively; for ordinary users this lands as an auditable guarantee / badge, not a felt math check.
  • The measurement covers boot-time state; runtime behavior is covered only via the config-hash binding.
  • SSR output is generated at runtime — attestation proves the code, not each rendered byte.
  • Postgres outside the enclave; DB URL/secret boundary.
  • CVM cost, no serverless, migration re-attestation, debug-mode/TCB-freshness checks.
Status

Proposed, spike-gated — the direction is recorded; implementation is gated on the spike ticket.

Acceptance criteria

  • docs/adr/0027-confidential-verified-serving-tier.md written in repo ADR style (context → decision → limits → consequences)
  • Both boot paths recorded as designed decisions with the tradeoff stated (A: measurement covers bytes; B: trust anchored in pins + enclave verifier)
  • docs/adr/README.md index row added and "next free" note bumped to 0027
  • No changeset required (docs-only)

Context

  • Follows discussion of ADR 0021 (docs/adr/0021-universal-runtime-image.md), ADR 0020 (docs/adr/0020-child-bundle-storage-r2.md), and the beta-v2 wayfinder map decision #5 (publisher attestation + load-time SRI — the confidential tier is the process channel and proceeds independently).
  • Dstack references: RTMR3 measures the compose hash; TLS keys generated in-TEE with evidence bound to the quote; trustless verification via dcap-qvl; zkSecurity audit (2025-08).
  • Spike ticket to follow (blocked by this one).
Lingua principale
TypeScript
Stelle
5
Fork
3
Merge medio
9h 55m
PR unite (30g)
108

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di NEARBuilders/everything-dev

Tutte le issue di NEARBuilders/everything-dev

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.