@acpantenna/relay-protocol 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,57 @@
 {
-  "name": "@acpantenna/relay-protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@acpantenna/relay-protocol",
+	"version": "0.2.0",
+	"description": "acpantenna's relay protocol: Noise NKpsk0 to pair and KK to reconnect, frames, the pairing link and the SAS words. Runs in browsers and Bun.",
+	"license": "MIT",
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist",
+		"src",
+		"!src/**/*.test.ts",
+		"test-vectors",
+		"README.md",
+		"LICENSE"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fboldo/acpantenna.git",
+		"directory": "packages/relay-protocol"
+	},
+	"homepage": "https://github.com/fboldo/acpantenna/blob/main/docs/relay-protocol.md",
+	"bugs": "https://github.com/fboldo/acpantenna/issues",
+	"keywords": [
+		"acp",
+		"agent-client-protocol",
+		"noise",
+		"noise-protocol",
+		"end-to-end-encryption",
+		"relay",
+		"websocket"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "rm -rf dist && tsc -p tsconfig.build.json && cp ../../LICENSE LICENSE",
+		"prepack": "bun run build",
+		"check": "bun run typecheck",
+		"test": "bun test src",
+		"typecheck": "tsc -p tsconfig.json --noEmit"
+	},
+	"dependencies": {
+		"@noble/ciphers": "2.4.0",
+		"@noble/curves": "2.4.0",
+		"@noble/hashes": "2.4.0"
+	}
+}

package/src/bip39-english.ts

