Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

feat(relay): add bounded sealed snapshot pages [H15,H17]

Corey Olson635f005c6f79
diff --git a/src/sealed-pages.js b/src/sealed-pages.js
new file mode 100644
index 00000000..3e3f41be
--- /dev/null
+++ b/src/sealed-pages.js
@@ -0,0 +1,177 @@
+/** Bounded, device-sealed snapshot objects; plaintext and private cache fingerprints never reach the relay [H15,H17]. */
+import { Refused } from './refused.js';
+import { seal, unseal } from './seal.js';
+
+export const PAGE_BYTES = 262_144;
+export const PAGE_FANOUT = 64;
+export const PAGE_CIPHER_BYTES = 400_000;
+const PREFIX = new TextEncoder().encode('pullboard-sealed-page/1\n');
+const MAX_DEPTH = 32;
+
+/** Refuse malformed pages without repeating authenticated content or private material. */
+function invalid() {
+ return new Refused('SNAPSHOT_PAGE_FORMAT', 'This sealed snapshot page is invalid. Refresh it from a linked machine or upgrade this device.');
+}
+
+/** Validate a content address and its authenticated position before requesting any bytes. */
+export function pageReference(value) {
+ if (!value || !/^[0-9a-f]{64}$/u.test(value.id ?? '') || !Number.isSafeInteger(value.sequence) || value.sequence < 0 ||
+ !Number.isSafeInteger(value.bytes) || value.bytes < 0) throw invalid();
+ return { id: value.id, sequence: value.sequence, bytes: value.bytes };
+}
+
+/** Hash only explicit bytes; plaintext fingerprints are for the device's private reuse cache. */
+export async function pageDigest(bytes) {
+ const hash = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes));
+ return [...hash].map(value => value.toString(16).padStart(2, '0')).join('');
+}
+
+/** Consume a compression stream with a limit before allocating its complete result. */
+async function transformed(bytes, compress, limit) {
+ const stream = new Blob([bytes]).stream().pipeThrough(compress ? new CompressionStream('gzip') : new DecompressionStream('gzip'));
+ const reader = stream.getReader();
+ const parts = [];
+ let length = 0;
+ try {
+ for (;;) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ length += value.byteLength;
+ if (length > limit) throw invalid();
+ parts.push(value);
+ }
+ } catch {
+ await reader.cancel().catch(() => {});
+ throw invalid();
+ } finally { reader.releaseLock(); }
+ const result = new Uint8Array(length);
+ let offset = 0;
+ for (const part of parts) { result.set(part, offset); offset += part.byteLength; }
+ return result;
+}
+
+/** Encode one bounded leaf or index, reusing only a device-private content lookup. */
+async function writePage(kind, body, children, logicalBytes, context) {
+ if (body.byteLength > PAGE_BYTES || !Number.isSafeInteger(logicalBytes) || logicalBytes < 0) throw invalid();
+ const plain = new Uint8Array(PREFIX.byteLength + 1 + body.byteLength);
+ plain.set(PREFIX); plain[PREFIX.byteLength] = kind; plain.set(body, PREFIX.byteLength + 1);
+ const fingerprint = await pageDigest(plain);
+ const reused = await context.lookup?.(fingerprint);
+ if (reused) {
+ const reference = pageReference(reused);
+ if (reference.bytes !== logicalBytes) throw invalid();
+ return reference;
+ }
+ const compressed = await transformed(plain, true, PAGE_CIPHER_BYTES);
+ const bytes = await seal(context.key, compressed, { boardId: context.boardId, kind: 'snapshot', sequence: context.sequence });
+ if (bytes.byteLength > PAGE_CIPHER_BYTES) throw invalid();
+ const reference = pageReference({ id: await pageDigest(bytes), sequence: context.sequence, bytes: logicalBytes });
+ // Only ciphertext identities and ciphertext are suitable for an upload. The reuse fingerprint stays a separate callback.
+ await context.put({ id: reference.id, sequence: reference.sequence, bytes, children: children.map(child => child.id) });
+ await context.remember?.(fingerprint, reference);
+ return reference;
+}
+
+/** Seal one bounded index; its authenticated children carry the exact uncompressed length of each subtree. */
+async function writeIndex(children, context) {
+ if (!children.length || children.length > PAGE_FANOUT) throw invalid();
+ const references = children.map(pageReference);
+ const length = references.reduce((sum, child) => sum + child.bytes, 0);
+ return writePage(0, new TextEncoder().encode(JSON.stringify(references)), references, length, context);
+}
+
+/**
+ * Seal JSON as a stream of bounded objects and bounded-fanout indexes, with no aggregate transport size cap.
+ * The supplied value is already materialized by its caller; this does not promise constant memory for building that value.
+ * put receives only upload-safe ciphertext metadata. lookup/remember are private device cache hooks, never relay fields.
+ */
+export async function writeSealedValue(value, context) {
+ let json;
+ try { json = JSON.stringify(value); } catch { throw invalid(); }
+ if (json === undefined || typeof context?.put !== 'function') throw invalid();
+ const bytes = new TextEncoder().encode(json);
+ const levels = [];
+ /** Flush complete groups upward without retaining a flat list of every chunk. */
+ async function append(reference, level = 0) {
+ if (level >= MAX_DEPTH) throw invalid();
+ const siblings = levels[level] ??= [];
+ siblings.push(reference);
+ if (siblings.length === PAGE_FANOUT) {
+ levels[level] = [];
+ await append(await writeIndex(siblings, context), level + 1);
+ }
+ }
+ for (let offset = 0; offset < bytes.byteLength; offset += PAGE_BYTES) {
+ const body = bytes.subarray(offset, offset + PAGE_BYTES);
+ await append(await writePage(1, body, [], body.byteLength, context));
+ }
+ let highest = levels.length - 1;
+ while (highest >= 0 && !levels[highest]?.length) highest -= 1;
+ let tail = null;
+ for (let level = 0; level <= highest; level += 1) {
+ const siblings = [...(levels[level] ?? []), ...(tail ? [tail] : [])];
+ if (!siblings.length) continue;
+ if (level === highest && siblings.length === 1) return siblings[0];
+ tail = await writeIndex(siblings, context);
+ }
+ if (!tail) throw invalid();
+ return tail;
+}
+
+/** Authenticate, bound inflation and parse a single object before interpreting its references. */
+async function readPage(reference, context) {
+ const received = await context.get(reference.id);
+ if (!(received instanceof Uint8Array) || received.byteLength > PAGE_CIPHER_BYTES || await pageDigest(received) !== reference.id) throw invalid();
+ const compressed = await unseal(context.key, received, { boardId: context.boardId, kind: 'snapshot', sequence: reference.sequence });
+ const plain = await transformed(compressed, false, PAGE_BYTES + PREFIX.byteLength + 1);
+ if (plain.byteLength <= PREFIX.byteLength || PREFIX.some((byte, index) => plain[index] !== byte)) throw invalid();
+ const kind = plain[PREFIX.byteLength];
+ const body = plain.subarray(PREFIX.byteLength + 1);
+ if (kind === 1) {
+ if (body.byteLength !== reference.bytes) throw invalid();
+ return { body };
+ }
+ if (kind !== 0) throw invalid();
+ let children;
+ try { children = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(body)); } catch { throw invalid(); }
+ if (!Array.isArray(children) || !children.length || children.length > PAGE_FANOUT) throw invalid();
+ children = children.map(pageReference);
+ const length = children.reduce((sum, child) => sum + child.bytes, 0);
+ if (!Number.isSafeInteger(length) || length !== reference.bytes) throw invalid();
+ return { children };
+}
+
+/**
+ * Yield authenticated JSON bytes one bounded leaf at a time. A shared subtree may appear twice; only ancestor cycles refuse.
+ * maxBytes is a consumer's allocation budget for this value, independent of the size of the board's other paged values.
+ */
+export async function* readSealedBytes(rawReference, context, { maxBytes = Number.MAX_SAFE_INTEGER } = {}) {
+ const root = pageReference(rawReference);
+ if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || root.bytes > maxBytes || typeof context?.get !== 'function') throw invalid();
+ const ancestors = new Set();
+ /** Walk in authenticated byte order, without requesting later siblings before they are consumed. */
+ async function* walk(reference, depth) {
+ if (depth >= MAX_DEPTH || ancestors.has(reference.id)) throw invalid();
+ ancestors.add(reference.id);
+ try {
+ const page = await readPage(reference, context);
+ if (page.body) yield page.body;
+ else for (const child of page.children) yield* walk(child, depth + 1);
+ } finally { ancestors.delete(reference.id); }
+ }
+ yield* walk(root, 0);
+}
+
+/** Read one selected JSON value; unrelated history values are neither fetched nor decrypted here. */
+export async function readSealedValue(reference, context, options) {
+ const decoder = new TextDecoder('utf-8', { fatal: true });
+ const parts = [];
+ try {
+ for await (const bytes of readSealedBytes(reference, context, options)) parts.push(decoder.decode(bytes, { stream: true }));
+ parts.push(decoder.decode());
+ return JSON.parse(parts.join(''));
+ } catch (error) {
+ if (error instanceof Refused) throw error;
+ throw invalid();
+ }
+}
diff --git a/test/sealed-pages.test.js b/test/sealed-pages.test.js
new file mode 100644
index 00000000..623e12c5
--- /dev/null
+++ b/test/sealed-pages.test.js
@@ -0,0 +1,104 @@
+/** Sealed page integrity, bounded objects and selected-value reads [H15,H17]. */
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { gzipSync } from 'node:zlib';
+import { test } from 'node:test';
+import { generateBoardKey, seal } from '../src/seal.js';
+import {
+ PAGE_BYTES,
+ PAGE_CIPHER_BYTES,
+ PAGE_FANOUT,
+ pageDigest,
+ readSealedBytes,
+ readSealedValue,
+ writeSealedValue,
+} from '../src/sealed-pages.js';
+
+/** Retain only synthetic encrypted objects, with a distinct private reuse cache and observable reads. */
+async function storage() {
+ const objects = new Map();
+ const fingerprints = new Map();
+ const requested = [];
+ const key = await generateBoardKey();
+ const context = {
+ key, boardId: 'a'.repeat(32), sequence: 7,
+ /** Keep upload metadata distinct from the private plaintext fingerprint callback. */
+ put(object) {
+ assert.deepEqual(Object.keys(object).sort(), ['bytes', 'children', 'id', 'sequence']);
+ assert.ok(object.bytes.byteLength <= PAGE_CIPHER_BYTES);
+ assert.ok(object.children.length <= PAGE_FANOUT);
+ objects.set(object.id, { ...object, bytes: Uint8Array.from(object.bytes) });
+ },
+ /** Count reads without returning device cache metadata. */
+ get(id) {
+ requested.push(id);
+ const found = objects.get(id);
+ if (!found) throw new Error('Synthetic encrypted object is absent.');
+ return found.bytes;
+ },
+ /** Reuse a trusted device-private cache across authenticated snapshot positions. */
+ lookup(fingerprint) { return fingerprints.get(fingerprint); },
+ /** The fingerprint is deliberately absent from every uploaded object. */
+ remember(fingerprint, reference) { fingerprints.set(fingerprint, reference); },
+ };
+ return { objects, requested, context };
+}
+
+test('sealed JSON exceeds one full index while every uploaded object stays bounded [H15,H17]', async () => {
+ const box = await storage();
+ // Real UTF-8 characters cross leaf boundaries; this forces a second index level, not a larger manifest.
+ const value = { marker: 'nested page fixture', text: '🙂'.repeat(Math.ceil(PAGE_BYTES * (PAGE_FANOUT + 1) / 4)) };
+ const reference = await writeSealedValue(value, box.context);
+ const restored = await readSealedValue(reference, box.context);
+ assert.equal(restored.marker, value.marker);
+ assert.equal(restored.text.length, value.text.length);
+ assert.equal(createHash('sha256').update(restored.text).digest('hex'), createHash('sha256').update(value.text).digest('hex'));
+ assert.equal(reference.bytes, Buffer.byteLength(JSON.stringify(value)));
+ assert.ok([...box.objects.values()].some(object => object.children.length === PAGE_FANOUT), 'the complete bounded group became an index');
+ assert.ok(box.objects.get(reference.id).children.length >= 2, 'a later bounded index combines the complete group and its remainder');
+});
+
+test('private reuse preserves authenticated old pages without disclosing their fingerprints [H15,H17]', async () => {
+ const box = await storage();
+ const value = { text: 'retained history '.repeat(PAGE_BYTES / 8) };
+ const first = await writeSealedValue(value, box.context);
+ const count = box.objects.size;
+ const second = await writeSealedValue(value, { ...box.context, sequence: 8 });
+ assert.deepEqual(second, first);
+ assert.equal(box.objects.size, count, 'unchanged history uploads no new cipher objects');
+ assert.equal((await readSealedValue(second, box.context)).text.length, value.text.length);
+ assert.ok([...box.objects.values()].every(object => !Object.hasOwn(object, 'fingerprint')));
+});
+
+test('wrong board, position, ciphertext and subtree lengths cannot become snapshot data [H15,H17]', async () => {
+ const box = await storage();
+ const reference = await writeSealedValue({ marker: 'authenticated synthetic data' }, box.context);
+ await assert.rejects(readSealedValue(reference, { ...box.context, boardId: 'b'.repeat(32) }), { code: 'SEAL_AUTH_FAILED' });
+ await assert.rejects(readSealedValue({ ...reference, sequence: 8 }, box.context), { code: 'SEAL_AUTH_FAILED' });
+ await assert.rejects(readSealedValue({ ...reference, bytes: reference.bytes + 1 }, box.context), { code: 'SNAPSHOT_PAGE_FORMAT' });
+ const bytes = box.objects.get(reference.id).bytes;
+ bytes[bytes.length - 1] ^= 1;
+ await assert.rejects(readSealedValue(reference, box.context), { code: 'SNAPSHOT_PAGE_FORMAT' });
+});
+
+test('a selected-value reader stops fetching when its consumer stops or has no allocation budget [H15,H17]', async () => {
+ const box = await storage();
+ const reference = await writeSealedValue({ text: 'x'.repeat(PAGE_BYTES * 3) }, box.context);
+ box.requested.length = 0;
+ await assert.rejects(readSealedValue(reference, box.context, { maxBytes: 1 }), { code: 'SNAPSHOT_PAGE_FORMAT' });
+ assert.equal(box.requested.length, 0, 'allocation refusal precedes any remote read');
+ for await (const bytes of readSealedBytes(reference, box.context)) {
+ assert.equal(bytes.byteLength, PAGE_BYTES);
+ break;
+ }
+ assert.equal(box.requested.length, 2, 'only the index and first leaf were fetched');
+});
+
+test('an authenticated gzip bomb refuses before a complete oversized page is allocated [H15,H17]', async () => {
+ const box = await storage();
+ const plain = Buffer.concat([Buffer.from('pullboard-sealed-page/1\n'), Buffer.of(1), Buffer.alloc(PAGE_BYTES + 1)]);
+ const bytes = await seal(box.context.key, gzipSync(plain), { boardId: box.context.boardId, kind: 'snapshot', sequence: 7 });
+ const id = await pageDigest(bytes);
+ box.objects.set(id, { bytes });
+ await assert.rejects(readSealedValue({ id, sequence: 7, bytes: PAGE_BYTES + 1 }, box.context), { code: 'SNAPSHOT_PAGE_FORMAT' });
+});