nervur 0.19.2 → 0.20.1

package/dist/quo/door.js

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: Apache-2.0
+// The door: an ask's box in, a reply's box out, judged by the thirteen cases
+// of the spec in their order. A stranger hears one silence whatever the
+// case. The case is handed back beside the bytes, for the kit's own eyes,
+// with `heard`: whether a key the door holds or keeps spoke.
+import { decapsulate, hex, unhex, utf8, x25519Public, zero } from '../crypto/index.js';
+import { drawLock, SigningKey } from './keys.js';
+import { readPayload } from './payload.js';
+import { writeReply } from './reply.js';
+import { checkBody, follow, HEAD, knockEdge, openBody, openHead, replyKey, sealReply, signBody, SIZE, splitBody, splitKnock, ZERO_EDGE } from './seal.js';
+// The count numbers below the highest a door still honours: those within
+// this span that it has not seen.
+export const SPAN = 64;
+export class Door {
+    key;
+    relations;
+    behind;
+    draw;
+    constructor(key, relations, behind, draw) {
+        this.key = key;
+        this.relations = relations;
+        this.behind = behind;
+        this.draw = draw;
+    }
+    // A new heir, held fresh, and its invitation. The lock is drawn at the
+    // first invitation that names an heir, before the heir's secret.
+    async invite() {
+        let lock = this.relations.lock();
+        if (!lock)
+            this.relations.setLock((lock = drawLock(this.draw)));
+        const heir = await SigningKey.draw(this.draw);
+        this.relations.set(heir.id, { state: 'fresh' });
+        return { heir: heir.id, invitation: { ward: this.key.pk, heir: heir.id, secret: hex(heir.secret), lock: hex(lock.ek) } };
+    }
+    // The door stops holding an heir. A fresh one leaves nothing, a spent one
+    // leaves the keys kept at removal.
+    remove(heir) {
+        const record = this.relations.get(heir);
+        if (record === undefined || record.state === 'kept')
+            return false;
+        if (record.state === 'fresh')
+            this.relations.delete(heir);
+        else
+            this.relations.set(heir, { state: 'kept', held: record.held, vouched: record.vouched, open: record.open, offered: record.offered });
+        return true;
+    }
+    async arrive(bytes) {
+        const stranger = async (n) => ({ bytes: await this.#silence(bytes), case: n, heard: false });
+        if (bytes.length > SIZE || bytes.length < HEAD)
+            return stranger(1);
+        const agreement = await this.key.open(bytes.subarray(0, HEAD));
+        const opened = agreement && (await openHead(bytes, agreement));
+        if (!opened)
+            return stranger(1);
+        const isZero = zero(opened.head);
+        const heir = hex(opened.head);
+        const record = isZero ? undefined : this.relations.get(heir);
+        const body = await this.#body(opened, record);
+        if (!body)
+            return stranger(1);
+        const read = readPayload(body.text);
+        if ('fault' in read)
+            return stranger(read.fault === 'not an object' ? 2 : 3);
+        const p = read.payload;
+        if (isZero ? p.to !== null : p.to !== heir)
+            return stranger(3);
+        if (isZero) {
+            if (!this.behind.zero)
+                return stranger(4);
+            if (!(await checkBody(unhex(p.by), body)))
+                return stranger(5);
+            const choice = await this.#choose(null, p);
+            return { bytes: await this.#sealed(opened, choice), case: 'object' in choice ? 12 : 13, heard: false };
+        }
+        if (record === undefined)
+            return stranger(6);
+        if (!admits(record, heir, p.by))
+            return stranger(7);
+        if (!(await checkBody(unhex(p.by), body)))
+            return stranger(8);
+        const reply = await replyKey(this.draw, opened.lid);
+        if (!reply)
+            return stranger(1);
+        const offered = await follow(body.edge, reply.agreement);
+        // Checked again, since another arrival may have moved the keys while
+        // this one was checking its signature.
+        const now = this.relations.get(heir);
+        if (now === undefined || !admits(now, heir, p.by) || !opensUnder(now, body.edge))
+            return stranger(7);
+        if (now.state === 'kept')
+            return this.#heard(reply, { quo: 'removed' }, 9);
+        if (now.state === 'fresh' && (p.next === null || p.next === heir))
+            return this.#heard(reply, { quo: 'unannounced' }, 10);
+        if (now.state === 'spent' && !honours(now, p.seq))
+            return this.#heard(reply, { quo: 'repeated' }, 11);
+        this.relations.set(heir, move(now, heir, p, hex(body.edge), hex(offered)));
+        const choice = await this.#choose(heir, p);
+        const kept = await this.relations.kept().catch(() => false);
+        return this.#heard(reply, kept ? choice : { silence: true }, kept && 'object' in choice ? 12 : 13);
+    }
+    async #heard(key, reply, n) {
+        return { bytes: await sealReply(key, await this.#signed(reply)), case: n, heard: true };
+    }
+    #signed(reply) {
+        return signBody(utf8(writeReply(reply)), this.key.signing);
+    }
+    async #choose(heir, p) {
+        try {
+            return await this.behind.answer(heir, p);
+        }
+        catch {
+            return { silence: true };
+        }
+    }
+    async #sealed(opened, reply) {
+        const key = await replyKey(this.draw, opened.lid);
+        return key ? sealReply(key, await this.#signed(reply)) : this.#silence(opened.lid);
+    }
+    // The body, opened under the edge keys the door takes for this head.
+    async #body(opened, record) {
+        const tries = [];
+        if (record?.state === 'fresh') {
+            const knock = splitKnock(opened.rest);
+            const lock = this.relations.lock();
+            const shared = knock && lock ? decapsulate(lock.dk, knock.ciphertext) : null;
+            if (!knock || !shared)
+                return null;
+            tries.push({ edge: await knockEdge(shared), sealed: knock.sealedBody });
+        }
+        else if (record === undefined)
+            tries.push({ edge: ZERO_EDGE, sealed: opened.rest });
+        else
+            for (const edge of [record.open, record.offered])
+                tries.push({ edge: unhex(edge), sealed: opened.rest });
+        for (const { edge, sealed } of tries) {
+            const plain = await openBody(opened, edge, sealed);
+            if (plain === null)
+                continue;
+            const body = splitBody(plain);
+            return body && { edge, ...body };
+        }
+        return null;
+    }
+    // A stranger's silence: sealed to the first thirty-two bytes that arrived
+    // when they take a seal, and otherwise to a lid nobody holds.
+    async #silence(arrived) {
+        const text = await this.#signed({ silence: true });
+        const candidates = [arrived.length >= HEAD ? arrived.subarray(0, HEAD) : null, this.draw(HEAD)];
+        for (const lid of candidates) {
+            const key = lid && (await replyKey(this.draw, lid));
+            if (key)
+                return sealReply(key, text);
+        }
+        return sealReply((await replyKey(this.draw, await x25519Public(this.draw(HEAD)))), text);
+    }
+}
+const admits = (record, heir, by) => (record.state === 'fresh' ? by === heir : by === record.held || by === record.vouched);
+const opensUnder = (record, edge) => record.state === 'fresh' || hex(edge) === record.open || hex(edge) === record.offered;
+const honours = (record, seq) => seq > record.highest || (seq > record.highest - SPAN && seq !== record.highest && !record.honoured.includes(seq));
+// The move tables: the keys and edge keys after a choice, and the count.
+const move = (record, heir, p, edge, offered) => {
+    const announced = p.next !== null && p.next !== heir && p.next !== p.by ? p.next : null;
+    if (record.state === 'fresh')
+        return { state: 'spent', held: announced, vouched: null, open: edge, offered, highest: p.seq, honoured: [] };
+    if (record.state !== 'spent')
+        return record;
+    if (p.seq < record.highest)
+        return { ...record, honoured: [...record.honoured, p.seq] };
+    const keys = p.by === record.held ? { held: record.held, vouched: announced ?? record.vouched, open: edge, offered } : { held: p.by, vouched: announced, open: edge, offered };
+    const honoured = [...record.honoured, record.highest].filter((n) => n > p.seq - SPAN);
+    return { state: 'spent', ...keys, highest: p.seq, honoured };
+};

