diff --git a/apps/be/.env.example b/apps/be/.env.example index 76a6ab0b..e74449e6 100644 --- a/apps/be/.env.example +++ b/apps/be/.env.example @@ -61,3 +61,5 @@ NEAR_TEST_PRIVATE_KEY= OUTLAYER_API_KEY= OUTLAYER_HANDOFF_URL= OUTLAYER_SUB_SKILL_PAYMENTS= +# Optional, default https://proof.t16z.com: Phala's TEE Attestation Explorer, where POST /v1/runs/{id}/proof/tee-explorer uploads a run's Intel quote (#277; tests point it at a fake) +TEE_EXPLORER_URL= diff --git a/apps/be/CLAUDE.md b/apps/be/CLAUDE.md index 3dd131fa..5ba4bf79 100644 --- a/apps/be/CLAUDE.md +++ b/apps/be/CLAUDE.md @@ -25,6 +25,7 @@ Backend API: Postgres + pgvector, NEP-413 login, run/event storage + SSE, encryp - **Thread ids are issued by the backend** (`thr_…`). A `threadId` from the browser is only accepted if a run of that same Mind already used it: engine memory is keyed by thread, so a foreign id would read another Mind's history. - The chat relay (`src/runs.ts`) reads the engine stream to the end even when the browser leaves, so `run_events` is complete. Store every event before forwarding it; deltas are batched. A resumed run continues the paused run's `seq`; if the engine restarted (its counter is in memory) the backend shifts the new events after the stored ones. - **Verification proof (#254):** the engine puts the proof behind the badge on `run.verified.verification.proof` (~12 KB, mostly the Intel quote; hashes and keys' addresses only, no conversation text). It is stored whole in `run_events`, but `withoutProof` drops it from every streamed event and `NO_PROOF` from `GET /v1/runs/{runId}` and the Mind Graph's `…/events`; only `GET /v1/runs/{runId}/proof` (owner only, `runProofs`) returns it, one entry per `run.verified` that has one, `404 no_proof` when none. Any new route that returns stored events must strip it too. +- **TEE Explorer link (#277, `src/teeExplorer.ts`):** `POST /v1/runs/{runId}/proof/tee-explorer` (owner only, `getRun`) uploads each Intel quote in the run's stored proofs (`quotesOf`, one per attestation) to Phala's TEE Attestation Explorer through its own upload, `POST {TEE_EXPLORER_URL}/api/upload` with multipart `file` = the quote's bytes (default `https://proof.t16z.com`; read live 12 Nov from its page script: there is no URL that prefills a quote, and the API sends no CORS headers, so the FE cannot call it). It answers `{ runId, reports: [{ attestation, kind, url, verified }] }`, `url` = `/reports/`, a page that already reads VERIFIED (a local run's real gateway quote came back `verified: true`). The checksum must be 64 lowercase hex before it goes into a link. One upload per quote and process (in-memory `reports`, keyed by the quote's SHA-256). Only the quote leaves (NEAR AI's hardware report and nonce, no conversation text); it then shows in the Explorer's public "Recent attestations". `404 no_proof` without one, `503 tee_explorer_unreachable` / `tee_explorer_error` when the Explorer fails (never 502), `422 not_a_quote` for anything but hex. Tests: `test/fake-explorer.ts` and the two `TEE Explorer link (#277)` tests in `test/api.test.ts`. - **Cancel (#121):** each relayed run gets an `AbortController` (passed to `engineFetch` as `signal`, kept in the in-memory `live` map in `src/runs.ts` once its `runId` is known). `POST /v1/runs/{id}/cancel` aborts it; the relay then stores `run.finished` `{ status: "canceled" }` (builder: `workflow.finished`) as the last event, sets `runs.status = 'canceled'` and ends the stream, and the route answers once that is stored. A browser leaving still does **not** cancel. Not live (finished, paused, or after a restart): `409 not_running`; a paused run is declined, not canceled. Single process only: with more than one backend process the map would have to move to Postgres. - **Stuck runs (#218):** `sweepStuckRuns` (`src/runs.ts`, at start and every 5 minutes) ends a run left `running` by a backend that died mid-stream: not in `live`, and no event for `STUCK_AFTER_MS` (5 minutes; the engine gives up after 2). It must look stuck on two sweeps in a row at the same last `seq`, because an approval claims the run (`running`) just before its resumed stream starts. It then gets status `error` and a `run.error` event `run_interrupted`, so it can't block an approval or the chat's delete. - Secrets: AES-256-GCM with `SECRETS_MASTER_KEY`, AAD `userId:name`. Never return values, never log them, decrypt only in `secretsForRun` for one engine call. Host rules match the engine's (`allowedHosts`, lowercase host names, no scheme/port/path). @@ -60,4 +61,4 @@ Backend API: Postgres + pgvector, NEP-413 login, run/event storage + SSE, encryp ## Env -See `.env.example`: `DATABASE_URL`, `ENGINE_URL`, `ENGINE_API_KEY`, `SECRETS_MASTER_KEY` (32 bytes base64; losing it loses every stored secret), optional `PORT`, `FE_ORIGIN`, `AUTH_RECIPIENT`, `NEAR_RPC_URL`, `COOKIE_SECURE`, `OUTLAYER_URL`, `OUTLAYER_CONTRACT_ID`, `DEMO_MODE`, `DEMO_OUTLAYER_API_KEY`, `COMPOSIO_API_KEY`, `COMPOSIO_URL`, `AGENTMAIL_API_KEY`, `AGENTMAIL_API_KEY_2`, `AGENTMAIL_URL`, `DEMO_AGENTMAIL_INBOX`. `.env` is gitignored; never commit it. +See `.env.example`: `DATABASE_URL`, `ENGINE_URL`, `ENGINE_API_KEY`, `SECRETS_MASTER_KEY` (32 bytes base64; losing it loses every stored secret), optional `PORT`, `FE_ORIGIN`, `AUTH_RECIPIENT`, `NEAR_RPC_URL`, `COOKIE_SECURE`, `OUTLAYER_URL`, `OUTLAYER_CONTRACT_ID`, `DEMO_MODE`, `DEMO_OUTLAYER_API_KEY`, `COMPOSIO_API_KEY`, `COMPOSIO_URL`, `AGENTMAIL_API_KEY`, `AGENTMAIL_API_KEY_2`, `AGENTMAIL_URL`, `DEMO_AGENTMAIL_INBOX`, `TEE_EXPLORER_URL`. `.env` is gitignored; never commit it. diff --git a/apps/be/src/server.ts b/apps/be/src/server.ts index cdb3247b..1f60a67e 100644 --- a/apps/be/src/server.ts +++ b/apps/be/src/server.ts @@ -10,6 +10,7 @@ import { HttpError, assertSameOrigin, cors, logServerError, readBody, sendJson, import { TOOLKITS, connect, disconnect, listConnections, toolkitSchema } from './connections.ts' import { createMind, createMindSchema, deleteMind, listMinds, mindConfig, playgroundAttackOf, playgroundMind, requireMind, updateMind, updateMindSchema, type Mind } from './minds.ts' import { cancelRun, getRun, isAwaiting, listRuns, mindEvents, pendingApprovals, relayRun, runEvents, runProofs, sweepStuckRuns } from './runs.ts' +import { explorerReport, quotesOf } from './teeExplorer.ts' import { deleteSecret, listSecrets, putSecret, putSecretSchema, secretNameSchema, secretsForRun } from './secrets.ts' import { addressRuleOf, assertWalletEmpty, createWallet, freezeTransaction, getWallet, hasWallet, isDemoMind, policySchema, policyTransaction } from './wallets.ts' import { listPayments, sendPayment, sendPaymentSchema, walletBalance } from './payments.ts' @@ -392,7 +393,7 @@ export const server = createServer(async (req, res) => { } // Runs (#14, #17) - const run = path.match(/^\/v1\/runs\/([^/]+)(\/approve|\/decline|\/cancel|\/proof)?$/) + const run = path.match(/^\/v1\/runs\/([^/]+)(\/approve|\/decline|\/cancel|\/proof|\/proof\/tee-explorer)?$/) if (run) { const found = await getRun(user.id, decodeURIComponent(run[1])) if (!found) throw new HttpError(404, 'run_not_found') @@ -404,6 +405,15 @@ export const server = createServer(async (req, res) => { if (!proofs.length) throw new HttpError(404, 'no_proof') return sendJson(res, 200, { runId: found.runId, proofs }) } + // The proof's Intel quote(s) checked by Phala's TEE Explorer (#277): the app opens `url`, a report already verified, + // instead of asking the owner to paste the quote. + if (run[2] === '/proof/tee-explorer' && req.method === 'POST') { + const quotes = quotesOf(await runProofs(found.runId)) + if (!quotes.length) throw new HttpError(404, 'no_proof') + const reports = [] + for (const q of quotes) reports.push({ attestation: q.attestation, kind: q.kind, ...(await explorerReport(q.intelQuote)) }) + return sendJson(res, 200, { runId: found.runId, reports }) + } // Stop a run that is still streaming (#121). A run paused for approval has no stream: decline it instead. if (run[2] === '/cancel' && req.method === 'POST') { const stopped = cancelRun(found.runId) diff --git a/apps/be/src/teeExplorer.ts b/apps/be/src/teeExplorer.ts new file mode 100644 index 00000000..f61c8867 --- /dev/null +++ b/apps/be/src/teeExplorer.ts @@ -0,0 +1,59 @@ +// "Paste the quote in TEE Explorer" without the pasting (#277): the run's Intel quote goes to Phala's TEE Attestation +// Explorer through the same upload its own Verify button uses, and the owner gets the report's link, already checked. +// proof.t16z.com has no URL that prefills a quote and its API sends no CORS headers, so the browser can't do this +// itself (read 12 Nov). `POST /api/upload`, multipart `file` = the quote's bytes, answers `{ success, checksum, +// quote: { verified } }`, and the report lives at `/reports/` (a live gateway quote came back verified). +// Only the quote is sent: NEAR AI's hardware report and its nonce, never conversation text. An uploaded report shows +// in the Explorer's public "Recent attestations", as it would if the owner pasted it. +import { createHash } from 'node:crypto' +import { HttpError, UPSTREAM_ERROR, fetchFailure } from './http.ts' + +// Read per call, not at import, so tests can point it at a fake. +const explorer = () => process.env.TEE_EXPLORER_URL ?? 'https://proof.t16z.com' + +export type ExplorerReport = { url: string; verified: boolean } + +// One upload per quote and process: a second click, or the same attestation in several runs, reuses the link. +const reports = new Map() +export const resetExplorerCache = () => reports.clear() + +const HEX = /^(?:[0-9a-fA-F]{2})+$/ +// A TDX quote with its certificates is ~5 KB (10 KB of hex); anything far larger is not one. +const MAX_HEX = 64 * 1024 + +export async function explorerReport(intelQuote: string): Promise { + if (!HEX.test(intelQuote) || intelQuote.length > MAX_HEX) throw new HttpError(422, 'not_a_quote') + const key = createHash('sha256').update(intelQuote.toLowerCase()).digest('hex') + const known = reports.get(key) + if (known) return known + const form = new FormData() + form.append('file', new Blob([Buffer.from(intelQuote, 'hex')], { type: 'application/octet-stream' }), 'quote.bin') + // Upstream failures answer 503, never 502 (Cloudflare replaces a 502 body with its own page; apps/be/CLAUDE.md). + let res: Response + try { + res = await fetch(`${explorer()}/api/upload`, { method: 'POST', body: form, redirect: 'error', signal: AbortSignal.timeout(20_000) }) + } catch (e) { + throw new HttpError(UPSTREAM_ERROR, 'tee_explorer_unreachable', { reason: fetchFailure(e) }) + } + const body = (await res.json().catch(() => ({}))) as { success?: boolean; checksum?: string; quote?: { verified?: boolean } } + // The checksum becomes part of a link the app opens, so only a plain hex one is accepted. + if (!res.ok || !body.success || !/^[0-9a-f]{64}$/.test(body.checksum ?? '')) throw new HttpError(UPSTREAM_ERROR, 'tee_explorer_error', { explorerStatus: res.status }) + const report = { url: `${explorer()}/reports/${body.checksum}`, verified: body.quote?.verified === true } + reports.set(key, report) + return report +} + +type Attestation = { kind?: string; intelQuote?: string } + +// Every attestation with an Intel quote across a run's proofs, each once (a paused run carries one proof per part, +// usually with the same gateway attestation). +export function quotesOf(proofs: { proof: unknown }[]): { attestation: string; kind: string; intelQuote: string }[] { + const seen = new Map() + for (const { proof } of proofs) { + const atts = (proof as { attestations?: Record } | null)?.attestations ?? {} + for (const [attestation, a] of Object.entries(atts)) { + if (typeof a?.intelQuote === 'string' && !seen.has(attestation)) seen.set(attestation, { attestation, kind: a.kind ?? '', intelQuote: a.intelQuote }) + } + } + return [...seen.values()] +} diff --git a/apps/be/test/api.test.ts b/apps/be/test/api.test.ts index 0f5e2673..3d30280d 100644 --- a/apps/be/test/api.test.ts +++ b/apps/be/test/api.test.ts @@ -11,6 +11,7 @@ import { fakeOutlayer, outlayerServer } from './fake-outlayer.ts' import { COMPOSIO_KEY, composioServer, fakeComposio } from './fake-composio.ts' import { fakeTelegram, telegramServer } from './fake-telegram.ts' import { AGENTMAIL_KEYS, agentmailServer, fakeAgentmail } from './fake-agentmail.ts' +import { explorerServer, fakeExplorer } from './fake-explorer.ts' await new Promise((r) => engine.listen(0, r)) process.env.ENGINE_URL = `http://127.0.0.1:${(engine.address() as AddressInfo).port}` @@ -30,6 +31,8 @@ await new Promise((r) => agentmailServer.listen(0, r)) process.env.AGENTMAIL_URL = `http://127.0.0.1:${(agentmailServer.address() as AddressInfo).port}/v0` process.env.AGENTMAIL_API_KEY = AGENTMAIL_KEYS[0] process.env.AGENTMAIL_API_KEY_2 = AGENTMAIL_KEYS[1] +await new Promise((r) => explorerServer.listen(0, r)) +process.env.TEE_EXPLORER_URL = `http://127.0.0.1:${(explorerServer.address() as AddressInfo).port}` const DEMO_INBOX = 'hellonear-demo@agentmail.to' fakeAgentmail.inboxes.push({ inbox_id: DEMO_INBOX, email: DEMO_INBOX, client_id: 'hellonear-demo', org: 0 }) process.env.DEMO_AGENTMAIL_INBOX = DEMO_INBOX @@ -65,6 +68,7 @@ after(async () => { await new Promise((r) => composioServer.close(() => r())) await new Promise((r) => telegramServer.close(() => r())) await new Promise((r) => agentmailServer.close(() => r())) + await new Promise((r) => explorerServer.close(() => r())) await pool.end() }) @@ -624,6 +628,48 @@ describe('chat and runs (#14, #17)', () => { assert.deepEqual(all.map((e: any) => e.seq), all.map((_: unknown, i: number) => i)) assert.equal(all.length, paused.length + 3) }) + + test('the TEE Explorer link (#277): the run\'s Intel quote uploaded once, a verified report for the owner alone', async () => { + const alice = await signIn() + const { mind } = await (await alice.call('POST', '/v1/minds', { templateId: 'general-assistant', name: 'Tia' })).json() + const evs = await events(await alice.call('POST', `/v1/minds/${mind.id}/chat`, { message: 'what time is it?' })) + const runId = evs[0].runId + const before = fakeExplorer.uploads.length + const res = await alice.call('POST', `/v1/runs/${runId}/proof/tee-explorer`, {}) + assert.equal(res.status, 200, await res.clone().text()) + const body = await res.json() + const quote = (fakeProof.attestations as any)['gateway:0xabc'].intelQuote as string + const checksum = createHash('sha256').update(Buffer.from(quote, 'hex')).digest('hex') + assert.deepEqual(body, { runId, reports: [{ attestation: 'gateway:0xabc', kind: 'gateway', url: `${process.env.TEE_EXPLORER_URL}/reports/${checksum}`, verified: true }] }) + // The quote's bytes, not its hex or the whole proof. + assert.equal(fakeExplorer.uploads.length, before + 1) + assert.ok(fakeExplorer.uploads.at(-1)!.equals(Buffer.from(quote, 'hex'))) + // A second click reuses the link. + assert.deepEqual(await (await alice.call('POST', `/v1/runs/${runId}/proof/tee-explorer`, {})).json(), body) + assert.equal(fakeExplorer.uploads.length, before + 1) + // Someone else's run, a run without a proof, and the wrong method. + const bob = await signIn() + assert.equal((await bob.call('POST', `/v1/runs/${runId}/proof/tee-explorer`, {})).status, 404) + const plain = await events(await alice.call('POST', `/v1/minds/${mind.id}/chat`, { message: 'no proof' })) + const none = await alice.call('POST', `/v1/runs/${plain[0].runId}/proof/tee-explorer`, {}) + assert.equal(none.status, 404) + assert.equal((await none.json()).error, 'no_proof') + assert.equal((await alice.call('GET', `/v1/runs/${runId}/proof/tee-explorer`)).status, 405) + }) + + test('the TEE Explorer link (#277): an Explorer that fails answers 503, never 502', async () => { + const { resetExplorerCache } = await import('../src/teeExplorer.ts') + resetExplorerCache() + const alice = await signIn() + const { mind } = await (await alice.call('POST', '/v1/minds', { templateId: 'general-assistant', name: 'Uma' })).json() + const evs = await events(await alice.call('POST', `/v1/minds/${mind.id}/chat`, { message: 'what time is it?' })) + fakeExplorer.down = true + try { + const res = await alice.call('POST', `/v1/runs/${evs[0].runId}/proof/tee-explorer`, {}) + assert.equal(res.status, 503) + assert.equal((await res.json()).error, 'tee_explorer_error') + } finally { fakeExplorer.down = false } + }) }) describe('runs a crash left running (#218)', () => { diff --git a/apps/be/test/fake-explorer.ts b/apps/be/test/fake-explorer.ts new file mode 100644 index 00000000..da8c5c2b --- /dev/null +++ b/apps/be/test/fake-explorer.ts @@ -0,0 +1,20 @@ +// A stand-in for Phala's TEE Attestation Explorer upload (#277): `POST /api/upload` with a multipart `file`, answered +// like proof.t16z.com did on 12 Nov (`success`, `checksum`, `quote.verified`). Every upload is kept, with its bytes. +import { createServer } from 'node:http' +import { createHash } from 'node:crypto' + +export const fakeExplorer = { uploads: [] as Buffer[], down: false } + +export const explorerServer = createServer(async (req, res) => { + const chunks: Buffer[] = [] + for await (const c of req) chunks.push(c as Buffer) + if (fakeExplorer.down) return res.writeHead(500, { 'content-type': 'application/json' }).end('{"error":"down"}') + if (req.method !== 'POST' || req.url !== '/api/upload') return res.writeHead(404).end() + const form = await new Request('http://x', { method: 'POST', headers: { 'content-type': req.headers['content-type'] ?? '' }, body: Buffer.concat(chunks) }).formData() + const file = form.get('file') + if (!(file instanceof Blob)) return res.writeHead(400, { 'content-type': 'application/json' }).end('{"success":false}') + const bytes = Buffer.from(await file.arrayBuffer()) + fakeExplorer.uploads.push(bytes) + const checksum = createHash('sha256').update(bytes).digest('hex') + res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ id: checksum, success: true, checksum, quote: { verified: true } })) +}) diff --git a/docs/api-contract.md b/docs/api-contract.md index 1c7bbf42..12391904 100644 --- a/docs/api-contract.md +++ b/docs/api-contract.md @@ -437,6 +437,7 @@ One OutLayer wallet per Mind, on testnet. The backend keeps the agent key and ne | `GET /v1/minds/{mindId}/runs?threadId&limit=20` | | `{ runs: [{ runId, threadId, workflowId, status, model, usage, costUsd, startedAt, finishedAt }] }` | | `GET /v1/runs/{runId}` | | `{ run, events }` (all stored events, in `seq` order; `run.verified` without `verification.proof`, #254) | | `GET /v1/runs/{runId}/proof` | | `{ runId, proofs: [{ seq, model, level, proof }] }`: the proof behind the verified badge (#254), as the engine put it on each `run.verified` (§3), oldest first; a run paused for approval has one per part, and the last is the reply's. Owner only (`404 run_not_found` otherwise). `404 no_proof` when no part carries one: Incognito, failed verification, a step without evidence, a run still paused, or one from before 11 Nov (#256) **[tested: fake engine sending a 10,012-character quote]** | +| `POST /v1/runs/{runId}/proof/tee-explorer` | `{}` | `{ runId, reports: [{ attestation, kind, url, verified }] }` (#277): each Intel quote in the run's proofs, uploaded by the backend to Phala's TEE Attestation Explorer (its own `POST /api/upload`), so the FE opens `url` (`https://proof.t16z.com/reports/`), a report already checked, instead of asking the owner to paste the quote (the Explorer has no prefill URL and no CORS). One upload per quote. Owner only (`404 run_not_found` otherwise), `404 no_proof`, `503 tee_explorer_unreachable` \| `tee_explorer_error` **[tested: fake Explorer; one real upload from a local run came back `verified: true`, 12 Nov]** | | `GET /v1/minds/{mindId}/events?since=ISO&limit=2000` | | `{ events }` across runs since `since` (default 7 days), deltas left out: Mind Graph history mode (#17) | | `GET /v1/minds/{mindId}/approvals` | | `{ approvals: [{ runId, threadId, toolCallId, tool, args, requestedAt }] }`: runs paused on `tool.approval_required` (#14) | | `POST /v1/runs/{runId}/approve` · `/decline` | `{ toolCallId, reason?, timeZone? }` | SSE continuing the run's `seq`. `409 not_awaiting_approval` unless the run waits for that `toolCallId` in its current pause (an approval from an earlier pause of the same run, e.g. a split bill's first payment, no longer counts), or when it was just answered elsewhere: the backend moves the run from `awaiting_approval` to `running` in one update before resuming, so the app and Telegram (#208) can never resume it twice |