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): serve authenticated paged snapshots [H15,H17]

Corey Olson05fad78222f9
diff --git a/relay/page-store.js b/relay/page-store.js
index 36c1c95d..0ec12882 100644
--- a/relay/page-store.js
+++ b/relay/page-store.js
@@ -105,7 +105,11 @@ export function createRelayPages({ directory, boardId, now = Date.now }) {
}
const row = db.prepare('SELECT id,children FROM page_object WHERE id=?').get(id);
if (!row) {
- if (complete) throw new Refused('SNAPSHOT_PAGE_MISSING', 'Upload the referenced sealed page before publishing: ' + id);
+ if (complete) {
+ const error = new Refused('SNAPSHOT_PAGE_MISSING', 'Upload the referenced sealed page before publishing this snapshot.');
+ error.page = id;
+ throw error;
+ }
return;
}
visiting.add(id);
@@ -129,6 +133,16 @@ export function createRelayPages({ directory, boardId, now = Date.now }) {
});
}
+ /** Resume the same authenticated machine's interrupted upload without inventing another sequence. */
+ function resume(id, principal, sequence) {
+ return atomic(() => {
+ const saved = upload(id, principal);
+ if (saved.sequence !== sequence) throw new Refused('BAD_SEQUENCE', 'Resume the original upload coverage sequence.');
+ db.prepare('UPDATE page_upload SET expires=? WHERE id=?').run(clock() + UPLOAD_MS, saved.id);
+ return { id: saved.id, sequence: saved.sequence };
+ });
+ }
+
/** Store an idempotent bounded object, checking the account budget before adding new bytes. */
function put(id, principal, object, checkBudget = () => {}) {
const identity = objectId(object?.id);
@@ -157,10 +171,10 @@ export function createRelayPages({ directory, boardId, now = Date.now }) {
return atomic(() => {
const staged = upload(id, principal);
if (reference.sequence !== staged.sequence) throw new Refused('BAD_SEQUENCE', 'Publish the coverage sequence named when this upload began.');
- const root = db.prepare('SELECT sequence FROM page_object WHERE id=?').get(reference.id);
+ const root = db.prepare('SELECT sequence,payload FROM page_object WHERE id=?').get(reference.id);
if (!root || root.sequence !== reference.sequence) throw new Refused('SNAPSHOT_PAGE_MISSING', 'Upload this snapshot’s sealed root before publishing it.');
graph([reference.id], true);
- const result = publishHead(reference);
+ const result = publishHead(reference, Buffer.from(root.payload));
if (result && typeof result.then === 'function') throw new Refused('RELAY_CONFIG', 'Commit the journal head synchronously before finishing publication.');
db.prepare('DELETE FROM page_upload WHERE id=?').run(id);
return result;
@@ -226,5 +240,5 @@ export function createRelayPages({ directory, boardId, now = Date.now }) {
/** Close exactly this store; repeated shutdown is harmless. */
function close() { if (!closed) { db.close(); closed = true; } }
- return { begin, put, publish, pin, get, prune, usage, close, file };
+ return { begin, resume, put, publish, pin, get, prune, usage, close, file };
}
diff --git a/relay/pages-http.js b/relay/pages-http.js
new file mode 100644
index 00000000..baccead8
--- /dev/null
+++ b/relay/pages-http.js
@@ -0,0 +1,128 @@
+/** Authenticated relay API2 snapshot objects; stored data remains opaque to the relay [H15,H17]. */
+import { createHash } from 'node:crypto';
+import { apiJson, apiRefusal, apiStatus, readApiBody } from '../src/api-http.js';
+import { Refused } from '../src/refused.js';
+import { PAGE_BYTES, PAGE_CIPHER_BYTES, PAGE_FANOUT, pageReference } from '../src/sealed-pages.js';
+import { createRelayPages } from './page-store.js';
+
+const PAGE_BODY_BYTES = 600_000;
+
+/** Tell the host router that a response was completed, including refusals. */
+function reply(res, status, value) { apiJson(res, status, value); return true; }
+
+/** The journal's authenticated metadata points at the exact opaque root object, without decoding it. */
+export function snapshotPageRoot(snapshot) {
+ if (snapshot?.apiVersion !== 2) return null;
+ return pageReference({ id: createHash('sha256').update(snapshot.bytes).digest('hex'), sequence: snapshot.sequence, bytes: snapshot.pageBytes });
+}
+
+/** Require an intentional API2 object, never an accidentally uploaded key or account field. */
+function only(body, allowed) {
+ if (Object.keys(body).some(key => !allowed.includes(key))) throw new Refused('BAD_REQUEST', 'Send only the fields of this sealed-page operation; keep keys on the device.');
+}
+
+/** Decode canonical ciphertext transport without accepting a permissive base64 alias. */
+function cipherBytes(value) {
+ if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/u.test(value)) throw new Refused('BAD_PAGE', 'Send canonical base64url encrypted page bytes.');
+ const bytes = Buffer.from(value, 'base64url');
+ if (!bytes.byteLength || bytes.byteLength > PAGE_CIPHER_BYTES || bytes.toString('base64url') !== value) throw new Refused('BAD_PAGE', 'Send one bounded encrypted page under its content id.');
+ return bytes;
+}
+
+/** Add the new snapshot transport without changing API1 native board documents or executable move formats. */
+export function createRelayPagesHandler({ directory, now, authorize, withJournal, sender, quota, annotated, enabled = true }) {
+ /** Open objects only while the caller's shared board lifecycle lock and fresh authorization hold. */
+ function withPages(id, who, work, create = false) {
+ return withJournal(id, journal => {
+ const pages = createRelayPages({ directory, boardId: id, now });
+ try { return work(journal, pages); } finally { pages.close(); }
+ }, create, who.engineVersion);
+ }
+
+ /** Preserve supported old heads while making paged heads explicit to new clients. */
+ function head(journal, pages, principal, id) {
+ const snapshot = journal.snapshot();
+ if (!snapshot) throw new Refused('NO_SNAPSHOT', 'Upload a sealed snapshot before reading this board.');
+ const root = snapshotPageRoot(snapshot);
+ if (!root) return { ...annotated(snapshot, id), apiVersion: 1 };
+ const read = pages.pin(principal, root);
+ const warning = quota.notice(id);
+ return { apiVersion: 2, sequence: snapshot.sequence, receivedAt: snapshot.receivedAt, sender: snapshot.sender,
+ root, read, ...(warning ? { warning } : {}) };
+ }
+
+ /** Route only bounded opaque operations; no request supplies the account charged for them. */
+ async function handle(req, res) {
+ let url;
+ try { url = new URL(req.url ?? '/', 'http://127.0.0.1'); }
+ catch { return false; }
+ if (!url.pathname.startsWith('/api/v2')) return false;
+ try {
+ if (req.method === 'GET' && url.pathname === '/api/v2') return reply(res, 200, enabled
+ ? { apiVersion: 2, snapshot: 'sealed-pages', pageBytes: PAGE_BYTES, cipherBytes: PAGE_CIPHER_BYTES, fanout: PAGE_FANOUT }
+ : { apiVersion: 1, snapshot: 'legacy' });
+ if (!enabled) throw new Refused('RELAY_API_VERSION', 'Upgrade the relay authentication adapter to serve relay API version2.');
+ const route = /^\/api\/v2\/boards\/([0-9a-f]{32})\/(state|uploads(?:\/([A-Za-z0-9-]{1,128})(?:\/(publish|objects\/([0-9a-f]{64})))?)?|objects\/([0-9a-f]{64}))$/u.exec(url.pathname);
+ if (!route) throw new Refused('BAD_REQUEST', 'Use a supported relay API version2 sealed-page route.');
+ const id = route[1];
+ const write = req.method !== 'GET';
+ const who = await authorize(req, id, write);
+ const principal = sender(who, write ? 'snapshot' : false);
+ if (req.method === 'GET' && route[2] === 'state') {
+ const state = withPages(id, who, (journal, pages) => head(journal, pages, principal, id));
+ return reply(res, 200, { apiVersion: 2, state });
+ }
+ if (req.method === 'POST' && route[2] === 'uploads') {
+ const body = await readApiBody(req);
+ only(body, ['sequence', 'resume']);
+ const result = withPages(id, who, (journal, pages) => {
+ const current = snapshotPageRoot(journal.snapshot());
+ pages.prune(current ? [current.id] : []);
+ quota.usage(id, principal);
+ const upload = body.resume ? pages.resume(body.resume, principal, body.sequence) : pages.begin(principal, body.sequence);
+ return { upload, storage: quota.usage(id) };
+ }, true);
+ return reply(res, 200, { apiVersion: 2, ...result });
+ }
+ if (req.method === 'PUT' && route[5]) {
+ const body = await readApiBody(req, { maxBytes: PAGE_BODY_BYTES });
+ only(body, ['sequence', 'sealed', 'children']);
+ const object = { id: route[5], sequence: body.sequence, bytes: cipherBytes(body.sealed), children: body.children };
+ const stored = withPages(id, who, (journal, pages) => {
+ const current = snapshotPageRoot(journal.snapshot());
+ pages.prune(current ? [current.id] : []);
+ return pages.put(route[3], principal, object, delta => quota.change(id, principal, delta, () => {}));
+ });
+ return reply(res, 200, { apiVersion: 2, page: stored });
+ }
+ if (req.method === 'POST' && route[4] === 'publish') {
+ const body = await readApiBody(req);
+ only(body, ['root', 'initialOnly']);
+ const reference = pageReference(body.root);
+ if (reference.bytes > PAGE_BYTES || body.initialOnly !== undefined && typeof body.initialOnly !== 'boolean') throw new Refused('BAD_PAGE', 'Publish a bounded sealed root for this upload.');
+ const saved = withPages(id, who, (journal, pages) => {
+ const snapshot = pages.publish(route[3], principal, reference, (root, bytes) => quota.change(id, principal, journal.snapshotDelta(root.sequence, bytes),
+ () => journal.saveSnapshot(root.sequence, bytes, principal, { apiVersion: 2, pageBytes: root.bytes, initialOnly: body.initialOnly === true })));
+ pages.prune([reference.id]);
+ quota.clear(id);
+ return { root: snapshotPageRoot(snapshot), sequence: snapshot.sequence, sender: snapshot.sender, storage: quota.usage(id) };
+ });
+ return reply(res, 200, { apiVersion: 2, state: saved });
+ }
+ if (req.method === 'GET' && route[6]) {
+ const via = url.searchParams.get('via') ?? '';
+ if (via.length > 64 * 65) throw new Refused('BAD_PAGE_PATH', 'Use the bounded path from this pinned snapshot.');
+ const object = withPages(id, who, (journal, pages) => pages.get(url.searchParams.get('pin'), principal, route[6], via ? via.split(',') : []));
+ return reply(res, 200, { apiVersion: 2, page: { id: object.id, sequence: object.sequence, sealed: object.bytes.toString('base64url'), children: object.children } });
+ }
+ throw new Refused('BAD_REQUEST', 'Use the supported method for this sealed-page route.');
+ } catch (error) {
+ const document = apiRefusal(error);
+ if (error instanceof Refused && error.page && /^[0-9a-f]{64}$/u.test(error.page)) document.error.page = error.page;
+ if (error instanceof Refused && error.storage) document.error.storage = error.storage;
+ const status = { ACCOUNT_STORAGE_LIMIT: 507, BAD_PAGE_PATH: 403, SNAPSHOT_READ_EXPIRED: 410, SNAPSHOT_UPLOAD_EXPIRED: 410 }[error.code] ?? apiStatus(error);
+ return reply(res, status, { ...document, apiVersion: 2 });
+ }
+ }
+ return handle;
+}
diff --git a/relay/server.mjs b/relay/server.mjs
index f5d0a147..1f7faf15 100644
--- a/relay/server.mjs
+++ b/relay/server.mjs
@@ -62,6 +62,11 @@ async function startRelay() {
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new Refused('RELAY_PORT', 'set PORT to an available TCP port from 1 to 65535 and restart the service');
}
+ const quotaSetting = process.env.PULLBOARD_ACCOUNT_STORAGE_BYTES;
+ const accountStorageBytes = quotaSetting === undefined ? undefined : Number(quotaSetting);
+ if (quotaSetting !== undefined && (!/^[1-9][0-9]*$/u.test(quotaSetting) || !Number.isSafeInteger(accountStorageBytes))) {
+ throw new Refused('RELAY_CONFIG', 'Set PULLBOARD_ACCOUNT_STORAGE_BYTES to a positive whole-byte account quota, then restart the relay.');
+ }
const privateKey = (process.env.GITHUB_APP_PRIVATE_KEY || '').replaceAll('\\n', '\n');
try { prepareStorage(data); }
catch (error) {
@@ -87,6 +92,7 @@ async function startRelay() {
backupsDirectory: join(data, 'backups'),
auth,
publicOrigin,
+ accountStorageBytes,
});
/** Route readiness, GitHub authentication and opaque board relay requests. */
async function handleRequest(req, res) {
diff --git a/relay/service.js b/relay/service.js
index 2ba41135..6588c94d 100644
--- a/relay/service.js
+++ b/relay/service.js
@@ -13,6 +13,8 @@ import { createPairingStore } from './pairing-store.js';
import { createPairingHandler } from './pairing-http.js';
import { createRelayBrowserHandler } from './browser-page.js';
import { VERIFIER_STANDING_ENGINE } from '../src/machine.js';
+import { createRelayPagesHandler } from './pages-http.js';
+import { createStorageQuota } from './storage-quota.js';
const SNAPSHOT_BODY = 14_000_000;
const STORED_BYTES = 10_000_000;
@@ -108,13 +110,15 @@ function sender(who, personOnly = false) {
}
/** Create a private relay handler; the caller owns sign-in lifecycle and service shutdown. */
-export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin, now = Date.now, backupsDirectory, maintenanceMs = 60_000 }) {
+export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin, now = Date.now, backupsDirectory, maintenanceMs = 60_000, accountStorageBytes }) {
const origin = trustedOrigin(publicOrigin);
if (typeof directory !== 'string' || !directory.trim() || !auth) throw new Refused('RELAY_CONFIG', 'configure a private relay directory and sign-in component');
const root = resolve(directory);
mkdirSync(root, { recursive: true, mode: 0o700 });
const stat = lstatSync(root);
if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) throw new Refused('RELAY_STORAGE', 'use a private directory with mode 700 for relay storage');
+ // Older custom auth adapters remain explicitly API1-only, never an unmetered API2 transport.
+ const quota = auth.storageAccount && auth.storageBoards ? createStorageQuota({ directory: root, auth, limitBytes: accountStorageBytes }) : null;
if (!Number.isSafeInteger(maintenanceMs) || maintenanceMs < 0 || maintenanceMs > 2_147_483_647 || (maintenanceMs > 0 && maintenanceMs < 10)) {
throw new Refused('RELAY_CONFIG', 'use a maintenance interval of at least ten milliseconds, or zero for an external scheduler');
@@ -167,6 +171,7 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin
const declared = req.headers['x-pullboard-engine'];
const version = declared === undefined ? 1 : typeof declared === 'string' && /^[1-9][0-9]*$/.test(declared) ? Number(declared) : NaN;
requireClientVersion(id, version);
+ if (write && quota) auth.storageAccount(id, who.user.id);
return { ...who, engineVersion: version };
}
@@ -180,10 +185,14 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin
/** Add an authorized next-contact warning without exposing any plaintext board contents. */
function annotated(row, id) {
- const warning = retention.notice(id);
+ if (row.apiVersion === 2) throw new Refused('RELAY_API_VERSION', 'This board requires relay API version 2. Upgrade with npm i -g pullboard@latest.');
+ const warning = quota?.notice(id) ?? retention.notice(id);
return { ...state(row), ...(warning ? { warning } : {}) };
}
+ /** Keep the budget check and its write inside the same authenticated lifecycle transaction. */
+ function storing(id, principal, delta, write) { return quota ? quota.change(id, principal, delta, write) : write(); }
+
/** Open only an existing journal on reads; each synchronous operation closes its connection. */
function withJournal(id, work, create = false, engineVersion) {
const file = join(root, identity(id) + '.journal.sqlite');
@@ -225,7 +234,8 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin
const principal = sender(authenticated);
if (body.registration === undefined) {
return withJournal(board.id, (journal) => {
- const row = journal.append(body.sequence, bytes, kind, principal);
+ const row = body.sequence <= journal.latest() ? journal.append(body.sequence, bytes, kind, principal)
+ : storing(board.id, principal, bytes.byteLength, () => journal.append(body.sequence, bytes, kind, principal));
return { status: 200, body: { event: event(row), result: { sequence: row.sequence } } };
}, false, who.engineVersion);
}
@@ -237,7 +247,9 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin
const retry = prior && prior.origin === 'registered' && prior.creator === receipt.creator && prior.sequence === receipt.sequence && prior.digest === receipt.digest;
if (prior && !retry) throw new Refused('SEAT_TAKEN', `the relay already issued ${receipt.target} a token, so it cannot be registered again; register the next free name`);
let row;
- try { row = retry ? journal.recordAt(receipt.sequence) : journal.append(body.sequence, bytes, kind, principal, receipt); }
+ try { row = retry ? journal.recordAt(receipt.sequence) : body.sequence <= journal.latest()
+ ? journal.append(body.sequence, bytes, kind, principal, receipt)
+ : storing(board.id, principal, bytes.byteLength, () => journal.append(body.sequence, bytes, kind, principal, receipt)); }
catch (error) {
// The move and its receipt committed but the seat did not (any failure before enrollment):
// the creator's exact retry rolls the enrollment forward, even after compaction.
@@ -252,6 +264,7 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin
}
const browser = origin ? createRelayBrowserHandler({ authenticate: (req) => auth.authenticate(credential(req, origin)) }) : null;
+ const pagesHandler = createRelayPagesHandler({ directory: root, now, authorize: authorizedRequest, withJournal, sender, quota, annotated, enabled: Boolean(quota) });
const common = createApiHandler({
authenticate: async (req, { board, write }) => {
const token = credential(req, origin, write);
@@ -263,7 +276,10 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin
},
boards: (who) => {
const boards = who.visible.filter((board) => !retention.expire(board.id));
- const warnings = boards.map((board) => retention.notice(board.id)).filter(Boolean);
+ const warnings = boards.flatMap((board) => {
+ const storage = quota?.notice(board.id);
+ return [retention.notice(board.id), ...(storage ? [{ board: board.id, ...storage }] : [])].filter(Boolean);
+ });
return { boards, ...(warnings.length ? { warnings } : {}) };
},
board: (id, who) => { withJournal(id, () => undefined, false, who.engineVersion); return { id, engineVersion: who.engineVersion }; },
@@ -284,6 +300,7 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin
/** Add authenticated snapshot replacement and deletion to the common versioned read/move paths. */
async function handle(req, res) {
+ if (await pagesHandler(req, res)) return;
if (await deviceHandler(req, res)) return;
if (await pairing(req, res)) return;
try {
@@ -317,7 +334,12 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin
if (!Number.isSafeInteger(body.sequence) || body.sequence < 0) throw new Refused('BAD_SEQUENCE', 'name the nonnegative sequence covered by the sealed snapshot');
const who = await authorizedRequest(req, id, true);
const principal = sender(who, 'snapshot');
- const saved = withJournal(id, (journal) => journal.saveSnapshot(body.sequence, bytes, principal, { initialOnly: req.headers['if-none-match'] === '*' }), true, who.engineVersion);
+ const saved = withJournal(id, (journal) => {
+ if (journal.snapshot()?.apiVersion === 2) throw new Refused('RELAY_API_VERSION', 'This board requires relay API version 2. Upgrade with npm i -g pullboard@latest.');
+ const row = storing(id, principal, journal.snapshotDelta(body.sequence, bytes), () => journal.saveSnapshot(body.sequence, bytes, principal, { initialOnly: req.headers['if-none-match'] === '*' }));
+ quota?.clear(id);
+ return row;
+ }, true, who.engineVersion);
return apiJson(res, 200, { state: annotated(saved, id) });
}
if (req.method === 'DELETE' && deletion) {
@@ -336,13 +358,13 @@ export function createRelayHandler({ directory, auth, pollMs = 200, publicOrigin
handle.maintenance = maintain;
handle.backup = retention.backup;
handle.maintenanceStatus = () => ({ error: maintenanceError });
- handle.close = () => { clearInterval(timer); common.close(); releaseSessionGuard?.(); deviceStore.close(); };
+ handle.close = () => { clearInterval(timer); common.close(); releaseSessionGuard?.(); deviceStore.close(); quota?.close(); };
return handle;
}
/** Start the opt-in service on a configured address; tests use loopback and an ephemeral port. */
-export function serveRelay({ directory, auth, port = 0, host = '127.0.0.1', pollMs = 200, publicOrigin, now, backupsDirectory, maintenanceMs }) {
- const handler = createRelayHandler({ directory, auth, pollMs, publicOrigin, now, backupsDirectory, maintenanceMs });
+export function serveRelay({ directory, auth, port = 0, host = '127.0.0.1', pollMs = 200, publicOrigin, now, backupsDirectory, maintenanceMs, accountStorageBytes }) {
+ const handler = createRelayHandler({ directory, auth, pollMs, publicOrigin, now, backupsDirectory, maintenanceMs, accountStorageBytes });
const server = createServer(handler);
server.requestTimeout = 15_000;
return new Promise((ready, fail) => {
diff --git a/relay/storage-quota.js b/relay/storage-quota.js
index 478de2f6..233c5634 100644
--- a/relay/storage-quota.js
+++ b/relay/storage-quota.js
@@ -40,7 +40,8 @@ export function createStorageQuota({ directory, auth, limitBytes = ACCOUNT_STORA
const stat = lstatSync(file);
if (!stat.isFile() || stat.isSymbolicLink() || stat.mode & 0o077) throw new Refused('RELAY_STORAGE', 'Keep quota notices in a private regular database.');
const db = new DatabaseSync(file);
- db.exec('PRAGMA busy_timeout=30000; CREATE TABLE IF NOT EXISTS storage_warning (board TEXT PRIMARY KEY, storage TEXT NOT NULL, needed INTEGER NOT NULL)');
+ try { db.exec('PRAGMA busy_timeout=30000; CREATE TABLE IF NOT EXISTS storage_warning (board TEXT PRIMARY KEY, storage TEXT NOT NULL, needed INTEGER NOT NULL)'); }
+ catch (error) { db.close(); throw error; }
let closed = false;
/** Refuse use after shutdown instead of exposing a native database error. */
diff --git a/test/relay-pages-http.test.js b/test/relay-pages-http.test.js
new file mode 100644
index 00000000..a0d88fb5
--- /dev/null
+++ b/test/relay-pages-http.test.js
@@ -0,0 +1,152 @@
+/** Authenticated API2 publication stays opaque, bounded and compatible with legacy heads [H15,H17,H18]. */
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { test } from 'node:test';
+import { createRelayAuth } from '../relay/auth.js';
+import { createGitHubClient } from '../relay/github.js';
+import { createRelayHandler } from '../relay/service.js';
+import { ENGINE_VERSION } from '../src/machine.js';
+import { generateBoardKey, seal } from '../src/seal.js';
+import { readSealedDescriptor, readSealedValue, writeSealedDescriptor, writeSealedValue } from '../src/sealed-pages.js';
+import { githubFixture } from './relay-fixture.js';
+
+const BOARD = 'a'.repeat(32);
+const OTHER = 'b'.repeat(32);
+
+/** Create real private auth, journals and an HTTP relay; all credentials remain inside the fixture. */
+async function fixture(t, accountStorageBytes) {
+ const provider = await githubFixture(t);
+ const root = mkdtempSync(join(tmpdir(), 'pullboard-page-http-'));
+ const auth = createRelayAuth({ database: join(root, 'auth.sqlite'), github: createGitHubClient(provider.config) });
+ const flow = auth.beginWeb();
+ const redirect = await fetch(flow.authorizationURL, { redirect: 'manual' });
+ const callback = new URL(redirect.headers.get('location'));
+ const signed = await auth.finishWeb(callback.searchParams.get('state'), callback.searchParams.get('code'), flow.binding);
+ await auth.linkBoard(signed.token, BOARD, 'fixture/repository');
+ await auth.linkBoard(signed.token, OTHER, 'fixture/repository');
+ let handler;
+ const server = createServer((req, res) => handler(req, res));
+ server.listen(0, '127.0.0.1'); await once(server, 'listening');
+ const origin = 'http://127.0.0.1:' + server.address().port;
+ handler = createRelayHandler({ directory: join(root, 'boards'), auth, publicOrigin: origin, maintenanceMs: 0, accountStorageBytes });
+ t.after(() => { server.closeAllConnections(); server.close(); handler.close(); auth.close(); rmSync(root, { recursive: true, force: true }); });
+ const key = await generateBoardKey();
+ /** Return only protocol responses, never bearer credentials, in assertion diagnostics. */
+ async function call(method, path, body, token = signed.token, extra = {}) {
+ const response = await fetch(origin + path, { method, headers: { authorization: 'Bearer ' + token,
+ 'x-pullboard-engine': String(ENGINE_VERSION), ...(body === undefined ? {} : { 'content-type': 'application/json' }), ...extra },
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+ return { status: response.status, document: await response.json() };
+ }
+ /** Stage a genuine sealed value and its bounded encrypted directory through public HTTP routes. */
+ async function stage(value, sequence = 0) {
+ const began = await call('POST', '/api/v2/boards/' + BOARD + '/uploads', { sequence });
+ assert.equal(began.status, 200, began.document.error?.message);
+ const upload = began.document.upload;
+ const context = { key, boardId: BOARD, sequence,
+ async put(object) {
+ const stored = await call('PUT', '/api/v2/boards/' + BOARD + '/uploads/' + upload.id + '/objects/' + object.id,
+ { sequence: object.sequence, sealed: Buffer.from(object.bytes).toString('base64url'), children: object.children });
+ if (stored.status !== 200) {
+ const error = new Error(stored.document.error?.message ?? 'Synthetic page upload refused.');
+ Object.assign(error, { code: stored.document.error?.code, status: stored.status, storage: stored.document.error?.storage });
+ throw error;
+ }
+ } };
+ const valueReference = await writeSealedValue(value, context);
+ const reference = await writeSealedDescriptor({ format: 'synthetic-directory', value: valueReference }, [valueReference], context);
+ return { upload, reference, context };
+ }
+ /** Publish one staged complete graph, retaining the actual relay's sequencing checks. */
+ function publish(staged, initialOnly = false) {
+ return call('POST', '/api/v2/boards/' + BOARD + '/uploads/' + staged.upload.id + '/publish', { root: staged.reference, initialOnly });
+ }
+ /** Read and authenticate only selected values, with the graph path anchored at a pinned root. */
+ async function read(state, token = signed.token) {
+ const context = { key, boardId: BOARD,
+ async get(id, parents) {
+ const path = '/api/v2/boards/' + BOARD + '/objects/' + id + '?pin=' + encodeURIComponent(state.read.id)
+ + (parents.length ? '&via=' + encodeURIComponent(parents.join(',')) : '');
+ const result = await call('GET', path, undefined, token);
+ assert.equal(result.status, 200, result.document.error?.message);
+ return Buffer.from(result.document.page.sealed, 'base64url');
+ } };
+ const directory = await readSealedDescriptor(state.root, context);
+ return readSealedValue(directory.value.value, { ...context, parents: [state.root.id] });
+ }
+ return { root, auth, signed, origin, key, call, stage, publish, read };
+}
+
+test('API2 reads legacy heads and publishes opaque pages while old clients explicitly upgrade [H15,H17]', async t => {
+ const box = await fixture(t);
+ const capabilities = await box.call('GET', '/api/v2');
+ assert.equal(capabilities.document.apiVersion, 2);
+ const legacy = Buffer.from(await seal(box.key, Buffer.from('{"legacy":"fixture"}'), { boardId: BOARD, kind: 'snapshot', sequence: 0 })).toString('base64url');
+ assert.equal((await box.call('PUT', '/api/v1/boards/' + BOARD + '/state', { sequence: 0, sealed: legacy })).status, 200);
+ assert.equal((await box.call('GET', '/api/v1/boards/' + BOARD + '/state')).document.state.sealed, legacy);
+ const old = await box.call('GET', '/api/v2/boards/' + BOARD + '/state');
+ assert.equal(old.document.state.apiVersion, 1);
+ assert.equal(old.document.state.sealed, legacy);
+ const value = { marker: 'AUTHENTICATED_HISTORY_THROUGH_OPAQUE_PAGES', text: 'x'.repeat(600_000) };
+ const staged = await box.stage(value);
+ assert.equal((await box.publish(staged)).status, 200);
+ const head = await box.call('GET', '/api/v2/boards/' + BOARD + '/state');
+ assert.equal(head.document.state.root.id, staged.reference.id);
+ const decoded = await box.read(head.document.state);
+ assert.equal(decoded.marker, value.marker); assert.equal(decoded.text.length, value.text.length);
+ const refused = await box.call('GET', '/api/v1/boards/' + BOARD + '/state');
+ assert.equal(refused.document.error.code, 'RELAY_API_VERSION');
+ assert.match(refused.document.error.message, /version 2.*npm i -g pullboard@latest/u);
+ assert.equal((await box.call('PUT', '/api/v1/boards/' + BOARD + '/state', { sequence: 0, sealed: legacy })).document.error.code, 'RELAY_API_VERSION');
+});
+
+test('a pinned HTTP reader survives replacement and staged ids are not public read authority [H15,H17,H18]', async t => {
+ const box = await fixture(t);
+ const first = await box.stage({ marker: 'first complete head' });
+ assert.equal((await box.publish(first, true)).status, 200);
+ const old = (await box.call('GET', '/api/v2/boards/' + BOARD + '/state')).document.state;
+ const move = Buffer.from(await seal(box.key, Buffer.from('synthetic opaque move'), { boardId: BOARD, kind: 'move', sequence: 1 })).toString('base64url');
+ assert.equal((await box.call('POST', '/api/v1/boards/' + BOARD + '/moves', { sequence: 1, sealed: move })).status, 200);
+ const next = await box.stage({ marker: 'second complete head' }, 1);
+ assert.equal((await box.publish(next)).status, 200);
+ assert.equal((await box.read(old)).marker, 'first complete head');
+ const newest = (await box.call('GET', '/api/v2/boards/' + BOARD + '/state')).document.state;
+ assert.equal((await box.read(newest)).marker, 'second complete head');
+ const staged = await box.stage({ marker: 'not yet published' }, 1);
+ const stolen = await box.call('GET', '/api/v2/boards/' + BOARD + '/objects/' + staged.reference.id + '?pin=' + old.read.id);
+ assert.equal(stolen.status, 403); assert.equal(stolen.document.error.code, 'BAD_PAGE_PATH');
+});
+
+test('an account quota refusal preserves the readable head and is named in phone-facing APIs [H15,H17]', async t => {
+ const box = await fixture(t, 2_000);
+ const first = await box.stage({ marker: 'readable before quota' });
+ assert.equal((await box.publish(first)).status, 200);
+ await assert.rejects(box.stage({ text: randomBytes(8_000).toString('base64') }), error => error.code === 'ACCOUNT_STORAGE_LIMIT' && error.status === 507 && error.storage.account.id === box.signed.user.id);
+ const head = await box.call('GET', '/api/v2/boards/' + BOARD + '/state');
+ assert.equal(head.document.state.warning.code, 'ACCOUNT_STORAGE_LIMIT');
+ assert.ok(head.document.state.warning.message.includes(box.signed.user.login));
+ assert.equal((await box.read(head.document.state)).marker, 'readable before quota');
+ const boards = await box.call('GET', '/api/v1/boards');
+ assert.ok(boards.document.warnings.some(warning => warning.board === BOARD && warning.code === 'ACCOUNT_STORAGE_LIMIT'));
+ assert.equal((await box.call('POST', '/api/v2/boards/' + BOARD + '/uploads', { sequence: 0, account: 'another-account' })).document.error.code, 'BAD_REQUEST');
+});
+
+test('all page reads reauthorize the board and a readable agent cannot replace a snapshot [H15,H17]', async t => {
+ const box = await fixture(t);
+ const staged = await box.stage({ marker: 'authorized page' });
+ assert.equal((await box.publish(staged)).status, 200);
+ const agent = await box.auth.issueToken(box.signed.token, { board: BOARD, agent: 'page-observer' });
+ const state = await box.call('GET', '/api/v2/boards/' + BOARD + '/state', undefined, agent.token);
+ assert.equal(state.status, 200);
+ assert.equal((await box.read(state.document.state, agent.token)).marker, 'authorized page');
+ assert.equal((await box.call('POST', '/api/v2/boards/' + BOARD + '/uploads', { sequence: 0 }, agent.token)).status, 403);
+ assert.equal((await box.call('GET', '/api/v2/boards/' + OTHER + '/state', undefined, agent.token)).status, 403);
+ await box.auth.revoke(box.signed.token, agent.id);
+ const after = await box.call('GET', '/api/v2/boards/' + BOARD + '/objects/' + state.document.state.root.id + '?pin=' + state.document.state.read.id, undefined, agent.token);
+ assert.equal(after.status, 401, 'a previously issued read pin never bypasses revocation');
+});