package/dist/quo/index.d.ts

@@ -0,0 +1,8 @@
+export { Door, SPAN, type Behind, type Choice, type Judged } from './door.ts';
+export { readInvitation, type Invitation } from './invitation.ts';
+export { Ephemeral, SigningKey, WardKey, type Draw } from './keys.ts';
+export { readPayload, writePayload, type Payload } from './payload.ts';
+export { GONE, keptLock, lockOf, MemoryRelations, type HeirRecord, type KeptLock, type Relations } from './relations.ts';
+export { readReply, SILENCE, WORDS, writeReply, type Reply, type Word } from './reply.ts';
+export { SIZE } from './seal.ts';
+export { freshStanding, Standing, type Read, type Sent, type StandingState } from './standing.ts';

package/dist/quo/index.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+// Quo's wire: keys, the invitation, the payload, the reply, the boxes, the
+// door and the standing. It knows no being, no ward and no terrain.
+export { Door, SPAN } from './door.js';
+export { readInvitation } from './invitation.js';
+export { Ephemeral, SigningKey, WardKey } from './keys.js';
+export { readPayload, writePayload } from './payload.js';
+export { GONE, keptLock, lockOf, MemoryRelations } from './relations.js';
+export { readReply, SILENCE, WORDS, writeReply } from './reply.js';
+export { SIZE } from './seal.js';
+export { freshStanding, Standing } from './standing.js';

