feat(relay): rendezvous-relay service — 7 packages + plans (contracts/transport/agent/control-plane/e2e/auth/web)
Multi-tenant reverse-tunnel service ("ngrok for Claude Code" with E2E): a
host-agent dials OUT to an operator-run relay; external devices reach the host
THROUGH the relay, routed by per-tenant subdomain, forwarding ciphertext only
(the relay never sees plaintext). Lets a customer reach their own self-hosted
web-terminal from anywhere with zero networking setup.
Packages — all tsc-strict + vitest green (656 tests), cross-package integration verified:
- relay-contracts: frozen shared contracts (mux frame codec, data model,
capability token, E2E envelope, pairing) — the src/types.ts analog
- term-relay: native WS mux + stateless data plane (subdomain routing, ciphertext forward)
- agent: host-agent (pairing, per-host Ed25519 + mTLS dial-out, forwards to 127.0.0.1:3000)
- control-plane: accounts/hosts registry, pairing-code flow, routing table, provisioning
- relay-e2e: browser<->agent E2E (X25519 ECDH through relay, AEAD, anti-replay, recoverable replay key)
- relay-auth: Passkey/WebAuthn, capability tokens, per-host certs, deny-by-default tenant isolation
- relay-web: browser login + Web Crypto E2E + client-side preview rendering
Security invariants INV1-15 enforced; cross-tenant isolation CI tripwire live
(.github/workflows/relay-tripwire.yml). Design + implementation-level plans in
docs/PLAN_RELAY_*.md and docs/EXPLORE_RELAY_SERVICE.md.
NOTE: generated autonomously per the reviewed plans. The security-critical
packages (relay-e2e, relay-auth) REQUIRE expert security audit before any real
deployment — passing tests prove self-consistency, not resistance to attackers.
Base app (src/, public/) unchanged; concurrent desktop work left uncommitted.
This commit is contained in:
77
relay-e2e/src/aead.ts
Normal file
77
relay-e2e/src/aead.ts
Normal file
@@ -0,0 +1,77 @@
|
||||
/**
|
||||
* T2 — synchronous AEAD primitives over @noble/ciphers (AES-256-GCM + XChaCha20-Poly1305).
|
||||
*
|
||||
* SYNCHRONOUS so it satisfies the frozen §4.4 `sealFrame`/`openFrame` synchronous signatures.
|
||||
* @noble/ciphers is audited, isomorphic, and provides XChaCha (which WebCrypto lacks). Noble's
|
||||
* one-shot AEAD returns `ciphertext‖tag`; §4.4 `E2EEnvelope` keeps them split, so we slice the
|
||||
* fixed 16-byte tag off the tail on seal and re-join on open.
|
||||
*/
|
||||
import { gcm } from '@noble/ciphers/aes'
|
||||
import { xchacha20poly1305 } from '@noble/ciphers/chacha'
|
||||
import type { AeadAlg, AeadKey } from 'relay-contracts'
|
||||
import { NONCE_BYTES } from 'relay-contracts'
|
||||
import { AeadOpenError, E2EError } from './errors.js'
|
||||
import { unwrapAeadKey, wrapAeadKey } from './aead-key.js'
|
||||
|
||||
const TAG_BYTES = 16 as const
|
||||
|
||||
/** Nonce width for an AEAD alg (12 GCM · 24 XChaCha, §4.4). */
|
||||
export function nonceLength(alg: AeadAlg): 12 | 24 {
|
||||
const width = NONCE_BYTES[alg]
|
||||
return width as 12 | 24
|
||||
}
|
||||
|
||||
/** Fixed AEAD tag length (16 bytes for both algs). */
|
||||
export function tagLength(_alg: AeadAlg): 16 {
|
||||
return TAG_BYTES
|
||||
}
|
||||
|
||||
/** Construct the frozen opaque `AeadKey` from 32 raw bytes (P4-local constructor, INDEX §2.1). */
|
||||
export function importAeadKey(raw: Uint8Array, alg: AeadAlg, aadLabel = ''): AeadKey {
|
||||
return wrapAeadKey(raw, alg, aadLabel)
|
||||
}
|
||||
|
||||
function cipherFor(alg: AeadAlg, raw: Uint8Array, nonce: Uint8Array, aad: Uint8Array) {
|
||||
if (nonce.length !== nonceLength(alg)) {
|
||||
throw new E2EError(
|
||||
'E2E_NONCE_LENGTH',
|
||||
`nonce length ${nonce.length} != required ${nonceLength(alg)} for ${alg}`,
|
||||
)
|
||||
}
|
||||
return alg === 'aes-256-gcm' ? gcm(raw, nonce, aad) : xchacha20poly1305(raw, nonce, aad)
|
||||
}
|
||||
|
||||
/** Seal plaintext; returns split ciphertext + 16-byte tag (§4.4 E2EEnvelope). */
|
||||
export function aeadSeal(
|
||||
key: AeadKey,
|
||||
nonce: Uint8Array,
|
||||
plaintext: Uint8Array,
|
||||
aad: Uint8Array,
|
||||
): { ciphertext: Uint8Array; tag: Uint8Array } {
|
||||
const { raw, alg } = unwrapAeadKey(key)
|
||||
const sealed = cipherFor(alg, raw, nonce, aad).encrypt(plaintext)
|
||||
const cut = sealed.length - TAG_BYTES
|
||||
return { ciphertext: sealed.slice(0, cut), tag: sealed.slice(cut) }
|
||||
}
|
||||
|
||||
/** Open ciphertext+tag; throws {@link AeadOpenError} on any tag/aad/key/nonce mismatch. */
|
||||
export function aeadOpen(
|
||||
key: AeadKey,
|
||||
nonce: Uint8Array,
|
||||
ciphertext: Uint8Array,
|
||||
tag: Uint8Array,
|
||||
aad: Uint8Array,
|
||||
): Uint8Array {
|
||||
if (tag.length !== TAG_BYTES) {
|
||||
throw new AeadOpenError(`tag length ${tag.length} != ${TAG_BYTES}`)
|
||||
}
|
||||
const { raw, alg } = unwrapAeadKey(key)
|
||||
const joined = new Uint8Array(ciphertext.length + tag.length)
|
||||
joined.set(ciphertext, 0)
|
||||
joined.set(tag, ciphertext.length)
|
||||
try {
|
||||
return cipherFor(alg, raw, nonce, aad).decrypt(joined)
|
||||
} catch {
|
||||
throw new AeadOpenError()
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user