@hachej/boring-files 0.0.0-stage → 0.2.1

package/dist/platform.js

@@ -0,0 +1,157 @@
+/**
+ * Environment-sensitive browser capabilities, in one place. Browsers expose `crypto.randomUUID`, `crypto.subtle`,
+ * `navigator.clipboard` and `navigator.share` only in secure contexts (HTTPS, localhost); a page served over plain HTTP on a
+ * private network gets none of them. Every browser-reachable package and the studio import these instead of the raw APIs,
+ * and `npm run check` (scripts/check-platform-apis.mjs) fails when browser-reachable source uses a raw one.
+ */
+/** A version 4 UUID; falls back to `crypto.getRandomValues`, which every context has. */
+export function randomUUID() {
+    const crypto = globalThis.crypto;
+    if (typeof crypto.randomUUID === 'function')
+        return crypto.randomUUID();
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * Puts `text` on the clipboard: the async Clipboard API where present, otherwise a hidden-textarea `execCommand('copy')`
+ * (works over plain HTTP). Resolves `false` when neither worked, so the caller can show the text for a manual copy.
+ */
+export async function copyToClipboard(text) {
+    try {
+        const clipboard = globalThis.navigator?.clipboard;
+        if (clipboard) {
+            await clipboard.writeText(text);
+            return true;
+        }
+    }
+    catch { /* denied or unfocused: try the selection route */ }
+    const doc = globalThis.document;
+    if (!doc?.body || typeof doc.execCommand !== 'function')
+        return false;
+    const area = doc.createElement('textarea');
+    area.value = text;
+    area.setAttribute('readonly', '');
+    area.style.cssText = 'position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;pointer-events:none';
+    const focus = doc.activeElement instanceof HTMLElement ? doc.activeElement : undefined;
+    doc.body.append(area);
+    try {
+        area.select();
+        area.setSelectionRange(0, text.length);
+        return doc.execCommand('copy');
+    }
+    catch {
+        return false;
+    }
+    finally {
+        area.remove();
+        focus?.focus({ preventScroll: true });
+    }
+}
+/** SHA-256 of `bytes`; without `crypto.subtle` it uses the portable standard (FIPS 180-4) implementation below, with identical output. */
+export async function sha256(bytes) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle)
+        return new Uint8Array(await subtle.digest('SHA-256', bytes));
+    return sha256Portable(bytes);
+}
+/** SHA-1 of `bytes` (a content identifier, not a security boundary): `crypto.subtle` where present, otherwise the portable implementation below. */
+export async function sha1(bytes) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle)
+        return new Uint8Array(await subtle.digest('SHA-1', bytes));
+    return sha1Portable(bytes);
+}
+/** Exported for the equivalence check only; use `sha1`. */
+export function sha1Portable(bytes) {
+    const length = bytes.length, blocks = Math.ceil((length + 9) / 64);
+    const padded = new Uint8Array(blocks * 64);
+    padded.set(bytes);
+    padded[length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(length / 0x20000000));
+    view.setUint32(padded.length - 4, (length * 8) >>> 0);
+    const h = Uint32Array.from([0x67452301, 0xefcdab89, 0x98badcfe, 0x10325476, 0xc3d2e1f0]);
+    const w = new Uint32Array(80);
+    const rotl = (x, n) => (x << n) | (x >>> (32 - n));
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 80; i++)
+            w[i] = rotl(w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16], 1);
+        let [a, b, c, d, e] = [h[0], h[1], h[2], h[3], h[4]];
+        for (let i = 0; i < 80; i++) {
+            const f = i < 20 ? (b & c) | (~b & d) : i < 40 ? b ^ c ^ d : i < 60 ? (b & c) | (b & d) | (c & d) : b ^ c ^ d;
+            const k = i < 20 ? 0x5a827999 : i < 40 ? 0x6ed9eba1 : i < 60 ? 0x8f1bbcdc : 0xca62c1d6;
+            const t = (rotl(a, 5) + f + e + k + w[i]) >>> 0;
+            e = d;
+            d = c;
+            c = rotl(b, 30) >>> 0;
+            b = a;
+            a = t;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+    }
+    const out = new Uint8Array(20), outView = new DataView(out.buffer);
+    h.forEach((word, i) => outView.setUint32(i * 4, word));
+    return out;
+}
+const K = Uint32Array.from([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+    0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** Exported for the equivalence check only; use `sha256`. */
+export function sha256Portable(bytes) {
+    const length = bytes.length, blocks = Math.ceil((length + 9) / 64);
+    const padded = new Uint8Array(blocks * 64);
+    padded.set(bytes);
+    padded[length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(length / 0x20000000));
+    view.setUint32(padded.length - 4, (length * 8) >>> 0);
+    const h = Uint32Array.from([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const w = new Uint32Array(64);
+    const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const a = w[i - 15], b = w[i - 2];
+            w[i] = (w[i - 16] + (rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3)) + w[i - 7] + (rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10))) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, k] = [h[0], h[1], h[2], h[3], h[4], h[5], h[6], h[7]];
+        for (let i = 0; i < 64; i++) {
+            const t1 = (k + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i]) >>> 0;
+            const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+            k = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + k) >>> 0;
+    }
+    const out = new Uint8Array(32), outView = new DataView(out.buffer);
+    h.forEach((word, i) => outView.setUint32(i * 4, word));
+    return out;
+}