@@ -0,0 +1,30 @@
+/**
+ * The BIP-39 English wordlist: 2,048 words, used for the short authentication
+ * string. From https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt
+ * (SHA-256 2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda).
+ *
+ * BIP-39 is by Marek Palatinus, Pavol Rusnak, Aaron Voisine and Sean Bowe,
+ * and is licensed under the MIT License:
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+export const BIP39_ENGLISH: readonly string[] =
+	"abandon ability able about above absent absorb abstract absurd abuse access accident account accuse achieve acid acoustic acquire across act action actor actress actual adapt add addict address adjust admit adult advance advice aerobic affair afford afraid again age agent agree ahead aim air airport aisle alarm album alcohol alert alien all alley allow almost alone alpha already also alter always amateur amazing among amount amused analyst anchor ancient anger angle angry animal ankle announce annual another answer antenna antique anxiety any apart apology appear apple approve april arch arctic area arena argue arm armed armor army around arrange arrest arrive arrow art artefact artist artwork ask aspect assault asset assist assume asthma athlete atom attack attend attitude attract auction audit august aunt author auto autumn average avocado avoid awake aware away awesome awful awkward axis baby bachelor bacon badge bag balance balcony ball bamboo banana banner bar barely bargain barrel base basic basket battle beach bean beauty because become beef before begin behave behind believe below belt bench benefit best betray better between beyond bicycle bid bike bind biology bird birth bitter black blade blame blanket blast bleak bless blind blood blossom blouse blue blur blush board boat body boil bomb bone bonus book boost border boring borrow boss bottom bounce box boy bracket brain brand brass brave bread breeze brick bridge brief bright bring brisk broccoli broken bronze broom brother brown brush bubble buddy budget buffalo build bulb bulk bullet bundle bunker burden burger burst bus business busy butter buyer buzz cabbage cabin cable cactus cage cake call calm camera camp can canal cancel candy cannon canoe canvas canyon capable capital captain car carbon card cargo carpet carry cart case cash casino castle casual cat catalog catch category cattle caught cause caution cave ceiling celery cement census century cereal certain chair chalk champion change chaos chapter charge chase chat cheap check cheese chef cherry chest chicken chief child chimney choice choose chronic chuckle chunk churn cigar cinnamon circle citizen city civil claim clap clarify claw clay clean clerk clever click client cliff climb clinic clip clock clog close cloth cloud clown club clump cluster clutch coach coast coconut code coffee coil coin collect color column combine come comfort comic common company concert conduct confirm congress connect consider control convince cook cool copper copy coral core corn correct cost cotton couch country couple course cousin cover coyote crack cradle craft cram crane crash crater crawl crazy cream credit creek crew cricket crime crisp critic crop cross crouch crowd crucial cruel cruise crumble crunch crush cry crystal cube culture cup cupboard curious current curtain curve cushion custom cute cycle dad damage damp dance danger daring dash daughter dawn day deal debate debris decade december decide decline decorate decrease deer defense define defy degree delay deliver demand demise denial dentist deny depart depend deposit depth deputy derive describe desert design desk despair destroy detail detect develop device devote diagram dial diamond diary dice diesel diet differ digital dignity dilemma dinner dinosaur direct dirt disagree discover disease dish dismiss disorder display distance divert divide divorce dizzy doctor document dog doll dolphin domain donate donkey donor door dose double dove draft dragon drama drastic draw dream dress drift drill drink drip drive drop drum dry duck dumb dune during dust dutch duty dwarf dynamic eager eagle early earn earth easily east easy echo ecology economy edge edit educate effort egg eight either elbow elder electric elegant element elephant elevator elite else embark embody embrace emerge emotion employ empower empty enable enact end endless endorse enemy energy enforce engage engine enhance enjoy enlist enough enrich enroll ensure enter entire entry envelope episode equal equip era erase erode erosion error erupt escape essay essence estate eternal ethics evidence evil evoke evolve exact example excess exchange excite exclude excuse execute exercise exhaust exhibit exile exist exit exotic expand expect expire explain expose express extend extra eye eyebrow fabric face faculty fade faint faith fall false fame family famous fan fancy fantasy farm fashion fat fatal father fatigue fault favorite feature february federal fee feed feel female fence festival fetch fever few fiber fiction field figure file film filter final find fine finger finish fire firm first fiscal fish fit fitness fix flag flame flash flat flavor flee flight flip float flock floor flower fluid flush fly foam focus fog foil fold follow food foot force forest forget fork fortune forum forward fossil foster found fox fragile frame frequent fresh friend fringe frog front frost frown frozen fruit fuel fun funny furnace fury future gadget gain galaxy gallery game gap garage garbage garden garlic garment gas gasp gate gather gauge gaze general genius genre gentle genuine gesture ghost giant gift giggle ginger giraffe girl give glad glance glare glass glide glimpse globe gloom glory glove glow glue goat goddess gold good goose gorilla gospel gossip govern gown grab grace grain grant grape grass gravity great green grid grief grit grocery group grow grunt guard guess guide guilt guitar gun gym habit hair half hammer hamster hand happy harbor hard harsh harvest hat have hawk hazard head health heart heavy hedgehog height hello helmet help hen hero hidden high hill hint hip hire history hobby hockey hold hole holiday hollow home honey hood hope horn horror horse hospital host hotel hour hover hub huge human humble humor hundred hungry hunt hurdle hurry hurt husband hybrid ice icon idea identify idle ignore ill illegal illness image imitate immense immune impact impose improve impulse inch include income increase index indicate indoor industry infant inflict inform inhale inherit initial inject injury inmate inner innocent input inquiry insane insect inside inspire install intact interest into invest invite involve iron island isolate issue item ivory jacket jaguar jar jazz jealous jeans jelly jewel job join joke journey joy judge juice jump jungle junior junk just kangaroo keen keep ketchup key kick kid kidney kind kingdom kiss kit kitchen kite kitten kiwi knee knife knock know lab label labor ladder lady lake lamp language laptop large later latin laugh laundry lava law lawn lawsuit layer lazy leader leaf learn leave lecture left leg legal legend leisure lemon lend length lens leopard lesson letter level liar liberty library license life lift light like limb limit link lion liquid list little live lizard load loan lobster local lock logic lonely long loop lottery loud lounge love loyal lucky luggage lumber lunar lunch luxury lyrics machine mad magic magnet maid mail main major make mammal man manage mandate mango mansion manual maple marble march margin marine market marriage mask mass master match material math matrix matter maximum maze meadow mean measure meat mechanic medal media melody melt member memory mention menu mercy merge merit merry mesh message metal method middle midnight milk million mimic mind minimum minor minute miracle mirror misery miss mistake mix mixed mixture mobile model modify mom moment monitor monkey monster month moon moral more morning mosquito mother motion motor mountain mouse move movie much muffin mule multiply muscle museum mushroom music must mutual myself mystery myth naive name napkin narrow nasty nation nature near neck need negative neglect neither nephew nerve nest net network neutral never news next nice night noble noise nominee noodle normal north nose notable note nothing notice novel now nuclear number nurse nut oak obey object oblige obscure observe obtain obvious occur ocean october odor off offer office often oil okay old olive olympic omit once one onion online only open opera opinion oppose option orange orbit orchard order ordinary organ orient original orphan ostrich other outdoor outer output outside oval oven over own owner oxygen oyster ozone pact paddle page pair palace palm panda panel panic panther paper parade parent park parrot party pass patch path patient patrol pattern pause pave payment peace peanut pear peasant pelican pen penalty pencil people pepper perfect permit person pet phone photo phrase physical piano picnic picture piece pig pigeon pill pilot pink pioneer pipe pistol pitch pizza place planet plastic plate play please pledge pluck plug plunge poem poet point polar pole police pond pony pool popular portion position possible post potato pottery poverty powder power practice praise predict prefer prepare present pretty prevent price pride primary print priority prison private prize problem process produce profit program project promote proof property prosper protect proud provide public pudding pull pulp pulse pumpkin punch pupil puppy purchase purity purpose purse push put puzzle pyramid quality quantum quarter question quick quit quiz quote rabbit raccoon race rack radar radio rail rain raise rally ramp ranch random range rapid rare rate rather raven raw razor ready real reason rebel rebuild recall receive recipe record recycle reduce reflect reform refuse region regret regular reject relax release relief rely remain remember remind remove render renew rent reopen repair repeat replace report require rescue resemble resist resource response result retire retreat return reunion reveal review reward rhythm rib ribbon rice rich ride ridge rifle right rigid ring riot ripple risk ritual rival river road roast robot robust rocket romance roof rookie room rose rotate rough round route royal rubber rude rug rule run runway rural sad saddle sadness safe sail salad salmon salon salt salute same sample sand satisfy satoshi sauce sausage save say scale scan scare scatter scene scheme school science scissors scorpion scout scrap screen script scrub sea search season seat second secret section security seed seek segment select sell seminar senior sense sentence series service session settle setup seven shadow shaft shallow share shed shell sheriff shield shift shine ship shiver shock shoe shoot shop short shoulder shove shrimp shrug shuffle shy sibling sick side siege sight sign silent silk silly silver similar simple since sing siren sister situate six size skate sketch ski skill skin skirt skull slab slam sleep slender slice slide slight slim slogan slot slow slush small smart smile smoke smooth snack snake snap sniff snow soap soccer social sock soda soft solar soldier solid solution solve someone song soon sorry sort soul sound soup source south space spare spatial spawn speak special speed spell spend sphere spice spider spike spin spirit split spoil sponsor spoon sport spot spray spread spring spy square squeeze squirrel stable stadium staff stage stairs stamp stand start state stay steak steel stem step stereo stick still sting stock stomach stone stool story stove strategy street strike strong struggle student stuff stumble style subject submit subway success such sudden suffer sugar suggest suit summer sun sunny sunset super supply supreme sure surface surge surprise surround survey suspect sustain swallow swamp swap swarm swear sweet swift swim swing switch sword symbol symptom syrup system table tackle tag tail talent talk tank tape target task taste tattoo taxi teach team tell ten tenant tennis tent term test text thank that theme then theory there they thing this thought three thrive throw thumb thunder ticket tide tiger tilt timber time tiny tip tired tissue title toast tobacco today toddler toe together toilet token tomato tomorrow tone tongue tonight tool tooth top topic topple torch tornado tortoise toss total tourist toward tower town toy track trade traffic tragic train transfer trap trash travel tray treat tree trend trial tribe trick trigger trim trip trophy trouble truck true truly trumpet trust truth try tube tuition tumble tuna tunnel turkey turn turtle twelve twenty twice twin twist two type typical ugly umbrella unable unaware uncle uncover under undo unfair unfold unhappy uniform unique unit universe unknown unlock until unusual unveil update upgrade uphold upon upper upset urban urge usage use used useful useless usual utility vacant vacuum vague valid valley valve van vanish vapor various vast vault vehicle velvet vendor venture venue verb verify version very vessel veteran viable vibrant vicious victory video view village vintage violin virtual virus visa visit visual vital vivid vocal voice void volcano volume vote voyage wage wagon wait walk wall walnut want warfare warm warrior wash wasp waste water wave way wealth weapon wear weasel weather web wedding weekend weird welcome west wet whale what wheat wheel when where whip whisper wide width wife wild will win window wine wing wink winner winter wire wisdom wise wish witness wolf woman wonder wood wool word work world worry worth wrap wreck wrestle wrist write wrong yard year yellow you young youth zebra zero zone zoo".split(
+		" ",
+	);

package/src/bytes.ts

@@ -0,0 +1,125 @@
+/**
+ * Byte helpers on plain `Uint8Array`s, so the package runs in a browser as
+ * well as in Bun.
+ */
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+export function concatBytes(...parts: Uint8Array[]): Uint8Array {
+	let length = 0;
+	for (const part of parts) {
+		length += part.length;
+	}
+	const out = new Uint8Array(length);
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+
+/** Compares two byte strings without stopping at the first difference. */
+export function equalBytes(a: Uint8Array, b: Uint8Array): boolean {
+	if (a.length !== b.length) {
+		return false;
+	}
+	let diff = 0;
+	for (let index = 0; index < a.length; index++) {
+		diff |= (a[index] ?? 0) ^ (b[index] ?? 0);
+	}
+	return diff === 0;
+}
+
+export function utf8Encode(text: string): Uint8Array {
+	return encoder.encode(text);
+}
+
+/** Decodes UTF-8, throwing on invalid sequences rather than replacing them. */
+export function utf8Decode(bytes: Uint8Array): string {
+	return decoder.decode(bytes);
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+	if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) {
+		throw new Error("Invalid hex string");
+	}
+	const out = new Uint8Array(hex.length / 2);
+	for (let index = 0; index < out.length; index++) {
+		out[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+	}
+	return out;
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+	let hex = "";
+	for (const byte of bytes) {
+		hex += byte.toString(16).padStart(2, "0");
+	}
+	return hex;
+}
+
+const BASE64URL =
+	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/** Base64url without padding (RFC 4648 §5). */
+export function base64urlEncode(bytes: Uint8Array): string {
+	let out = "";
+	let index = 0;
+	for (; index + 2 < bytes.length; index += 3) {
+		const n =
+			((bytes[index] ?? 0) << 16) |
+			((bytes[index + 1] ?? 0) << 8) |
+			(bytes[index + 2] ?? 0);
+		out +=
+			BASE64URL.charAt((n >> 18) & 63) +
+			BASE64URL.charAt((n >> 12) & 63) +
+			BASE64URL.charAt((n >> 6) & 63) +
+			BASE64URL.charAt(n & 63);
+	}
+	const rest = bytes.length - index;
+	if (rest === 1) {
+		const n = (bytes[index] ?? 0) << 16;
+		out += BASE64URL.charAt((n >> 18) & 63) + BASE64URL.charAt((n >> 12) & 63);
+	} else if (rest === 2) {
+		const n = ((bytes[index] ?? 0) << 16) | ((bytes[index + 1] ?? 0) << 8);
+		out +=
+			BASE64URL.charAt((n >> 18) & 63) +
+			BASE64URL.charAt((n >> 12) & 63) +
+			BASE64URL.charAt((n >> 6) & 63);
+	}
+	return out;
+}
+
+/**
+ * Decodes base64url without padding. Only the canonical encoding is accepted
+ * (unused trailing bits must be zero), so one value has one spelling.
+ */
+export function base64urlDecode(text: string): Uint8Array {
+	if (!/^[A-Za-z0-9_-]*$/.test(text) || text.length % 4 === 1) {
+		throw new Error("Invalid base64url");
+	}
+	const out = new Uint8Array(Math.floor((text.length * 3) / 4));
+	let buffer = 0;
+	let bits = 0;
+	let offset = 0;
+	for (const char of text) {
+		buffer = (buffer << 6) | BASE64URL.indexOf(char);
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out[offset++] = (buffer >> bits) & 0xff;
+		}
+	}
+	if ((buffer & ((1 << bits) - 1)) !== 0) {
+		throw new Error("Invalid base64url");
+	}
+	return out;
+}
+
+export function randomBytes(length: number): Uint8Array {
+	const out = new Uint8Array(length);
+	crypto.getRandomValues(out);
+	return out;
+}