package/dist/quo/invitation.d.ts

@@ -0,0 +1,7 @@
+export type Invitation = {
+    readonly ward: string;
+    readonly heir: string;
+    readonly secret: string;
+    readonly lock: string;
+};
+export declare const readInvitation: (value: unknown) => Invitation | null;

package/dist/quo/invitation.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// The invitation: `{ ward, heir, secret, lock }`, a value with no route.
+import { EK, encapsulate, isHex, unhex } from '../crypto/index.js';
+// An invitation, or null for any other shape. A field beside the four is
+// ignored, and the lock is held to the modulus check.
+export const readInvitation = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const { ward, heir, secret, lock } = value;
+    if (!isHex(ward, 64) || !isHex(heir, 32) || !isHex(secret, 32) || !isHex(lock, EK))
+        return null;
+    if (encapsulate(unhex(lock), new Uint8Array(32)) === null)
+        return null;
+    return { ward, heir, secret, lock };
+};

package/dist/quo/keys.d.ts

@@ -0,0 +1,40 @@
+import { type Lock } from '../crypto/index.ts';
+export type Draw = (length: number) => Uint8Array;
+export declare const LABEL: {
+    readonly seal: Uint8Array<ArrayBufferLike>;
+    readonly edgeSeal: Uint8Array<ArrayBufferLike>;
+    readonly lock: Uint8Array<ArrayBufferLike>;
+    readonly edge: Uint8Array<ArrayBufferLike>;
+    readonly wardSign: Uint8Array<ArrayBufferLike>;
+    readonly wardSeal: Uint8Array<ArrayBufferLike>;
+};
+export declare class SigningKey {
+    readonly secret: Uint8Array;
+    readonly pk: Uint8Array;
+    private constructor();
+    static from(secret: Uint8Array): Promise<SigningKey>;
+    static draw(draw: Draw): Promise<SigningKey>;
+    get id(): string;
+}
+export declare class Ephemeral {
+    readonly secret: Uint8Array;
+    readonly pk: Uint8Array;
+    private constructor();
+    static from(secret: Uint8Array): Promise<Ephemeral>;
+    static draw(draw: Draw): Promise<Ephemeral>;
+    agree(pk: Uint8Array): Promise<Uint8Array | null>;
+}
+export declare class WardKey {
+    readonly signing: SigningKey;
+    readonly sealSecret: Uint8Array;
+    readonly padlock: Uint8Array;
+    private constructor();
+    static from(seed: Uint8Array | string): Promise<WardKey>;
+    get pk(): string;
+    open(lid: Uint8Array): Promise<Uint8Array | null>;
+}
+export declare const wardHalves: (pk: string) => {
+    signing: string;
+    padlock: string;
+};
+export declare const drawLock: (draw: Draw) => Lock;

