From 532fe8cda341872dc2703af6ff1b21da4f4abda0 Mon Sep 17 00:00:00 2001 From: Lexirieru Date: Thu, 12 Nov 2026 22:05:27 +0700 Subject: [PATCH 1/2] feat(be): open a run's TEE Explorer report already verified (#277) POST /v1/runs/{runId}/proof/tee-explorer uploads the Intel quote(s) in the run's stored proof to Phala's TEE Attestation Explorer through its own POST /api/upload and answers the report links. The Explorer has no prefill URL and no CORS, so the FE couldn't do it, and pasting "Copy the proof" answered "The quote is invalid". One upload per quote; owner only; an Explorer failure answers 503. Tests: bun run test 134/134 (fake Explorer: the quote's bytes uploaded once, second click reused, other user 404, no proof 404, Explorer down 503); bun run load: 0 errors, 0 runs missing events; one real upload from a local run returned verified: true and the report link the owner checked by hand. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e --- apps/be/src/server.ts | 12 ++++++- apps/be/src/teeExplorer.ts | 59 +++++++++++++++++++++++++++++++++++ apps/be/test/api.test.ts | 46 +++++++++++++++++++++++++++ apps/be/test/fake-explorer.ts | 20 ++++++++++++ 4 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 apps/be/src/teeExplorer.ts create mode 100644 apps/be/test/fake-explorer.ts 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 } })) +}) From ddc4d5910e57f25cb8a655df8bb0f03b03dc954e Mon Sep 17 00:00:00 2001 From: Lexirieru Date: Thu, 12 Nov 2026 22:05:27 +0700 Subject: [PATCH 2/2] docs: TEE Explorer link route (#277) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Q5ZrzK8une3S2YyhDG746e --- apps/be/.env.example | 2 ++ apps/be/CLAUDE.md | 3 ++- docs/api-contract.md | 1 + 3 files changed, 5 insertions(+), 1 deletion(-) 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/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 |