package/src/frames.ts

@@ -0,0 +1,278 @@
+/**
+ * The plaintext of each transport message: a 14-byte header, the payload,
+ * and zero padding up to a size bucket.
+ *
+ *     offset size field
+ *     0      1    type     1 ACP, 2 CLOSE, 3 PING, 4 PONG, 5 CONFIRMED, 6 REMEMBER
+ *     1      4    stream   u32 BE
+ *     5      4    seq      u32 BE
+ *     9      1    flags    bit0 FINAL
+ *     10     4    length   u32 BE
+ *     14     n    payload
+ *     14+n   pad  zero bytes up to the bucket
+ *
+ * One ACP message is one stream, cut into chunks if it does not fit in one
+ * frame. Control frames (CLOSE, PING, PONG, CONFIRMED, REMEMBER) are single frames
+ * with stream 0, seq 0 and FINAL set; ACP streams count from 1.
+ */
+
+import { concatBytes } from "./bytes.ts";
+import { MAX_MESSAGE_LENGTH, TAGLEN } from "./noise.ts";
+
+export const FrameType = {
+	ACP: 1,
+	CLOSE: 2,
+	PING: 3,
+	PONG: 4,
+	/** Agent side to browser: the user has confirmed the SAS words, or a reconnect is confirmed. */
+	CONFIRMED: 5,
+	/** Browser to agent side, once, right after pairing: its static key for reconnecting. */
+	REMEMBER: 6,
+} as const;
+export type FrameType = (typeof FrameType)[keyof typeof FrameType];
+
+export const FLAG_FINAL = 0x01;
+export const HEADER_LENGTH = 14;
+/** The largest plaintext: one Noise message less its tag. */
+export const MAX_PLAINTEXT_LENGTH = MAX_MESSAGE_LENGTH - TAGLEN;
+/** The most payload one frame carries. */
+export const MAX_CHUNK_PAYLOAD = MAX_PLAINTEXT_LENGTH - HEADER_LENGTH;
+export const MIN_BUCKET = 256;
+/** The largest ACP message a reassembler accepts by default: 32 MiB. */
+export const DEFAULT_MAX_MESSAGE_BYTES = 32 * 1024 * 1024;
+/** A 32-byte key in base64url without padding. */
+export const REMEMBER_PAYLOAD_LENGTH = 43;
+
+export interface Frame {
+	type: FrameType;
+	stream: number;
+	seq: number;
+	final: boolean;
+	payload: Uint8Array;
+}
+
+/** A broken rule of the framing. The session must end: there is no resync. */
+export class FrameError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "FrameError";
+	}
+}
+
+/**
+ * The padded size of a plaintext of `length` bytes: 256, else the next power
+ * of two, capped at {@link MAX_PLAINTEXT_LENGTH}.
+ */
+export function bucketLength(length: number): number {
+	if (length > MAX_PLAINTEXT_LENGTH) {
+		throw new FrameError("Frame too long");
+	}
+	let bucket = MIN_BUCKET;
+	while (bucket < length) {
+		bucket *= 2;
+	}
+	return Math.min(bucket, MAX_PLAINTEXT_LENGTH);
+}
+
+const KNOWN_TYPES = new Set<number>(Object.values(FrameType));
+
+/** Encodes a frame as a padded plaintext. */
+export function encodeFrame(frame: Frame): Uint8Array {
+	checkFrameShape(frame);
+	const out = new Uint8Array(
+		bucketLength(HEADER_LENGTH + frame.payload.length),
+	);
+	const view = new DataView(out.buffer);
+	view.setUint8(0, frame.type);
+	view.setUint32(1, frame.stream);
+	view.setUint32(5, frame.seq);
+	view.setUint8(9, frame.final ? FLAG_FINAL : 0);
+	view.setUint32(10, frame.payload.length);
+	out.set(frame.payload, HEADER_LENGTH);
+	return out;
+}
+
+/**
+ * Decodes a padded plaintext. Anything off — an unknown type or flag, a
+ * length past the end, a size that is not the right bucket, non-zero
+ * padding — throws a {@link FrameError}.
+ */
+export function decodeFrame(plaintext: Uint8Array): Frame {
+	if (plaintext.length < HEADER_LENGTH) {
+		throw new FrameError("Frame shorter than its header");
+	}
+	const view = new DataView(
+		plaintext.buffer,
+		plaintext.byteOffset,
+		plaintext.byteLength,
+	);
+	const type = view.getUint8(0);
+	const stream = view.getUint32(1);
+	const seq = view.getUint32(5);
+	const flags = view.getUint8(9);
+	const length = view.getUint32(10);
+	if (!KNOWN_TYPES.has(type)) {
+		throw new FrameError(`Unknown frame type ${type}`);
+	}
+	if ((flags & ~FLAG_FINAL) !== 0) {
+		throw new FrameError("Unknown frame flags");
+	}
+	if (HEADER_LENGTH + length > plaintext.length) {
+		throw new FrameError("Frame length past the end");
+	}
+	if (plaintext.length !== bucketLength(HEADER_LENGTH + length)) {
+		throw new FrameError("Frame not padded to its bucket");
+	}
+	for (let index = HEADER_LENGTH + length; index < plaintext.length; index++) {
+		if (plaintext[index] !== 0) {
+			throw new FrameError("Non-zero padding");
+		}
+	}
+	const frame: Frame = {
+		type: type as FrameType,
+		stream,
+		seq,
+		final: (flags & FLAG_FINAL) !== 0,
+		payload: plaintext.slice(HEADER_LENGTH, HEADER_LENGTH + length),
+	};
+	checkFrameShape(frame);
+	return frame;
+}
+
+function checkFrameShape(frame: Frame): void {
+	if (!KNOWN_TYPES.has(frame.type)) {
+		throw new FrameError(`Unknown frame type ${frame.type}`);
+	}
+	if (frame.payload.length > MAX_CHUNK_PAYLOAD) {
+		throw new FrameError("Frame payload too long");
+	}
+	if (!isUint32(frame.stream) || !isUint32(frame.seq)) {
+		throw new FrameError("Stream and seq are 32-bit unsigned integers");
+	}
+	if (frame.type === FrameType.ACP) {
+		if (frame.stream === 0) {
+			throw new FrameError("ACP streams count from 1");
+		}
+		return;
+	}
+	if (frame.stream !== 0 || frame.seq !== 0 || !frame.final) {
+		throw new FrameError("A control frame has stream 0, seq 0 and FINAL set");
+	}
+	if (
+		frame.type === FrameType.CONFIRMED &&
+		frame.payload.length !== 0 &&
+		frame.payload.length !== 4
+	) {
+		throw new FrameError("CONFIRMED is empty, or a u32 when resuming");
+	}
+	if (
+		frame.type === FrameType.REMEMBER &&
+		frame.payload.length !== REMEMBER_PAYLOAD_LENGTH
+	) {
+		throw new FrameError("REMEMBER carries a 32-byte key in base64url");
+	}
+}
+
+function isUint32(value: number): boolean {
+	return Number.isInteger(value) && value >= 0 && value <= 0xffffffff;
+}
+
+/** A control frame: stream 0, seq 0, FINAL. */
+export function controlFrame(
+	type: Exclude<FrameType, typeof FrameType.ACP>,
+	payload: Uint8Array = new Uint8Array(0),
+): Frame {
+	return { type, stream: 0, seq: 0, final: true, payload };
+}
+
+/**
+ * Cuts one ACP message into the frames of stream `stream`. An empty message
+ * is one empty FINAL frame.
+ */
+export function chunkMessage(
+	stream: number,
+	message: Uint8Array,
+	maxChunk = MAX_CHUNK_PAYLOAD,
+): Frame[] {
+	if (maxChunk < 1 || maxChunk > MAX_CHUNK_PAYLOAD) {
+		throw new FrameError("Chunk size out of range");
+	}
+	const frames: Frame[] = [];
+	let offset = 0;
+	do {
+		const end = Math.min(offset + maxChunk, message.length);
+		frames.push({
+			type: FrameType.ACP,
+			stream,
+			seq: frames.length,
+			final: end === message.length,
+			payload: message.slice(offset, end),
+		});
+		offset = end;
+	} while (offset < message.length);
+	return frames;
+}
+
+/**
+ * Puts the ACP streams of one direction back together, enforcing the rules:
+ * stream ids go up by one from 1, seq goes up by one from 0, nothing is
+ * interleaved, and a message stays under a size cap. Any breach throws a
+ * {@link FrameError}.
+ */
+export class Reassembler {
+	private current:
+		| { stream: number; nextSeq: number; chunks: Uint8Array[]; size: number }
+		| undefined;
+
+	/** `lastStream` is the stream received before, when a connection resumes. */
+	constructor(
+		private readonly maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES,
+		private lastStream = 0,
+	) {}
+
+	/** Whether a stream has started and not yet ended. */
+	get inStream(): boolean {
+		return this.current !== undefined;
+	}
+
+	/** Takes one ACP frame; returns the whole message once its FINAL chunk arrives. */
+	push(frame: Frame): Uint8Array | undefined {
+		if (frame.type !== FrameType.ACP) {
+			throw new FrameError("Only ACP frames are reassembled");
+		}
+		if (!this.current) {
+			if (frame.stream !== this.lastStream + 1) {
+				throw new FrameError(
+					`Expected stream ${this.lastStream + 1}, got ${frame.stream}`,
+				);
+			}
+			this.current = { stream: frame.stream, nextSeq: 0, chunks: [], size: 0 };
+		}
+		const current = this.current;
+		if (frame.stream !== current.stream) {
+			throw new FrameError("Streams interleaved");
+		}
+		if (frame.seq !== current.nextSeq) {
+			throw new FrameError(`Expected seq ${current.nextSeq}, got ${frame.seq}`);
+		}
+		current.size += frame.payload.length;
+		if (current.size > this.maxMessageBytes) {
+			throw new FrameError("Message too large");
+		}
+		current.chunks.push(frame.payload);
+		current.nextSeq++;
+		if (!frame.final) {
+			return undefined;
+		}
+		this.lastStream = current.stream;
+		this.current = undefined;
+		return concatBytes(...current.chunks);
+	}
+
+	/** Called on CLOSE: a stream still open then means the relay truncated it. */
+	end(): void {
+		if (this.current) {
+			throw new FrameError("Stream left without FINAL");
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * The wire protocol between acpantenna and a web client over a relay:
+ * Noise NKpsk0, the frame codec, the pairing link, the SAS words, and a
+ * session object both ends use. Plain `Uint8Array`s and Web APIs only, so it
+ * runs in a browser as well as in Bun. The spec is `docs/relay-protocol.md`.
+ */
+
+export * from "./bytes.ts";
+export * from "./frames.ts";
+export * from "./link.ts";
+export * from "./noise.ts";
+export * from "./relay.ts";
+export * from "./sas.ts";
+export * from "./session.ts";

package/src/link.ts

@@ -0,0 +1,160 @@
+/**
+ * The pairing link: `<web origin>/#v1.<room>.<s_pub>.<psk>.<expiry>`.
+ *
+ * `room` (16 bytes), `s_pub` (32) and `psk` (32) are base64url without
+ * padding; `expiry` is unix seconds in decimal. Everything secret is in the
+ * fragment, which browsers never send to a server.
+ */
+
+import {
+	base64urlDecode,
+	base64urlEncode,
+	concatBytes,
+	utf8Encode,
+} from "./bytes.ts";
+
+export const LINK_VERSION = "v1";
+export const ROOM_LENGTH = 16;
+export const KEY_LENGTH = 32;
+/** How long a link is valid by default: 10 minutes. */
+export const DEFAULT_LINK_TTL_SECONDS = 10 * 60;
+/** The label at the start of the prologue. */
+export const PROLOGUE_LABEL = "acpantenna-relay/1";
+
+export interface PairingLink {
+	/** The web client's origin, e.g. `https://app.example`. */
+	webOrigin: string;
+	room: Uint8Array;
+	/** The agent side's static X25519 public key. */
+	staticPublicKey: Uint8Array;
+	psk: Uint8Array;
+	/** Unix seconds. */
+	expiry: number;
+}
+
+export class LinkError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "LinkError";
+	}
+}
+
+/**
+ * Checks that `origin` is an origin and nothing more — a scheme, a host and
+ * maybe a port — and returns it in the form `URL.origin` gives.
+ */
+export function normalizeWebOrigin(origin: string): string {
+	let url: URL;
+	try {
+		url = new URL(origin);
+	} catch {
+		throw new LinkError(`Not a URL: ${origin}`);
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") {
+		throw new LinkError("The web origin is http or https");
+	}
+	if (
+		url.origin !== origin.replace(/\/$/, "") ||
+		url.username ||
+		url.password
+	) {
+		throw new LinkError(
+			`The web origin is a scheme and host only, like https://app.example: ${origin}`,
+		);
+	}
+	return url.origin;
+}
+
+export function encodeLink(link: PairingLink): string {
+	checkFields(link);
+	const fragment = [
+		LINK_VERSION,
+		base64urlEncode(link.room),
+		base64urlEncode(link.staticPublicKey),
+		base64urlEncode(link.psk),
+		String(link.expiry),
+	].join(".");
+	return `${normalizeWebOrigin(link.webOrigin)}/#${fragment}`;
+}
+
+/** Parses a link. It does not check expiry: see {@link isLinkExpired}. */
+export function parseLink(text: string): PairingLink {
+	const hashIndex = text.indexOf("#");
+	if (hashIndex < 0) {
+		throw new LinkError("The link has no fragment");
+	}
+	const base = text.slice(0, hashIndex).replace(/\/$/, "");
+	const webOrigin = normalizeWebOrigin(base);
+	const parts = text.slice(hashIndex + 1).split(".");
+	if (parts.length !== 5 || parts[0] !== LINK_VERSION) {
+		throw new LinkError("Not a v1 link");
+	}
+	const [, room, staticPublicKey, psk, expiry] = parts as [
+		string,
+		string,
+		string,
+		string,
+		string,
+	];
+	if (!/^[1-9][0-9]{0,15}$/.test(expiry)) {
+		throw new LinkError("Invalid expiry");
+	}
+	const link: PairingLink = {
+		webOrigin,
+		room: decodeField(room, "room"),
+		staticPublicKey: decodeField(staticPublicKey, "static key"),
+		psk: decodeField(psk, "psk"),
+		expiry: Number(expiry),
+	};
+	checkFields(link);
+	return link;
+}
+
+export function isLinkExpired(link: PairingLink, nowMs = Date.now()): boolean {
+	return nowMs >= link.expiry * 1000;
+}
+
+/** The room id as it appears in the relay URL: base64url, 22 characters. */
+export function roomId(room: Uint8Array): string {
+	return base64urlEncode(room);
+}
+
+/**
+ * The Noise prologue: `"acpantenna-relay/1" ‖ 0x00 ‖ room ‖ 0x00 ‖ web
+ * origin`, binding the handshake to this room and this web client.
+ */
+export function prologue(room: Uint8Array, webOrigin: string): Uint8Array {
+	if (room.length !== ROOM_LENGTH) {
+		throw new LinkError("A room is 16 bytes");
+	}
+	return concatBytes(
+		utf8Encode(PROLOGUE_LABEL),
+		Uint8Array.of(0),
+		room,
+		Uint8Array.of(0),
+		utf8Encode(normalizeWebOrigin(webOrigin)),
+	);
+}
+
+function decodeField(text: string, name: string): Uint8Array {
+	try {
+		return base64urlDecode(text);
+	} catch {
+		throw new LinkError(`Invalid ${name}`);
+	}
+}
+
+function checkFields(link: PairingLink): void {
+	if (link.room.length !== ROOM_LENGTH) {
+		throw new LinkError("A room is 16 bytes");
+	}
+	if (link.staticPublicKey.length !== KEY_LENGTH) {
+		throw new LinkError("A static key is 32 bytes");
+	}
+	if (link.psk.length !== KEY_LENGTH) {
+		throw new LinkError("A psk is 32 bytes");
+	}
+	if (!Number.isSafeInteger(link.expiry) || link.expiry <= 0) {
+		throw new LinkError("Invalid expiry");
+	}
+}