package/dist/quo/keys.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// The keys of Quo: the ward key derived from a seed, and every other key
+// drawn. A draw is the caller's, so this layer names no source of bytes.
+import { agree, ed25519Public, hex, hkdf, lockFrom, sha256, utf8, x25519Public } from '../crypto/index.js';
+export const LABEL = {
+    seal: utf8('quo-seal'),
+    edgeSeal: utf8('quo-edge-seal'),
+    lock: utf8('quo-lock'),
+    edge: utf8('quo-edge'),
+    wardSign: utf8('quo-ward-sign'),
+    wardSeal: utf8('quo-ward-seal'),
+};
+// An Ed25519 pair: an heir, or a standing's own key.
+export class SigningKey {
+    secret;
+    pk;
+    constructor(secret, pk) {
+        this.secret = secret;
+        this.pk = pk;
+    }
+    static async from(secret) {
+        return new SigningKey(secret, await ed25519Public(secret));
+    }
+    static draw(draw) {
+        return SigningKey.from(draw(32));
+    }
+    get id() {
+        return hex(this.pk);
+    }
+}
+// An X25519 pair used for one box.
+export class Ephemeral {
+    secret;
+    pk;
+    constructor(secret, pk) {
+        this.secret = secret;
+        this.pk = pk;
+    }
+    static async from(secret) {
+        return new Ephemeral(secret, await x25519Public(secret));
+    }
+    static draw(draw) {
+        return Ephemeral.from(draw(32));
+    }
+    agree(pk) {
+        return agree(this.secret, pk);
+    }
+}
+// The ward key: a signing pair and a padlock, both from the seed.
+export class WardKey {
+    signing;
+    sealSecret;
+    padlock;
+    constructor(signing, sealSecret, padlock) {
+        this.signing = signing;
+        this.sealSecret = sealSecret;
+        this.padlock = padlock;
+    }
+    // Thirty-two bytes are the seed. Text, and bytes of any other length, are
+    // hashed to it first.
+    static async from(seed) {
+        const bytes = typeof seed === 'string' ? await sha256(utf8(seed)) : seed.length === 32 ? seed : await sha256(seed);
+        const sealSecret = await hkdf(bytes, LABEL.wardSeal, 32);
+        return new WardKey(await SigningKey.from(await hkdf(bytes, LABEL.wardSign, 32)), sealSecret, await x25519Public(sealSecret));
+    }
+    get pk() {
+        return hex(this.signing.pk) + hex(this.padlock);
+    }
+    open(lid) {
+        return agree(this.sealSecret, lid);
+    }
+}
+// A ward pk's two halves.
+export const wardHalves = (pk) => ({ signing: pk.slice(0, 64), padlock: pk.slice(64) });
+// A lock from sixty-four drawn bytes.
+export const drawLock = (draw) => {
+    const bytes = draw(64);
+    return lockFrom(bytes.subarray(0, 32), bytes.subarray(32));
+};

package/dist/quo/payload.d.ts

@@ -0,0 +1,15 @@
+export type Payload = {
+    readonly to: string | null;
+    readonly by: string;
+    readonly next: string | null;
+    readonly seq: number;
+    readonly method?: string;
+    readonly args?: string;
+};
+export declare const writePayload: (p: Payload) => string;
+export type PayloadRead = {
+    payload: Payload;
+} | {
+    fault: 'not an object' | 'not well formed';
+};
+export declare const readPayload: (bytes: Uint8Array) => PayloadRead;

package/dist/quo/payload.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// The payload: `{ to, by, next, seq, method?, args? }`. `args` is carried as
+// the text it was written in, since Quo reads nothing inside it.
+import { isCount, isHex, readObject } from '../crypto/index.js';
+const OWED = ['to', 'by', 'next', 'seq'];
+const ZERO = '0'.repeat(64);
+const isPk = (text) => isHex(text, 32) && text !== ZERO;
+// A pk written as a JSON string, or null written as null.
+const pkOrNull = (text, nullable) => {
+    if (nullable && text === 'null')
+        return null;
+    if (!/^"[0-9a-f]{64}"$/.test(text))
+        return undefined;
+    const pk = text.slice(1, -1);
+    return isPk(pk) ? pk : undefined;
+};
+export const writePayload = (p) => {
+    const parts = [`"to":${JSON.stringify(p.to)}`, `"by":"${p.by}"`, `"next":${JSON.stringify(p.next)}`, `"seq":${p.seq}`];
+    if (p.method !== undefined)
+        parts.push(`"method":${JSON.stringify(p.method)}`);
+    if (p.args !== undefined)
+        parts.push(`"args":${p.args}`);
+    return `{${parts.join(',')}}`;
+};
+// Cases 2 and 3 of the door, before the head is compared.
+export const readPayload = (bytes) => {
+    const fields = readObject(bytes);
+    if (fields === null)
+        return { fault: 'not an object' };
+    const bad = { fault: 'not well formed' };
+    if (!OWED.every((f) => fields.has(f)))
+        return bad;
+    const to = pkOrNull(fields.get('to'), true);
+    const by = pkOrNull(fields.get('by'), false);
+    const next = pkOrNull(fields.get('next'), true);
+    const seq = fields.get('seq');
+    if (to === undefined || !by || next === undefined || !isCount(seq))
+        return bad;
+    const method = fields.get('method');
+    if (method !== undefined && !method.startsWith('"'))
+        return bad;
+    const args = fields.get('args');
+    if (args !== undefined && !args.startsWith('{'))
+        return bad;
+    return {
+        payload: {
+            to,
+            by,
+            next,
+            seq: Number(seq),
+            ...(method === undefined ? {} : { method: JSON.parse(method) }),
+            ...(args === undefined ? {} : { args }),
+        },
+    };
+};

