Attestation
The five privacy invariants talk about the wire shape. Attestation answers a different question: is the server I'm talking to actually running the binary the operator published?
Without attestation, a wallet that's careful about wire-shape leakage is still trusting whoever runs the server not to swap the binary out for a logging one. On a TEE host, attestation closes that gap by binding the WebSocket session to a signed, hardware-attested measurement of the software stack. On a host without one, it pins the binary the server reports and binds the session to the operator's signed identity instead.
The two-server split
The reference deployment uses two servers with different roles:
| Server | Role | SEV-SNP | Why |
|---|---|---|---|
wss://weikeng1.bitcoinpir.org | Hint | No (Hetzner) | Sees only the hint blob — never query traffic. |
wss://bitcoin-pir-weikeng-laptop.chenweikeng.com | Query | No (MacBook) | Sees the per-query traffic. |
The query server is the one whose binary a wallet really wants to pin. Hint traffic alone reveals nothing about what the user is querying (an attacker who runs only the hint server can't replay queries — the secret-shared sketch lives in the query server's state).
The query server used to be a VPSBG AMD SEV-SNP host (Tier 3, below) at
wss://weikeng2.bitcoinpir.org. That host was retired on 2026-10-02.
The pir2 roles now run on a MacBook without a TEE (server id
pir2-macbook-v1), so both live servers are checked the same way: a
binary pin plus the operator-signed identity. Direct ORAM needs a TEE:
since 2026-10-03 it runs on its own VPSBG SEV-SNP host (AMD Milan) at
wss://weikeng2.bitcoinpir.org.
What "Tier 3" means
No live server runs Tier 3 today; this is the shape a TEE host uses (pir2 until 2026-10-02, and Direct ORAM's next host).
Tier 3 is a deployment shape: the entire software stack — kernel, initramfs, command line, server binary — is packed into a single Unified Kernel Image (UKI) that the AMD SEV-SNP firmware measures at boot. AMD's Platform Security Processor signs a report binding:
- The launch MEASUREMENT (the 48-byte hash of OVMF + UKI bytes).
- Per-chip identity (VCEK certificate chain rooted at AMD's ARK).
- A REPORT_DATA field the server uses for session binding.
Compare this to Slice 2 (the recovery mode) — same hardware, but
boots a normal rootfs with sshd enabled. Useful for operator
recovery, but unsuitable for production because the boot path is not
measured.
The full verification flow
Neither live server has a TEE, so a wallet compares each server's binary with its pin and checks each server's operator-signed identity. The checks report; what to do with a mismatch is the wallet's choice:
import {
gateOperatorIdentity,
PIR1_PROVIDER, // pir1: endpoint, PIR1_PIN, operator key
PIR2_PROVIDER, // pir2: endpoint, PIR2_MACBOOK_PIN, operator key
} from 'bitcoin-pir-web';
import { pinAcceptsBinary } from 'bitcoin-pir-web/attest-pin';
const attest0 = await client.attest(0); // hint server
const attest1 = await client.attest(1); // query server
// --- Step 1: compare with the operator's published binaries. Both
// servers report `noSevHost`: the hash is self-reported, so it catches
// drift from the published build but no hardware vouches for it. ---
const pinOk = [
pinAcceptsBinary(PIR1_PROVIDER.serverPin, attest0.binarySha256Hex),
pinAcceptsBinary(PIR2_PROVIDER.serverPin, attest1.binarySha256Hex),
];
// --- Step 2: upgrade to the AEAD-sealed channel ---
await client.upgradeToSecureChannel(
attest0.serverStaticPub,
attest1.serverStaticPub,
);
// --- Step 3: check the operator-signed identity of each server.
// Without a TEE this is what ties the channel key to the operator. ---
const now = BigInt(Math.floor(Date.now() / 1000));
const identities = [];
for (const [i, p, att] of [[0, PIR1_PROVIDER, attest0], [1, PIR2_PROVIDER, attest1]] as const) {
const v = await client.announce(i);
identities.push(gateOperatorIdentity(v, p.operatorPubkey, att.serverStaticPub, now));
v.free();
}
// `pinOk` and `identities[i].state` ('verified', 'unverified', ...) are
// the verdicts.The TypeScript adapters run the same checks on connect and report each
outcome (attestation, operatorIdentity); they do not refuse to
query.
On a TEE host
A server inside an AMD SEV-SNP guest (pir2 until 2026-10-02; the Direct
ORAM host since 2026-10-03) adds hardware evidence before the channel
upgrade, where pin is that host's ServerAttestPin from attest-pin.ts:
import { AMD_MILAN_ARK_FINGERPRINT } from 'bitcoin-pir-web/attest-pin';
if (attest.sevStatus !== 'reportDataMatch') {
throw new Error(`SEV-SNP report did not bind: ${attest.sevStatus}`);
}
attest.verifyVcekChain(AMD_MILAN_ARK_FINGERPRINT);
// The SEV-SNP report is signed by a real AMD Milan chip whose ARK
// matches the operator's pin (use the ARK of the host's generation).
if (attest.launchMeasurementHex !== pin.measurementHex) {
throw new Error('Server is running a different MEASUREMENT than expected');
}What's actually being verified
verifyVcekChain
A one-shot validator that:
- Hashes the ARK PEM the server bundled and compares to your pinned fingerprint. (This is the crucial step — without a pinned root, a malicious server could substitute a forged self-signed "ARK" that doesn't actually belong to AMD.)
- Confirms ARK self-signs (RSA-PSS-SHA384).
- Confirms ARK signs the ASK.
- Confirms ASK signs the VCEK.
- Confirms the SEV-SNP report's ECDSA-P384-SHA384 signature verifies against the VCEK's pubkey.
On success: the report is cryptographically authentic and your client
has cryptographically established that the chip generating it is a
real AMD SEV-SNP processor of the pinned generation (Milan for the ORAM
host). The adapters also hold every report chained to the Milan ARK to
AMD_MILAN_SEV_SNP_FLOOR: a minimum TCB per component, the
ALIAS_CHECK_COMPLETE platform bit and mitigation-vector bit 1, so a
host on firmware without AMD's published Milan fixes is refused.
launchMeasurementHex
The 48-byte hash AMD's PSP signs into every SEV-SNP report. For Tier 3 it covers OVMF + the loaded UKI bytes — kernel, initramfs, cmdline. Any change to the server binary inside the initramfs flips this value.
A wallet that pins this value detects:
- A server upgrade the operator made without publishing a new pin.
- A boot of the recovery (Slice 2) image instead of the Tier 3 UKI.
- Any binary substitution by anyone with access to the hardware.
binarySha256Hex
The SHA-256 of the running unified_server binary, server-self-reported.
For Tier 3, this transitively follows from MEASUREMENT (the binary
lives inside the initramfs, which is part of the UKI, which is part
of MEASUREMENT). For Slice 2, the binary hash is server-self-reported
and the operator publishes it via a separate channel.
The binarySha256Hex is also pinnable independently — the only pin
for a host without SEV (both live servers today). While the operator
switches such a host to a new build, its pin also carries the running
build as transitionBinarySha256Hex; compare with
pinAcceptsBinary(pin, reported), which accepts either, rather than
with ===.
sevStatus
A string enum: noSevHost, reportDataMatch, reportDataMismatch,
malformedReport. Any value other than reportDataMatch means no
hardware vouches for the self-reported fields. noSevHost is expected
on both live servers; there the operator-signed identity has to carry
the binding instead.
gateOperatorIdentity
Checks a server's announce() bundle (REQ_ANNOUNCE) against the
pinned operator key: the operator's key certified a server identity
key for a server id, and that identity key signed a bundle naming the
channel key and the binary hash. It returns state: 'verified' only
when the certificate is signed by your pinned operator key and inside
its validity window, the bundle's channel key equals the attested one,
and the bundle is not future-dated. Compare serverId and
binarySha256Hex with the provider's pins yourself, as in the flow
above.
Operator pins
The reference operator publishes pins in
web/src/attest-pin.ts.
For wallets shipping with the reference deployment, bake those values
into your bundle at build time and resync whenever the operator
redeploys (the values rotate with every binary). The pins as of
2026-10-03:
| Pin | Server | Pins |
|---|---|---|
PIR1_PIN | pir1 (Hetzner, no SEV) | binary SHA-256 |
PIR2_MACBOOK_PIN | pir2 (MacBook, no TEE) | binary SHA-256 |
PIR2_TIER3_PIN | the Direct ORAM host (VPSBG, AMD Milan) | binary SHA-256 + SEV-SNP MEASUREMENT |
AMD_MILAN_ARK_FINGERPRINT | the Direct ORAM host | AMD's Milan root key; its reports must also meet AMD_MILAN_SEV_SNP_FLOOR |
AMD_TURIN_ARK_FINGERPRINT | Turin SEV-SNP hosts | AMD's Turin root key |
PIR1_PROVIDER and PIR2_PROVIDER (production-providers.ts) pair
each binary pin with the endpoint, the expected server id and the
operator key the identity check needs. ORAM_PROVIDER does the same for
the Direct ORAM host (server id pir2-oram-v1) and adds its ARK pin
(Milan).
A wallet baking these into its bundle will refuse to connect after
the operator publishes a new binary. Either resync from
vendor/bitcoinpir-web/attest-pin.ts on every release, or fetch the
current pins from a signed manifest you control. The playground
itself reads from the vendored file, not from this doc.
The two servers run different builds (pir1 on Linux x86-64, pir2 on
macOS arm64), so PIR1_PIN and PIR2_MACBOOK_PIN differ. pir2 runs
--serve-queries only (no hint pool, no OnionPIR); pir1 runs the
hint role.
What happens after the channel is upgraded
upgradeToSecureChannel wraps both WebSocket connections in an AEAD
frame layer (ChaCha20-Poly1305). After this:
- Every PIR request and response is sealed end-to-end with a key derived from the X25519 ECDH between the client's ephemeral key and the server's static key.
- Cloudflared (the operator's TLS terminator), an ISP-level observer, or any other middlebox sees only ciphertext + framing metadata.
- A future re-key requires a new
attest()round trip.
This is defense in depth on top of TLS — TLS already encrypts in transit, but its certificate identity comes from a CA, not from hardware attestation. The AEAD layer binds the session to the server's channel key: on a TEE host the hardware report vouches for that key, and on the live servers (no TEE) the operator-signed identity does.
Skipping attestation
For development against the live server, you can skip attestation — the wire still uses WSS, and the SDK still enforces the four privacy invariants. What you lose is the binding to a specific known binary. Use this only for local prototyping; production wallets should pin.
Rotating pins
When the operator deploys a new binary:
- The operator runs
bpir-admin attest <endpoint>against the new deployment to capture the newbinary_sha256(and, on a TEE host, the new MEASUREMENT). - The pin file is updated in the reference repo (this is
web/src/attest-pin.ts). - Wallets ship a new bundle.
Wallets that don't update will refuse the new server — which is the correct behaviour from a security perspective. The operator must either coordinate a rolling rollout with bundled wallets, or maintain multiple acceptable pins during a transition (the SDK doesn't provide multi-pin acceptance out of the box; the wallet wraps it).
Where to go next
- The five invariants — what the wire shape doesn't leak.
- Operations / endpoints — the pir1/pir2 split and the WebSocket-only contract.
- Quickstart — the minimal happy-path integration (attestation flow at the end).