Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions apps/be/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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=
3 changes: 2 additions & 1 deletion apps/be/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<checksum>`, 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).
Expand Down Expand Up @@ -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.
12 changes: 11 additions & 1 deletion apps/be/src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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')
Expand All @@ -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)
Expand Down
59 changes: 59 additions & 0 deletions apps/be/src/teeExplorer.ts
Original file line number Diff line number Diff line change
@@ -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/<checksum>` (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<string, ExplorerReport>()
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<ExplorerReport> {
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<string, { attestation: string; kind: string; intelQuote: string }>()
for (const { proof } of proofs) {
const atts = (proof as { attestations?: Record<string, Attestation> } | 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()]
}
46 changes: 46 additions & 0 deletions apps/be/test/api.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<void>((r) => engine.listen(0, r))
process.env.ENGINE_URL = `http://127.0.0.1:${(engine.address() as AddressInfo).port}`
Expand All @@ -30,6 +31,8 @@ await new Promise<void>((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<void>((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
Expand Down Expand Up @@ -65,6 +68,7 @@ after(async () => {
await new Promise<void>((r) => composioServer.close(() => r()))
await new Promise<void>((r) => telegramServer.close(() => r()))
await new Promise<void>((r) => agentmailServer.close(() => r()))
await new Promise<void>((r) => explorerServer.close(() => r()))
await pool.end()
})

Expand Down Expand Up @@ -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)', () => {
Expand Down
20 changes: 20 additions & 0 deletions apps/be/test/fake-explorer.ts
Original file line number Diff line number Diff line change
@@ -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 } }))
})
1 change: 1 addition & 0 deletions docs/api-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<checksum>`), 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 |
Expand Down
Loading