package/dist/publication-input.d.ts

@@ -0,0 +1,15 @@
+import type { PublicationRequest, PublicationResult, ResourceAccess, ResourceLocator, ResourceRef } from './contracts.js';
+/** This invocation did not dispatch. Earlier attempts with the same ID may still have effects. */
+export declare class PublicationNotDispatchedError extends Error {
+    readonly operationId: string;
+    constructor(operationId: string);
+}
+export declare function identifier(value: unknown): string;
+export declare function locator(value: unknown): ResourceLocator;
+export declare function reference(value: unknown): ResourceRef;
+export declare function accessSnapshot(value: ResourceAccess): ResourceAccess;
+export declare function publicationSnapshot(value: unknown): PublicationRequest;
+export declare function publicationDigest(input: PublicationRequest): Promise<string>;
+/** Parse transport/provider output before treating it as acknowledgement. */
+export declare function parsePublicationResult(value: unknown): PublicationResult;
+//# sourceMappingURL=publication-input.d.ts.map

package/dist/publication-input.js

@@ -0,0 +1,164 @@
+import { sha256 } from './platform.js';
+/** This invocation did not dispatch. Earlier attempts with the same ID may still have effects. */
+export class PublicationNotDispatchedError extends Error {
+    operationId;
+    constructor(operationId) {
+        super('Publication request could not be prepared and was not dispatched');
+        this.name = 'PublicationNotDispatchedError';
+        this.operationId = identifier(operationId);
+    }
+}
+function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Expected an object');
+    return Object.fromEntries(Object.entries(value));
+}
+export function identifier(value) {
+    if (typeof value !== 'string' || !value.length || value.length > 1024 || /[\u0000-\u001f]/u.test(value) || /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(value)) {
+        throw new TypeError('Expected a nonempty well-formed identifier without control characters');
+    }
+    return value;
+}
+/** Human-readable refusal text from a provider: normalized and bounded rather than rejected, so a long or multi-line reason cannot downgrade the outcome. */
+function reason(value) {
+    if (typeof value !== 'string')
+        throw new TypeError('Expected a refusal reason');
+    const text = value.replace(/[\u0000-\u001f]+/g, ' ').trim().slice(0, 1024).replace(/[\uD800-\uDBFF]$/, '');
+    return identifier(text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '\uFFFD') || 'No reason given');
+}
+export function locator(value) {
+    const input = object(value);
+    const resource = object(input.resource);
+    const path = identifier(resource.path);
+    if (path.includes('\\') || path.includes('%') || path.split('/').some(part => !part || part === '.' || part === '..')) {
+        throw new TypeError('Expected a relative canonical resource path');
+    }
+    const view = object(input.view);
+    if (view.kind !== 'published' && view.kind !== 'working')
+        throw new TypeError('Invalid resource view');
+    return {
+        resource: { providerId: identifier(resource.providerId), path },
+        view: view.kind === 'published' ? { kind: 'published' } : { kind: 'working', viewId: identifier(view.viewId) },
+    };
+}
+export function reference(value) {
+    return { ...locator(value), revision: identifier(object(value).revision) };
+}
+export function accessSnapshot(value) {
+    return {
+        principalId: identifier(value.principalId), scopeId: identifier(value.scopeId), initiatorId: identifier(value.initiatorId),
+        ...(value.authorizationRef === undefined ? {} : { authorizationRef: identifier(value.authorizationRef) }),
+        ...(value.signal === undefined ? {} : { signal: value.signal }),
+    };
+}
+function expectation(value) {
+    const input = object(value);
+    if (input.kind === 'absent')
+        return { kind: 'absent', target: locator(input.target) };
+    if (input.kind === 'revision')
+        return { kind: 'revision', target: reference(input.target) };
+    throw new TypeError('Invalid resource expectation');
+}
+function change(value) {
+    const input = object(value);
+    if (input.kind === 'delete')
+        return { kind: 'delete', target: reference(input.target) };
+    if (input.kind !== 'create' && input.kind !== 'replace')
+        throw new TypeError('Invalid resource change');
+    if (!(input.bytes instanceof Uint8Array))
+        throw new TypeError('Resource bytes must be Uint8Array');
+    const bytes = Uint8Array.from(input.bytes);
+    const mediaType = identifier(input.mediaType);
+    if (input.kind === 'replace')
+        return { kind: 'replace', target: reference(input.target), bytes, mediaType };
+    if (object(input.expected).kind !== 'absent')
+        throw new TypeError('Create requires explicit absence');
+    return { kind: 'create', target: locator(input.target), expected: { kind: 'absent' }, bytes, mediaType };
+}
+export function publicationSnapshot(value) {
+    const input = object(value);
+    if (!Array.isArray(input.changes) || !input.changes.length)
+        throw new TypeError('Publication requires changes');
+    if (input.atomicity !== 'all-or-nothing' && input.atomicity !== 'per-change')
+        throw new TypeError('Invalid atomicity');
+    const [first, ...rest] = input.changes;
+    const changes = [change(first), ...rest.map(change)];
+    const targets = changes.map(item => JSON.stringify(item.target.resource) + JSON.stringify(item.target.view));
+    if (new Set(targets).size !== targets.length)
+        throw new TypeError('A publication cannot change the same target twice');
+    if (input.preconditions !== undefined && !Array.isArray(input.preconditions))
+        throw new TypeError('Invalid preconditions');
+    return {
+        operationId: identifier(input.operationId), changes, atomicity: input.atomicity,
+        ...(input.preconditions === undefined ? {} : { preconditions: input.preconditions.map(expectation) }),
+    };
+}
+export async function publicationDigest(input) {
+    const request = publicationSnapshot(input);
+    const canonical = JSON.stringify({
+        format: 'boring-publication-v1',
+        atomicity: request.atomicity,
+        changes: request.changes.map(item => item.kind === 'delete' ? item : { ...item, bytes: Array.from(item.bytes) }),
+        preconditions: request.preconditions ?? [],
+    });
+    const digest = await sha256(new TextEncoder().encode(canonical));
+    return 'boring-publication-v1:sha256:' + Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+function committedChange(value) {
+    const input = object(value);
+    if (input.kind === 'create' && input.before === null)
+        return { kind: 'create', before: null, after: reference(input.after) };
+    if (input.kind === 'delete' && input.after === null)
+        return { kind: 'delete', before: reference(input.before), after: null };
+    if (input.kind === 'replace') {
+        const before = reference(input.before), after = reference(input.after);
+        if (JSON.stringify(locator(before)) !== JSON.stringify(locator(after)))
+            throw new TypeError('Invalid replacement receipt');
+        return { kind: 'replace', before, after };
+    }
+    throw new TypeError('Invalid committed change');
+}
+function publicationReceipt(value) {
+    const input = object(value);
+    if (!Array.isArray(input.changes) || !input.changes.length)
+        throw new TypeError('Receipt requires changes');
+    const [first, ...rest] = input.changes;
+    return {
+        operationId: identifier(input.operationId), argumentDigest: identifier(input.argumentDigest),
+        principalId: identifier(input.principalId), scopeId: identifier(input.scopeId), initiatorId: identifier(input.initiatorId),
+        evidenceRef: identifier(input.evidenceRef), changes: [committedChange(first), ...rest.map(committedChange)],
+    };
+}
+function publicationOutcome(value) {
+    const input = object(value);
+    switch (input.kind) {
+        case 'committed': return { kind: 'committed', receipt: publicationReceipt(input.receipt) };
+        case 'denied':
+        case 'unavailable': return { kind: input.kind, reason: reason(input.reason) };
+        case 'unknown': return { kind: 'unknown', operationId: identifier(input.operationId), reason: reason(input.reason) };
+        case 'conflict': {
+            if (!Array.isArray(input.current))
+                throw new TypeError('Conflict requires current references');
+            return { kind: 'conflict', current: input.current.map(reference), reason: reason(input.reason) };
+        }
+        default: throw new TypeError('Invalid publication outcome');
+    }
+}
+/** Parse transport/provider output before treating it as acknowledgement. */
+export function parsePublicationResult(value) {
+    const input = object(value);
+    if (input.kind !== 'partial')
+        return publicationOutcome(input);
+    if (!Array.isArray(input.items) || !input.items.length)
+        throw new TypeError('Partial publication requires items');
+    const items = input.items.map(value => {
+        const item = object(value);
+        if (typeof item.changeIndex !== 'number' || !Number.isSafeInteger(item.changeIndex) || item.changeIndex < 0)
+            throw new TypeError('Invalid change index');
+        return { changeIndex: item.changeIndex, target: locator(item.target), outcome: publicationOutcome(item.outcome) };
+    });
+    const [first, ...rest] = items;
+    if (!first || new Set(items.map(item => item.changeIndex)).size !== items.length)
+        throw new TypeError('Invalid partial publication coverage');
+    return { kind: 'partial', operationId: identifier(input.operationId), items: [first, ...rest] };
+}

package/dist/remote-handler.d.ts

@@ -0,0 +1,11 @@
+import type { PublicationLookup, ResourceAccess, ResourcePublisher, ResourceReader } from './contracts.js';
+export interface ResourceHandlerOptions {
+    readonly authenticate: (request: Request) => Promise<ResourceAccess | null>;
+    readonly reader: ResourceReader;
+    readonly publisher?: ResourcePublisher;
+    readonly lookup?: PublicationLookup;
+    readonly maxRequestBytes?: number;
+    readonly maxResponseBytes?: number;
+}
+export declare function createResourceHandler(options: ResourceHandlerOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=remote-handler.d.ts.map

package/dist/remote-handler.js

@@ -0,0 +1,63 @@
+import { guardStatus, readJsonBody } from './request-guard.js';
+import { accessSnapshot, publicationDigest } from './publication-input.js';
+import { contentType, decodeCall, encode, envelope, identity, limit, lookupResult, observe, publicationResult, readResult, sameIdentity, schema, version } from './remote-protocol.js';
+export function createResourceHandler(options) {
+    const { authenticate, reader, publisher, lookup } = options;
+    const requestLimit = limit(options.maxRequestBytes ?? 4_194_304), responseLimit = limit(options.maxResponseBytes ?? 8_388_608);
+    return async (request) => {
+        const refuse = (status) => new Response(null, { status, headers: { 'cache-control': 'no-store' } });
+        try {
+            if (request.method !== 'POST')
+                return refuse(405);
+            const authenticated = await observe(authenticate(request), request.signal);
+            if (!authenticated)
+                return refuse(403);
+            const captured = accessSnapshot(authenticated);
+            const signal = captured.signal ? AbortSignal.any([captured.signal, request.signal]) : request.signal;
+            const access = { ...captured, signal };
+            if (signal.aborted)
+                return refuse(403);
+            const input = envelope(await readJsonBody(request, requestLimit, signal));
+            if (!sameIdentity(input.identity, captured))
+                return refuse(403);
+            const call = decodeCall(input);
+            let value;
+            switch (call.kind) {
+                case 'read': {
+                    if (signal.aborted)
+                        return refuse(403);
+                    value = readResult(await observe(reader.read(call.value, access), signal), call.value);
+                    break;
+                }
+                case 'publish': {
+                    if (!publisher)
+                        return refuse(405);
+                    const digest = await observe(publicationDigest(call.value), signal);
+                    if (signal.aborted)
+                        return refuse(403);
+                    value = publicationResult(await observe(publisher.publish(call.value, access), signal), call.value.operationId, captured, call.value, digest);
+                    break;
+                }
+                case 'lookup': {
+                    if (!lookup)
+                        return refuse(405);
+                    if (signal.aborted)
+                        return refuse(403);
+                    value = lookupResult(await observe(lookup.lookup(call.value, access), signal), call.value, captured);
+                    break;
+                }
+            }
+            if (signal.aborted)
+                return refuse(403);
+            const body = encode({ schema, version, requestId: input.requestId, identity: identity(captured), kind: call.kind, value }, responseLimit);
+            return new Response(body, { status: 200, headers: { 'content-type': contentType, 'cache-control': 'no-store' } });
+        }
+        catch (error) {
+            return refuse(guardStatus(error));
+        }
+        finally {
+            if (!request.bodyUsed)
+                void request.body?.cancel().catch(() => { });
+        }
+    };
+}

package/dist/remote-protocol.d.ts

@@ -0,0 +1,34 @@
+import type { PublicationLookupResult, PublicationRequest, PublicationResult, ReadResult, ResourceAccess, ResourceRead } from './contracts.js';
+export type ResourceIdentity = Pick<ResourceAccess, 'principalId' | 'scopeId' | 'initiatorId'>;
+export type ResourceCall = {
+    readonly kind: 'read';
+    readonly value: ResourceRead;
+} | {
+    readonly kind: 'publish';
+    readonly value: PublicationRequest;
+} | {
+    readonly kind: 'lookup';
+    readonly value: string;
+};
+export declare const schema = "boring-resource";
+export declare const version = 2;
+export declare const contentType = "application/json";
+export declare function object(value: unknown): Record<string, unknown>;
+export declare function identity(value: ResourceIdentity): ResourceIdentity;
+export declare function sameIdentity(left: ResourceIdentity, right: ResourceIdentity): boolean;
+export declare function envelope(value: unknown): {
+    requestId: string;
+    identity: ResourceIdentity;
+    kind: ResourceCall['kind'];
+    value: unknown;
+};
+export declare function readSnapshot(value: unknown): ResourceRead;
+export declare function decodeCall(input: ReturnType<typeof envelope>): ResourceCall;
+export declare function encode(value: unknown, limit: number): string;
+export declare function limit(value: number): number;
+export declare function observe<Value>(pending: Promise<Value>, signal?: AbortSignal): Promise<Value>;
+export { readJsonBody as jsonBody } from './request-guard.js';
+export declare function readResult(value: unknown, request: ResourceRead, wire?: boolean): ReadResult;
+export declare function publicationResult(value: unknown, operationId: string, selected: ResourceIdentity, request?: PublicationRequest, digest?: string): PublicationResult;
+export declare function lookupResult(value: unknown, operationId: string, selected: ResourceIdentity): PublicationLookupResult;
+//# sourceMappingURL=remote-protocol.d.ts.map

package/dist/remote-protocol.js

@@ -0,0 +1,154 @@
+import { accessSnapshot, identifier, locator, parsePublicationResult, publicationSnapshot, reference } from './publication-input.js';
+export const schema = 'boring-resource';
+export const version = 2;
+export const contentType = 'application/json';
+export function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Expected an object');
+    return Object.fromEntries(Object.entries(value));
+}
+export function identity(value) {
+    const { principalId, scopeId, initiatorId } = accessSnapshot(value);
+    return { principalId, scopeId, initiatorId };
+}
+export function sameIdentity(left, right) {
+    return left.principalId === right.principalId && left.scopeId === right.scopeId && left.initiatorId === right.initiatorId;
+}
+function wireIdentity(value) {
+    const input = object(value);
+    return { principalId: identifier(input.principalId), scopeId: identifier(input.scopeId), initiatorId: identifier(input.initiatorId) };
+}
+export function envelope(value) {
+    const input = object(value);
+    if (input.schema !== schema || input.version !== version)
+        throw new TypeError('Unsupported resource protocol');
+    if (input.kind !== 'read' && input.kind !== 'publish' && input.kind !== 'lookup')
+        throw new TypeError('Unsupported resource method');
+    return { requestId: identifier(input.requestId), identity: wireIdentity(input.identity), kind: input.kind, value: input.value };
+}
+export function readSnapshot(value) {
+    const input = object(value), revision = object(input.revision);
+    if (revision.kind !== 'latest' && revision.kind !== 'exact')
+        throw new TypeError('Invalid revision selector');
+    return { target: locator(input.target), revision: revision.kind === 'latest' ? { kind: 'latest' } : { kind: 'exact', value: identifier(revision.value) } };
+}
+/** Bytes travel as canonical base64 text; JSON number arrays multiplied the size by three to four. */
+function encodeBytes(value) {
+    let text = '';
+    for (let index = 0; index < value.length; index += 0x8000)
+        text += String.fromCharCode(...value.subarray(index, index + 0x8000));
+    return btoa(text);
+}
+function decodeBytes(value) {
+    let text;
+    try {
+        text = atob(value);
+    }
+    catch {
+        throw new TypeError('Invalid resource bytes');
+    }
+    const result = new Uint8Array(text.length);
+    for (let index = 0; index < text.length; index++)
+        result[index] = text.charCodeAt(index);
+    if (encodeBytes(result) !== value)
+        throw new TypeError('Invalid resource bytes');
+    return result;
+}
+function bytes(value) {
+    if (typeof value !== 'string')
+        throw new TypeError('Invalid resource bytes');
+    return decodeBytes(value);
+}
+export function decodeCall(input) {
+    if (input.kind === 'read')
+        return { kind: 'read', value: readSnapshot(input.value) };
+    if (input.kind === 'lookup')
+        return { kind: 'lookup', value: identifier(input.value) };
+    const value = object(input.value);
+    if (!Array.isArray(value.changes))
+        throw new TypeError('Missing changes');
+    const changes = value.changes.map(item => {
+        const change = object(item);
+        return change.kind === 'delete' ? change : { ...change, bytes: bytes(change.bytes) };
+    });
+    const request = publicationSnapshot({ ...value, changes });
+    if (request.atomicity !== 'all-or-nothing')
+        throw new TypeError('Remote per-change publication is not qualified');
+    return { kind: 'publish', value: request };
+}
+export function encode(value, limit) {
+    const json = JSON.stringify(value, (_key, item) => item instanceof Uint8Array ? encodeBytes(item) : item);
+    if (new TextEncoder().encode(json).byteLength > limit)
+        throw new RangeError('Resource message exceeds byte limit');
+    return json;
+}
+export function limit(value) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 67_108_864)
+        throw new TypeError('Expected a byte limit between 1 and 67108864');
+    return value;
+}
+export function observe(pending, signal) {
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener('abort', abort); reject(new Error('Resource observation aborted')); };
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        pending.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    });
+}
+export { readJsonBody as jsonBody } from './request-guard.js';
+function sameTarget(left, right) {
+    return JSON.stringify(locator(left)) === JSON.stringify(locator(right));
+}
+export function readResult(value, request, wire = false) {
+    const input = object(value);
+    if (input.kind === 'missing')
+        return { kind: 'missing' };
+    if (input.kind === 'denied' || input.kind === 'unavailable')
+        return { kind: input.kind, reason: identifier(input.reason) };
+    if (input.kind !== 'available')
+        throw new TypeError('Invalid read result');
+    const snapshot = object(input.snapshot), ref = reference(snapshot.ref);
+    if (!sameTarget(ref, request.target) || (request.revision.kind === 'exact' && ref.revision !== request.revision.value))
+        throw new TypeError('Read reference mismatch');
+    const content = wire ? bytes(snapshot.bytes) : snapshot.bytes;
+    if (!(content instanceof Uint8Array))
+        throw new TypeError('Invalid snapshot bytes');
+    return { kind: 'available', snapshot: { ref, bytes: Uint8Array.from(content), mediaType: identifier(snapshot.mediaType) } };
+}
+function outcomeAgreement(result, operationId, selected, changes, digest) {
+    if (result.kind === 'unknown' && result.operationId !== operationId)
+        throw new TypeError('Unknown operation mismatch');
+    if (result.kind !== 'committed')
+        return;
+    const receipt = result.receipt;
+    if (receipt.operationId !== operationId || !sameIdentity(receipt, selected) || (digest !== undefined && receipt.argumentDigest !== digest))
+        throw new TypeError('Receipt identity mismatch');
+    const targets = receipt.changes.map(change => JSON.stringify(locator(change.after ?? change.before)));
+    if (new Set(targets).size !== targets.length)
+        throw new TypeError('Duplicate receipt target');
+    if (!changes)
+        return;
+    if (receipt.changes.length !== changes.length)
+        throw new TypeError('Receipt change count mismatch');
+    const committedByTarget = new Map(receipt.changes.map(change => [JSON.stringify(locator(change.after ?? change.before)), change]));
+    for (const change of changes) {
+        const committed = committedByTarget.get(JSON.stringify(locator(change.target)));
+        if (!committed || committed.kind !== change.kind)
+            throw new TypeError('Receipt change mismatch');
+        if (change.kind !== 'create' && JSON.stringify(committed.before) !== JSON.stringify(change.target))
+            throw new TypeError('Receipt base mismatch');
+    }
+}
+export function publicationResult(value, operationId, selected, request, digest) {
+    const result = parsePublicationResult(value);
+    if (result.kind === 'partial')
+        throw new TypeError('Remote partial receipts are not qualified');
+    outcomeAgreement(result, operationId, selected, request?.changes, digest);
+    return result;
+}
+export function lookupResult(value, operationId, selected) {
+    return object(value).kind === 'not-found' ? { kind: 'not-found' } : publicationResult(value, operationId, selected);
+}