package/dist/quo/relations.d.ts

@@ -0,0 +1,40 @@
+import type { Lock } from '../crypto/index.ts';
+export type Keys = {
+    readonly held: string;
+    readonly vouched: string | null;
+    readonly open: string;
+    readonly offered: string;
+};
+export type HeirRecord = {
+    readonly state: 'fresh';
+} | ({
+    readonly state: 'spent';
+    readonly highest: number;
+    readonly honoured: readonly number[];
+} & Keys) | ({
+    readonly state: 'kept';
+} & Keys);
+export type KeptLock = {
+    readonly ek: string;
+    readonly dk: string;
+};
+export interface Relations {
+    lock(): Lock | undefined;
+    setLock(lock: Lock): void;
+    get(heir: string): HeirRecord | undefined;
+    set(heir: string, record: HeirRecord): void;
+    delete(heir: string): void;
+    kept(): Promise<boolean>;
+}
+export declare const lockOf: (kept: KeptLock | undefined) => Lock | undefined;
+export declare const keptLock: (lock: Lock) => KeptLock;
+export declare const GONE = 256;
+export declare class MemoryRelations implements Relations {
+    #private;
+    lock(): Lock | undefined;
+    setLock(lock: Lock): void;
+    get(heir: string): HeirRecord | undefined;
+    set(heir: string, record: HeirRecord): void;
+    delete(heir: string): void;
+    kept(): Promise<boolean>;
+}

package/dist/quo/relations.js