package/dist/remote.d.ts

@@ -0,0 +1,26 @@
+import type { ResourceClient } from './client.js';
+import type { ResourceIdentity } from './remote-protocol.js';
+export { createResourceHandler } from './remote-handler.js';
+export type { ResourceHandlerOptions } from './remote-handler.js';
+export type { ResourceIdentity } from './remote-protocol.js';
+interface ResourceClientBase {
+    readonly identity: ResourceIdentity;
+    readonly endpoint: string | URL;
+    readonly fetch: (request: Request) => Promise<Response>;
+    readonly maxRequestBytes?: number;
+    readonly maxResponseBytes?: number;
+}
+/**
+ * A client that can publish must also be able to reconcile (`lookup`): after one lost acknowledgement the editor's save
+ * is `unknown`, and without a lookup nothing can release it, so the editor would stay unsavable until a reload dropped
+ * the unsaved text. The type requires both, and the constructor throws if a plain-JS caller sets only `publication`.
+ */
+export type ResourceClientOptions = ResourceClientBase & ({
+    readonly publication: true;
+    readonly reconciliation: true;
+} | {
+    readonly publication?: false;
+    readonly reconciliation?: boolean;
+});
+export declare function createResourceClient(options: ResourceClientOptions): ResourceClient;
+//# sourceMappingURL=remote.d.ts.map