@@ -0,0 +1,33 @@
+import { hex, unhex } from '../crypto/index.js';
+export const lockOf = (kept) => (kept ? { ek: unhex(kept.ek), dk: unhex(kept.dk) } : undefined);
+export const keptLock = (lock) => ({ ek: hex(lock.ek), dk: hex(lock.dk) });
+// A bound on the kept records of removed relations, oldest out.
+export const GONE = 256;
+export class MemoryRelations {
+    #lock;
+    #heirs = new Map();
+    #gone = [];
+    lock() {
+        return lockOf(this.#lock);
+    }
+    setLock(lock) {
+        this.#lock = keptLock(lock);
+    }
+    get(heir) {
+        return this.#heirs.get(heir);
+    }
+    set(heir, record) {
+        this.#heirs.set(heir, record);
+        if (record.state !== 'kept')
+            return;
+        this.#gone.push(heir);
+        while (this.#gone.length > GONE)
+            this.#heirs.delete(this.#gone.shift());
+    }
+    delete(heir) {
+        this.#heirs.delete(heir);
+    }
+    kept() {
+        return Promise.resolve(true);
+    }
+}

package/dist/quo/reply.d.ts

@@ -0,0 +1,13 @@
+export declare const WORDS: readonly ['removed', 'unannounced', 'repeated'];
+export type Word = (typeof WORDS)[number];
+export type Reply = {
+    readonly object: string;
+    readonly seen: string | null;
+} | {
+    readonly silence: true;
+} | {
+    readonly quo: Word;
+};
+export declare const SILENCE = "{\"silence\":true}";
+export declare const writeReply: (reply: Reply) => string;
+export declare const readReply: (bytes: Uint8Array) => Reply | null;

package/dist/quo/reply.js

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+// The reply text: `{ object, seen }`, `{ silence: true }` or `{ quo: word }`.
+// `object` is carried as the text it was written in.
+import { readObject } from '../crypto/index.js';
+export const WORDS = ['removed', 'unannounced', 'repeated'];
+export const SILENCE = '{"silence":true}';
+export const writeReply = (reply) => {
+    if ('silence' in reply)
+        return SILENCE;
+    if ('quo' in reply)
+        return `{"quo":"${reply.quo}"}`;
+    return `{"object":${reply.object},"seen":${JSON.stringify(reply.seen)}}`;
+};
+const exactly = (fields, ...keys) => fields.size === keys.length && keys.every((k) => fields.has(k));
+// A reply text of one of the three shapes, or null for anything else, which
+// the reader takes as silence.
+export const readReply = (bytes) => {
+    const fields = readObject(bytes);
+    if (fields === null)
+        return null;
+    if (exactly(fields, 'silence'))
+        return fields.get('silence') === 'true' ? { silence: true } : null;
+    if (exactly(fields, 'quo')) {
+        const text = fields.get('quo');
+        const word = text.startsWith('"') ? JSON.parse(text) : null;
+        return WORDS.find((w) => w === word) ? { quo: word } : null;
+    }
+    if (exactly(fields, 'object', 'seen')) {
+        const seen = fields.get('seen');
+        if (seen === 'null')
+            return { object: fields.get('object'), seen: null };
+        return seen.startsWith('"') ? { object: fields.get('object'), seen: JSON.parse(seen) } : null;
+    }
+    return null;
+};

package/dist/quo/seal.d.ts

@@ -0,0 +1,42 @@
+import { Ephemeral, type Draw, type SigningKey } from './keys.ts';
+export declare const SIZE = 1048576;
+export declare const HEAD = 32;
+export declare const SIGNATURE = 64;
+export declare const SEALED_HEAD: number;
+export declare const ZERO_EDGE: Uint8Array<ArrayBuffer>;
+export declare const ZERO_HEAD: Uint8Array<ArrayBuffer>;
+export declare const knockEdge: (shared: Uint8Array) => Promise<Uint8Array>;
+export declare const follow: (edge: Uint8Array, agreement: Uint8Array) => Promise<Uint8Array>;
+export declare const signBody: (text: Uint8Array, key: SigningKey) => Promise<Uint8Array>;
+export declare const splitBody: (body: Uint8Array) => {
+    text: Uint8Array;
+    signature: Uint8Array;
+} | null;
+export declare const checkBody: (pk: Uint8Array, body: {
+    text: Uint8Array;
+    signature: Uint8Array;
+}) => Promise<boolean>;
+export declare const sealAsk: (lid: Ephemeral, padlock: Uint8Array, head: Uint8Array, edge: Uint8Array, body: Uint8Array, ciphertext?: Uint8Array) => Promise<Uint8Array | null>;
+export type OpenedHead = {
+    lid: Uint8Array;
+    agreement: Uint8Array;
+    head: Uint8Array;
+    rest: Uint8Array;
+};
+export declare const openHead: (bytes: Uint8Array, agreement: Uint8Array) => Promise<OpenedHead | null>;
+export declare const splitKnock: (rest: Uint8Array) => {
+    ciphertext: Uint8Array;
+    sealedBody: Uint8Array;
+} | null;
+export declare const openBody: (opened: OpenedHead, edge: Uint8Array, sealedBody: Uint8Array) => Promise<Uint8Array | null>;
+export type SealedReply = {
+    bytes: Uint8Array;
+    agreement: Uint8Array;
+};
+export type ReplyKey = {
+    ephemeral: Ephemeral;
+    agreement: Uint8Array;
+};
+export declare const replyKey: (draw: Draw, lid: Uint8Array) => Promise<ReplyKey | null>;
+export declare const sealReply: (key: ReplyKey, body: Uint8Array) => Promise<Uint8Array>;
+export declare const openReply: (bytes: Uint8Array, lid: Ephemeral) => Promise<SealedReply | null>;

package/dist/quo/seal.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// The three boxes and the keys between them.
+//
+//   ask box    lid (32) || AES( head ) || AES( body )
+//   knock box  lid (32) || AES( head ) || ML-KEM ciphertext (1088) || AES( body )
+//   reply box  ephemeral pk (32) || AES( body )
+//   body       JSON text || signature (64)
+//
+// The head of an ask and the body of a reply are sealed under `quo-seal`
+// over the agreement. The body of an ask is sealed under `quo-edge-seal`
+// over the agreement and then the edge key. Every ciphertext's additional
+// data is its own box's ephemeral pk.
+import { CIPHERTEXT, concat, decrypt, encrypt, hkdf, sign, TAG, verify } from '../crypto/index.js';
+import { Ephemeral, LABEL } from './keys.js';
+export const SIZE = 1_048_576;
+export const HEAD = 32;
+export const SIGNATURE = 64;
+export const SEALED_HEAD = HEAD + TAG;
+export const ZERO_EDGE = new Uint8Array(32);
+export const ZERO_HEAD = new Uint8Array(HEAD);
+const cipher = async (label, ...material) => {
+    const out = await hkdf(concat(...material), label, 44);
+    return { key: out.subarray(0, 32), nonce: out.subarray(32) };
+};
+const seal = async (label, material, lid, plaintext) => {
+    const { key, nonce } = await cipher(label, ...material);
+    return encrypt(key, nonce, lid, plaintext);
+};
+const open = async (label, material, lid, ciphertext) => {
+    const { key, nonce } = await cipher(label, ...material);
+    return decrypt(key, nonce, lid, ciphertext);
+};
+// A knock's edge key, from the shared secret the lock decapsulates.
+export const knockEdge = (shared) => hkdf(shared, LABEL.lock, 32);
+// The edge key that follows `edge` after a reply of this agreement.
+export const follow = (edge, agreement) => hkdf(concat(edge, agreement), LABEL.edge, 32);
+export const signBody = async (text, key) => concat(text, await sign(key.secret, text));
+// The text and signature of a body, or null for a body of sixty-four bytes
+// or fewer.
+export const splitBody = (body) => body.length <= SIGNATURE ? null : { text: body.subarray(0, -SIGNATURE), signature: body.subarray(-SIGNATURE) };
+export const checkBody = (pk, body) => verify(pk, body.text, body.signature);
+// An ask box sealed under `lid` to a padlock, or null for a padlock that
+// takes no seal. `ciphertext` makes it a knock box.
+export const sealAsk = async (lid, padlock, head, edge, body, ciphertext) => {
+    const agreement = await lid.agree(padlock);
+    if (agreement === null)
+        return null;
+    const sealedHead = await seal(LABEL.seal, [agreement], lid.pk, head);
+    const sealedBody = await seal(LABEL.edgeSeal, [agreement, edge], lid.pk, body);
+    return concat(lid.pk, sealedHead, ciphertext ?? new Uint8Array(0), sealedBody);
+};
+export const openHead = async (bytes, agreement) => {
+    if (bytes.length < HEAD + SEALED_HEAD)
+        return null;
+    const lid = bytes.subarray(0, HEAD);
+    const head = await open(LABEL.seal, [agreement], lid, bytes.subarray(HEAD, HEAD + SEALED_HEAD));
+    return head === null ? null : { lid, agreement, head, rest: bytes.subarray(HEAD + SEALED_HEAD) };
+};
+// A knock's rest split into its ciphertext and sealed body.
+export const splitKnock = (rest) => rest.length < CIPHERTEXT ? null : { ciphertext: rest.subarray(0, CIPHERTEXT), sealedBody: rest.subarray(CIPHERTEXT) };
+export const openBody = (opened, edge, sealedBody) => open(LABEL.edgeSeal, [opened.agreement, edge], opened.lid, sealedBody);
+export const replyKey = async (draw, lid) => {
+    const ephemeral = await Ephemeral.draw(draw);
+    const agreement = await ephemeral.agree(lid);
+    return agreement === null ? null : { ephemeral, agreement };
+};
+export const sealReply = async (key, body) => concat(key.ephemeral.pk, await seal(LABEL.seal, [key.agreement], key.ephemeral.pk, body));
+// A reply's body and agreement, opened with the lid's secret, or null.
+export const openReply = async (bytes, lid) => {
+    if (bytes.length > SIZE || bytes.length < HEAD + TAG)
+        return null;
+    const pk = bytes.subarray(0, HEAD);
+    const agreement = await lid.agree(pk);
+    if (agreement === null)
+        return null;
+    const body = await open(LABEL.seal, [agreement], pk, bytes.subarray(HEAD));
+    return body === null ? null : { bytes: body, agreement };
+};