@joe-broadhead/messaging 0.0.0-stage → 0.7.0

package/dist/lib/modules/core/envelope.js

@@ -0,0 +1,320 @@
+import { createCipheriv, createDecipheriv, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes } from "node:crypto";
+import { b64u, utf8 } from "./b64u.js";
+import { asMessagingError, parseWith } from "./check.js";
+import { canonicalize } from "./jcs.js";
+import { privateKeyFromRaw, publicKeyFromRaw, rawPublicKey } from "./keys.js";
+import { DOMAIN, LIMITS, PROTOCOL, Ulid } from "./schema/common.js";
+import { Envelope, EnvelopeType, PAYLOAD_BY_TYPE, SEAL_ALG, } from "./schema/envelope.js";
+import { MessagingError } from "./schema/errors.js";
+import { signingInput, sign, verifyInput } from "./sign.js";
+import { ulid } from "./ulid.js";
+import { parseWire } from "./wire.js";
+const Header = Envelope.omit({ body: true, sig: true });
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+/** Builds, seals (spec §5) and signs an envelope. Presence is signed but not sealed. */
+export function sealEnvelope(args) {
+    return seal(args, fresh);
+}
+/**
+ * `sealEnvelope` with caller-chosen ephemeral key and nonce, for test vectors and tests only; exported from
+ * `@messaging/core/testing`. Reusing an ephemeral key and nonce for real traffic breaks confidentiality.
+ */
+export function sealEnvelopeWith(args, randomness) {
+    return seal(args, fixed(randomness));
+}
+/**
+ * Seals arbitrary `plaintext` bytes as the body of a sealed type, with a valid header and signature but no
+ * payload validation or canonicalization, so tests can build envelopes a conforming sender never makes.
+ * Tests only; exported from `@messaging/core/testing`.
+ */
+export function sealPlaintext(args, plaintext, randomness) {
+    const type = parseWith(EnvelopeType, args.type, "envelope type");
+    if (type === "presence")
+        throw new MessagingError("invalid_request", "presence is not sealed");
+    return sealBytes(args, type, args.class ?? classOf(args.from, args.to), plaintext, randomness === undefined ? fresh : fixed(randomness));
+}
+function fresh() {
+    return { ephemeral: generateKeyPairSync("x25519").privateKey, nonce: randomBytes(NONCE_BYTES) };
+}
+function fixed(randomness) {
+    return () => {
+        if (randomness.nonce.length !== NONCE_BYTES)
+            throw new MessagingError("invalid_request", "nonce must be 12 bytes");
+        return { ephemeral: privateKeyFromRaw("x25519", randomness.ephemeral), nonce: randomness.nonce };
+    };
+}
+function seal(args, randomness) {
+    const type = parseWith(EnvelopeType, args.type, "envelope type");
+    const payload = parseWith(PAYLOAD_BY_TYPE[type], args.payload, `${type} payload`);
+    const plaintext = utf8(canonicalize(payload));
+    if (plaintext.length > LIMITS.plaintextBytes)
+        throw new MessagingError("too_large", `payload exceeds ${LIMITS.plaintextBytes} bytes`);
+    // Spec §5, "Class": a message request is the one class its payload chooses.
+    const klass = type === "message" && payload.conv?.kind === "request" ? "request" : classOf(args.from, args.to);
+    assertMeaning(type, args.from, args.to, klass, payload);
+    if (type !== "presence")
+        return sealBytes(args, type, klass, plaintext, randomness);
+    if (args.recipientEnc !== undefined)
+        throw new MessagingError("invalid_request", "presence is not sealed");
+    const header = parseWith(Header, { ...base(args, type, undefined), enc: "none" }, "envelope header");
+    assertShape(header);
+    return signed(args.identity, { ...header, body: payload });
+}
+function base(args, type, klass) {
+    if (args.from?.device !== args.identity.machine)
+        throw new MessagingError("invalid_request", "from.device must be the signing identity");
+    const ttl = args.ttlMs ?? LIMITS.ttlMs;
+    if (!Number.isSafeInteger(ttl) || ttl <= 0 || ttl > LIMITS.ttlMs)
+        throw new MessagingError("invalid_request", "ttlMs out of range");
+    const now = args.now ?? Date.now();
+    return {
+        v: PROTOCOL,
+        id: args.id ?? ulid(now),
+        realm: args.realm,
+        type,
+        from: args.from,
+        to: args.to,
+        ts: now,
+        exp: now + ttl,
+        anchor: args.anchor?.kind === "epoch" ? { kind: "epoch", size: args.anchor.size, root: args.anchor.root } : { kind: args.anchor?.kind, seq: args.anchor?.seq, hash: args.anchor?.hash },
+        ...(klass === undefined ? {} : { class: klass }),
+        ...(args.replyTo === undefined ? {} : { replyTo: args.replyTo }),
+    };
+}
+/** Spec §5, "Class": `self` between two devices of one person, `contact` otherwise (a message request chooses `request`). */
+function classOf(from, to) {
+    return to !== undefined && "person" in to && to.person === from?.person ? "self" : "contact";
+}
+function sealBytes(args, type, klass, plaintext, randomness) {
+    const head = base(args, type, klass);
+    const recipient = recipientKey(args.recipientEnc);
+    const { ephemeral, nonce } = randomness();
+    const epk = rawPublicKey(ephemeral);
+    const header = parseWith(Header, { ...head, enc: SEAL_ALG, epk, nonce: b64u.encode(nonce) }, "envelope header");
+    assertShape(header);
+    let shared;
+    try {
+        shared = diffieHellman({ privateKey: ephemeral, publicKey: recipient.key });
+    }
+    catch (cause) {
+        throw new MessagingError("invalid_request", "recipientEnc is not a usable X25519 key", { cause });
+    }
+    const cipher = createCipheriv("aes-256-gcm", sealKey(shared, b64u.decode(epk), recipient.raw), nonce, { authTagLength: TAG_BYTES });
+    cipher.setAAD(utf8(canonicalize(header)));
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+    return signed(args.identity, { ...header, body: b64u.encode(ciphertext) });
+}
+function recipientKey(enc) {
+    if (enc === undefined)
+        throw new MessagingError("invalid_request", "recipientEnc is required to seal");
+    try {
+        return { key: publicKeyFromRaw("x25519", enc), raw: b64u.decode(enc) };
+    }
+    catch (cause) {
+        throw new MessagingError("invalid_request", "recipientEnc is not an X25519 public key", { cause });
+    }
+}
+function signed(identity, unsigned) {
+    return { ...unsigned, sig: sign(identity, DOMAIN.envelope, unsigned) };
+}
+/**
+ * Receiver checks, spec §5 steps 1–6. Membership is checked against the locally verified realm and the
+ * signature over the raw JSON value, so unknown fields from newer peers stay covered. Returns the raw
+ * envelope; deduplication and recipient policy are the caller's. Throws only MessagingError.
+ */
+export function verifyEnvelope(raw, ctx) {
+    try {
+        return check(raw, ctx);
+    }
+    catch (error) {
+        throw asMessagingError(error, "envelope");
+    }
+}
+function check(raw, ctx) {
+    if (!Number.isSafeInteger(ctx.now))
+        throw new MessagingError("invalid_request", "now must be an integer");
+    parseWith(Envelope, raw, "envelope");
+    const env = raw;
+    assertShape(env);
+    if (env.type === "presence" ? !isPlainObject(env.body) : typeof env.body !== "string") {
+        throw new MessagingError("invalid_request", "envelope body does not match its encoding");
+    }
+    const { sig, ...unsigned } = env;
+    // The signed bytes. Computing them here also requires I-JSON within LIMITS.jsonDepth (step 1).
+    const input = signingInput(DOMAIN.envelope, unsigned);
+    if (env.realm !== ctx.realm.realm)
+        throw new MessagingError("not_member", "envelope is for another realm");
+    if (env.anchor.kind !== ctx.realm.anchor().kind)
+        throw new MessagingError("invalid_request", "envelope anchor is of another realm kind");
+    if (env.ts > env.exp)
+        throw new MessagingError("expired", "envelope ts is after its exp");
+    if (env.ts > ctx.now + LIMITS.clockSkewMs)
+        throw new MessagingError("expired", "envelope timestamp is in the future");
+    if (env.exp <= ctx.now)
+        throw new MessagingError("expired", "envelope has expired");
+    if (env.exp - env.ts > LIMITS.ttlMs)
+        throw new MessagingError("expired", "envelope TTL exceeds the maximum");
+    // Step 4: a roster realm calls the sender not a member; a directory realm, an unknown device (spec §5).
+    const unknown = ctx.realm.anchor().kind === "epoch" ? "unknown_device" : "not_member";
+    const sender = ctx.realm.device(env.from.device);
+    if (!sender)
+        throw new MessagingError(unknown, "sender is not a current device of the realm");
+    if (sender.person !== env.from.person)
+        throw new MessagingError(unknown, "sender person does not match the realm");
+    if (!verifyInput(env.from.device, input, sig))
+        throw new MessagingError("bad_signature", "envelope signature is invalid");
+    if (ctx.self !== undefined && "device" in env.to) {
+        if (env.to.device !== ctx.self)
+            throw new MessagingError("invalid_request", "envelope is addressed to another device");
+        if (env.to.person !== ctx.realm.device(ctx.self)?.person)
+            throw new MessagingError("invalid_request", "envelope is addressed to another person");
+    }
+    return { env, sender };
+}
+/**
+ * Decrypts (or, for presence, reads) the body and validates it against `PAYLOAD_BY_TYPE[type]`.
+ * A seal failure is `bad_signature`; an oversized body is `too_large`; a body that decrypts but is not
+ * UTF-8 I-JSON (`parseWire`, then `canonicalize`) or not a valid payload is `invalid_request`, so every
+ * payload returned canonicalizes. Throws only MessagingError, and never chains the plaintext as a cause.
+ */
+export function openEnvelope(env, identity) {
+    try {
+        return open(env, identity);
+    }
+    catch (error) {
+        throw asMessagingError(error, "envelope");
+    }
+}
+function open(env, identity) {
+    const type = parseWith(EnvelopeType, env.type, "envelope type");
+    assertShape(env);
+    const schema = PAYLOAD_BY_TYPE[type];
+    if (type === "presence") {
+        if (utf8(canonicalize(env.body)).length > LIMITS.presenceBytes)
+            throw new MessagingError("too_large", "presence body is too large");
+        return parseWith(schema, env.body, "presence payload");
+    }
+    const plaintext = decrypt(env, identity);
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(plaintext);
+    }
+    catch {
+        throw new MessagingError("invalid_request", "envelope body is not UTF-8");
+    }
+    const value = parseWire(text, { maxBytes: LIMITS.plaintextBytes });
+    // parseWire rejects duplicate names, lone surrogates and deep nesting; this adds the I-JSON number rules.
+    canonicalize(value);
+    const payload = parseWith(schema, value, `${type} payload`);
+    assertMeaning(type, env.from, env.to, env.class, payload);
+    return payload;
+}
+/**
+ * Spec §5, "Meaning": a `message` to an agent is mail or a task request, in no other conversation; one to a device
+ * with no agent is a chat line (a DM with no `conv`, or a channel change or post), a sync between one person's own
+ * devices, a message request or a contact card: kind `message`, outside any task, with a ULID
+ * `messageId` and, when set, a ULID `contextId`. A `self` sync goes only between two devices of one person; a card
+ * only between two persons, from the person (no agent); a message request is exactly the envelope of class
+ * `request`.
+ */
+function assertMeaning(type, from, to, klass, payload) {
+    if (type !== "message" || to === undefined || !("device" in to))
+        return;
+    const p = payload;
+    if ((klass === "request") !== (p.conv?.kind === "request"))
+        throw new MessagingError("invalid_request", "a message request is exactly an envelope of class request");
+    if (to.agent !== undefined) {
+        if (p.conv !== undefined)
+            throw new MessagingError("invalid_request", "mail to an agent has no conv");
+        return;
+    }
+    if (p.conv?.kind === "self" && from?.person !== to.person)
+        throw new MessagingError("invalid_request", "a self sync goes between devices of one person");
+    if (p.conv?.kind === "card" && (from?.person === to.person || from?.agent !== undefined))
+        throw new MessagingError("invalid_request", "a card goes from a person to another person");
+    const line = p.kind === "message" &&
+        p.message.taskId === undefined &&
+        Ulid.safeParse(p.message.messageId).success &&
+        (p.message.contextId === undefined || Ulid.safeParse(p.message.contextId).success);
+    if (!line)
+        throw new MessagingError("invalid_request", "a chat line is kind message, outside any task, with ULID messageId and contextId");
+}
+function decrypt(env, identity) {
+    let data;
+    try {
+        data = b64u.decode(env.body);
+    }
+    catch (cause) {
+        throw new MessagingError("bad_signature", "envelope seal failed", { cause });
+    }
+    if (data.length - TAG_BYTES > LIMITS.plaintextBytes)
+        throw new MessagingError("too_large", "envelope body is too large");
+    try {
+        const epk = b64u.decode(env.epk ?? "");
+        const nonce = b64u.decode(env.nonce ?? "");
+        if (nonce.length !== NONCE_BYTES || data.length < TAG_BYTES)
+            throw new Error("bad seal lengths");
+        const shared = diffieHellman({ privateKey: identity.encKey, publicKey: publicKeyFromRaw("x25519", env.epk ?? "") });
+        const { body: _body, sig: _sig, ...header } = env;
+        const decipher = createDecipheriv("aes-256-gcm", sealKey(shared, epk, b64u.decode(identity.enc)), nonce, { authTagLength: TAG_BYTES });
+        decipher.setAAD(utf8(canonicalize(header)));
+        decipher.setAuthTag(data.subarray(data.length - TAG_BYTES));
+        return Buffer.concat([decipher.update(data.subarray(0, data.length - TAG_BYTES)), decipher.final()]);
+    }
+    catch (cause) {
+        throw new MessagingError("bad_signature", "envelope seal failed", { cause });
+    }
+}
+function sealKey(shared, epk, recipientEnc) {
+    return Buffer.from(hkdfSync("sha256", shared, Buffer.concat([epk, recipientEnc]), DOMAIN.seal, 32));
+}
+/** Type, encoding and addressing must agree: presence is plain and team-wide; every other type is sealed to a device. */
+function assertShape(env) {
+    const problem = shapeProblem(env);
+    if (problem)
+        throw new MessagingError("invalid_request", problem);
+}
+function shapeProblem(env) {
+    if (env.type === "presence") {
+        if (env.enc !== "none")
+            return "presence must not be sealed";
+        if (!("team" in env.to) || "device" in env.to)
+            return "presence must be addressed to the team";
+        if (env.epk !== undefined || env.nonce !== undefined)
+            return "a plain envelope has no epk or nonce";
+        if (env.class !== undefined)
+            return "presence has no class";
+        return undefined;
+    }
+    if (env.enc !== SEAL_ALG)
+        return `${env.type} must be sealed`;
+    // A task update names the task's request (spec §6.2).
+    if ((env.type === "task.status" || env.type === "task.artifact") && env.replyTo === undefined)
+        return `${env.type} needs replyTo`;
+    if (!("device" in env.to) || "team" in env.to)
+        return `${env.type} must be addressed to a device`;
+    if (env.epk === undefined || env.nonce === undefined)
+        return "a sealed envelope needs epk and nonce";
+    // Spec §5, "Class": the header says whether the two ends are one person.
+    if (env.class === undefined)
+        return "a sealed envelope needs class";
+    // Spec §6.9, "Message requests": a person's line to another person, with no agent at either end and no reply.
+    if (env.class === "request") {
+        if (env.type !== "message")
+            return "only a message is of class request";
+        if (classOf(env.from, env.to) !== "contact")
+            return "a message request goes to another person";
+        if (env.from.agent !== undefined || ("agent" in env.to && env.to.agent !== undefined))
+            return "a message request goes from a person to a person";
+        if (env.replyTo !== undefined)
+            return "a message request answers nothing";
+        return undefined;
+    }
+    if (env.class !== classOf(env.from, env.to))
+        return `class ${env.class} does not match the ends`;
+    return undefined;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/lib/modules/core/hash.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+/** SHA-256, base64url. Strings are hashed as UTF-8. */
+export function sha256(data) {
+    return createHash("sha256").update(data).digest("base64url");
+}

package/dist/lib/modules/core/head.js

@@ -0,0 +1,27 @@
+import { DOMAIN } from "./schema/common.js";
+import { Envelope } from "./schema/envelope.js";
+import { verify } from "./sign.js";
+export function headRelation(roster, head) {
+    return roster.relate({ kind: "roster", seq: head.seq, hash: head.hash });
+}
+/** The anchor a roster realm's envelopes carry: the roster's head (spec §5). */
+export function rosterAnchor(roster) {
+    return roster.anchor();
+}
+/**
+ * The roster head `raw` commits to, if `raw` is an envelope of `realm` (schema) whose signature over the
+ * raw JSON verifies under `from.device`. Membership and the time window are not checked: a receiver
+ * uses this to bring its roster up to the head before it checks membership (a new joiner is not in a
+ * stale roster), and to check stored evidence. Never throws; anything else is undefined.
+ */
+export function signedHead(raw, realm) {
+    if (!Envelope.safeParse(raw).success)
+        return undefined;
+    const env = raw;
+    if (env.realm !== realm || env.anchor.kind !== "roster")
+        return undefined;
+    const { sig, ...unsigned } = env;
+    if (!verify(env.from.device, DOMAIN.envelope, unsigned, sig))
+        return undefined;
+    return { head: { seq: env.anchor.seq, hash: env.anchor.hash }, machine: env.from.device, person: env.from.person, id: env.id };
+}

package/dist/lib/modules/core/identity.js

@@ -0,0 +1,71 @@
+import { generateKeyPairSync } from "node:crypto";
+import { z } from "../vendor/zod/index.js";
+import { b64u } from "./b64u.js";
+import { parseWith } from "./check.js";
+import { isPrivateKey, privateKeyFromRaw, rawPrivateKey, rawPublicKey } from "./keys.js";
+import { EncKey, MachineId, PROTOCOL } from "./schema/common.js";
+import { MessagingError } from "./schema/errors.js";
+const PrivateKey32 = z.string().regex(/^[A-Za-z0-9_-]{43}$/, "32 bytes, base64url without padding");
+/** `$MESSAGING_HOME/identity.json`. `signingKey` and `encKey` are the private JWK `d` values. */
+export const IdentityFile = z.object({
+    v: z.literal(PROTOCOL),
+    machine: MachineId,
+    enc: EncKey,
+    signingKey: PrivateKey32,
+    encKey: PrivateKey32,
+});
+/**
+ * A machine identity: an Ed25519 signing key and an X25519 encryption key. The public ids are
+ * derived from the private keys, so they always match. The private keys are held in private
+ * fields and never appear in `JSON.stringify`, `String()` or `util.inspect` output.
+ */
+export class Identity {
+    machine;
+    enc;
+    #signingKey;
+    #encKey;
+    constructor(signingKey, encKey) {
+        if (!isPrivateKey(signingKey, "ed25519"))
+            throw new MessagingError("invalid_request", "signing key must be an Ed25519 private key");
+        if (!isPrivateKey(encKey, "x25519"))
+            throw new MessagingError("invalid_request", "encryption key must be an X25519 private key");
+        this.#signingKey = signingKey;
+        this.#encKey = encKey;
+        this.machine = rawPublicKey(signingKey);
+        this.enc = rawPublicKey(encKey);
+    }
+    get signingKey() {
+        return this.#signingKey;
+    }
+    get encKey() {
+        return this.#encKey;
+    }
+    toJSON() {
+        return { machine: this.machine, enc: this.enc };
+    }
+    toString() {
+        return `Identity(${this.machine})`;
+    }
+}
+export function generateIdentity() {
+    return new Identity(generateKeyPairSync("ed25519").privateKey, generateKeyPairSync("x25519").privateKey);
+}
+/** The identity file contents. This is the only API that returns private key material. */
+export function exportIdentity(identity) {
+    return {
+        v: PROTOCOL,
+        machine: identity.machine,
+        enc: identity.enc,
+        signingKey: rawPrivateKey(identity.signingKey),
+        encKey: rawPrivateKey(identity.encKey),
+    };
+}
+/** Validates an identity file and checks that its public keys belong to its private keys. */
+export function importIdentity(file) {
+    const parsed = parseWith(IdentityFile, file, "identity file");
+    const identity = new Identity(privateKeyFromRaw("ed25519", b64u.decode(parsed.signingKey)), privateKeyFromRaw("x25519", b64u.decode(parsed.encKey)));
+    if (identity.machine !== parsed.machine || identity.enc !== parsed.enc) {
+        throw new MessagingError("invalid_request", "identity public keys do not match its private keys");
+    }
+    return identity;
+}

package/dist/lib/modules/core/index.js

@@ -0,0 +1,44 @@
+// Wire contracts (frozen; change only with a spec update and new test vectors).
+export * from "./schema/index.js";
+// Protocol logic; see docs/spec/messaging-v1.md §9.
+export { b64u } from "./b64u.js";
+export { VERSION } from "./version.js";
+export { canonicalize } from "./jcs.js";
+export { parseWire } from "./wire.js";
+export { sha256 } from "./hash.js";
+export { ulid } from "./ulid.js";
+export { Identity, IdentityFile, generateIdentity, exportIdentity, importIdentity } from "./identity.js";
+export { sign, verify } from "./sign.js";
+// Fixed-randomness and raw sealing for tests live in `@messaging/core/testing`.
+export { sealEnvelope, verifyEnvelope, openEnvelope } from "./envelope.js";
+export { headRelation, rosterAnchor, signedHead } from "./head.js";
+export { Roster, entryHash, createGenesis, createEntry, createInvite, decodeTicket, createRedeem, relayAuthPayload, inviteJoinPayload, inviteJoinProof, } from "./roster.js";
+// A daemon under a Jelly host (spec §8.11): action grants and session tickets.
+export { ACT_GRANT_MAX_S, ACTION_CLASSES, HOST_GRANT_MAX_S, JELLY_HOST_SKEW_S, SESSION_TICKET_MAX_S, actionClass, grantInput, parseActKey, readWakeTicket, verifyActGrant, verifySessionTicket, } from "./jelly-host.js";
+// Hosted realms: the key directory's data structures and verifiers (spec §15).
+export { personId } from "./directory/person.js";
+export { DirectoryRealmConfig, directoryRealmId } from "./directory/realm.js";
+export { emailOrg, hostedHandle } from "./directory/handle.js";
+export { JELLY_HISTORY_TTL_MS, JELLY_IAT_LEEWAY_S, JELLY_JWKS_TTL_MS, JELLY_MAX_LIFETIME_S, JELLY_REFETCH_MIN_MS, JELLY_REVOCATION_CHECK_MS, JellyKeyring, cnfJwk, decodeJellyToken, isBindableKey, jellyKeyCovers, jellyMintRefusal, verifyJellyToken, } from "./directory/jelly-token.js";
+export { DeviceLog, logEntryHash, signLogEntry, } from "./directory/device-log.js";
+export { DEVICE_GRANT_TYPE, JELLY_ANSWER_BYTES, LOGIN_INTERVAL_MAX_S, LOGIN_SLOW_DOWN_S, deviceCodeForm, devicePollForm, jellyKeyFingerprint, jellyKeyThumbprint, readDeviceCodeAnswer, readDevicePoll, readDeviceSignIn, } from "./directory/jelly-device.js";
+export { LINK_PREFIX, createLinkRequest, decodeLink, encodeLink, linkSas, verifyLinkRequest, verifyLinkSignature } from "./directory/link.js";
+export { createKeysStatement, keysStatementHash, verifyKeysStatement } from "./directory/keys-statement.js";
+export { adoptSth, epochAnchor, epochLeafHash, signKeyRotation, signSth, verifyEpochProof, verifySthSignature, } from "./directory/epoch.js";
+export { checkPersonSuccession, DirectoryInconsistency, verifyPersonHead, verifyPersonView, } from "./directory/person-view.js";
+export { MerkleLog, merkleLeafHash, verifyConsistency, verifyInclusion } from "./directory/merkle-log.js";
+export { MAP_DEPTH, SparseMerkleTree, TOMBSTONE, emptyMapHash, mapKey, mapRootFromProof, mapValue, verifyMapProof } from "./directory/smt.js";
+export { parseAddress, formatAddress } from "./address.js";
+export { decodeAdmitCard, decodeTeamCard, encodeAdmitCard, encodeTeamCard, } from "./cards.js";
+export { decide, effectivePolicy, grantSubjectKey, levelsOf, preferGrant, resignGrant, restrictingLevels, signConsentGrant, verifyConsentGrant, wideningLevels, } from "./consent.js";
+export { cardCan, signContactCard, verifyContactCard } from "./contact-card.js";
+export { createGrant, verifyChain } from "./delegation.js";
+export { canTransition, isTerminal, isInterrupted } from "./task.js";
+export { TERMINAL_STATES } from "./schema/a2a.js";
+export { cleanPeerText, createFence, terminalSafe, displayWidth, HOST_TAGS, PEER_FENCE_TAG, PEER_DATA_NOTICE, provenanceOf } from "./peer-text.js";
+// The agent tool contract shared by the OpenCode plugin and messaging-mcp (spec §11, "Agent tools").
+export { AgentTool, TOOL_VERBS, TOOL_DESCRIPTIONS, ToolExpect, UNTRUSTED_SENTENCE, TOOL_REMEDIES, DONE_STATES, TaskStateName, ToolErrorBody, ToolFiles, a2aTaskState, conversationOf, decodeToolCursor, encodeToolCursor, formatToolAddress, parseToolAddress, taskStateName, toolErrorBody, toolName, } from "./agent-tools.js";
+// The agent tools' operations and presenters, shared by the plugin and messaging-mcp (spec §11).
+export { Operations, } from "./agent/operations.js";
+export { agentCan, consentOf, conversationOfPeer, followUpRead, isoOf, presentAgent, presentConvEntry, presentInboxItem, presentLine, presentMail, presentSent, presentTask, presentTaskItem, presentTaskView, } from "./agent/present.js";
+export { chainPath, compact, delegated, delegationPrompt, EXPECT_TEXT, isSafeId, messageAttributes, validatedAddress, } from "./agent/text.js";

package/dist/lib/modules/core/jcs.js

@@ -0,0 +1,96 @@
+import { LIMITS } from "./schema/common.js";
+import { MessagingError } from "./schema/errors.js";
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** True when `text` has a UTF-16 surrogate without its partner, which has no UTF-8 form. */
+function hasLoneSurrogate(text) {
+    return LONE_SURROGATE.test(text);
+}
+/**
+ * RFC 8785 JSON Canonicalization Scheme over the I-JSON subset Messaging signs.
+ * Object members whose value is `undefined` are dropped. Throws `invalid_request` for anything
+ * that is not I-JSON: NaN, ±Infinity, integers beyond ±(2^53 − 1), bigint, functions, symbols,
+ * `undefined` array elements or top-level values, lone surrogates, cycles, and non-plain objects.
+ * It also throws `invalid_request` for arrays and objects nested deeper than `LIMITS.jsonDepth`.
+ *
+ * The cost is linear in the size of the value, and the result never depends on the call stack: each
+ * node is visited once with O(1) bookkeeping, recursion stops at `LIMITS.jsonDepth`, and a cycle is
+ * caught by that same limit (sorting member names is the only superlinear step).
+ */
+export function canonicalize(value) {
+    return write(value, []);
+}
+function write(value, ancestors) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+            return string(value);
+        case "number":
+            return number(value);
+        case "boolean":
+            return value ? "true" : "false";
+        case "object":
+            break;
+        default:
+            throw invalid(`${typeof value} is not JSON`);
+    }
+    const object = value;
+    // A cycle always runs into the depth limit, so the ancestors are searched only once that is hit.
+    if (ancestors.length >= LIMITS.jsonDepth) {
+        throw invalid(ancestors.includes(object) ? "cyclic value" : `nested deeper than ${LIMITS.jsonDepth}`);
+    }
+    ancestors.push(object);
+    let out;
+    if (Array.isArray(object)) {
+        out = "[";
+        for (let i = 0; i < object.length; i++) {
+            const item = object[i];
+            if (item === undefined)
+                throw invalid("undefined array element");
+            if (i > 0)
+                out += ",";
+            out += write(item, ancestors);
+        }
+        out += "]";
+    }
+    else {
+        const proto = Object.getPrototypeOf(object);
+        if (proto !== Object.prototype && proto !== null && Object.getPrototypeOf(proto) !== null)
+            throw invalid("only plain objects are JSON");
+        const record = object;
+        const keys = Object.keys(record);
+        if (keys.length > 1)
+            keys.sort();
+        out = "{";
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            const member = record[key];
+            if (member === undefined)
+                continue;
+            out += `${out.length > 1 ? "," : ""}${string(key)}:${write(member, ancestors)}`;
+        }
+        out += "}";
+    }
+    ancestors.pop();
+    return out;
+}
+function number(value) {
+    if (Number.isSafeInteger(value))
+        return String(value);
+    if (!Number.isFinite(value))
+        throw invalid("non-finite number");
+    if (Number.isInteger(value))
+        throw invalid("integer outside ±(2^53 − 1)");
+    // ECMAScript Number::toString, as RFC 8785 §3.2.2.3 requires.
+    return String(value);
+}
+function string(value) {
+    const json = JSON.stringify(value);
+    // JSON.stringify escapes a lone surrogate as \udXXX, so only such output needs the exact check.
+    if (json.includes("\\ud") && hasLoneSurrogate(value))
+        throw invalid("lone surrogate");
+    return json;
+}
+function invalid(reason) {
+    return new MessagingError("invalid_request", `not I-JSON: ${reason}`);
+}

package/dist/lib/modules/core/jelly-host-double.js

@@ -0,0 +1,35 @@
+/**
+ * A Jelly host double, for tests only (exported from `@messaging/core/testing`): it holds an action key and mints
+ * action grants (`jelly-act+jwt`) and session tickets (`jelly-session+jwt`) as Jelly's host does (spec §8.11). Every
+ * claim can be overridden, so tests can mint what a conforming host never would.
+ */
+import { generateKeyPairSync } from "node:crypto";
+import { signJellyToken } from "./directory/jelly-issuer.js";
+import { actionClass, grantInput } from "./jelly-host.js";
+import { JELLY_SERVICE_AUDIENCE } from "./schema/jelly.js";
+let counter = 0;
+/** A host double with a fresh action key, signing at `now()` (milliseconds; default the wall clock). */
+export function jellyHostDouble(options = {}) {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    const kid = options.kid ?? "act-1";
+    const x = publicKey.export({ format: "jwk" }).x;
+    const key = { kty: "OKP", crv: "Ed25519", x, kid };
+    const now = () => Math.floor((options.now ?? Date.now)() / 1000);
+    const sign = (typ, claims, header = {}) => signJellyToken(privateKey, { alg: "EdDSA", typ, kid, ...header }, claims);
+    return {
+        key,
+        keyText: `${JSON.stringify(key)}\n`,
+        act(method, params = {}, claims = {}, header = {}) {
+            const iat = now();
+            return sign("jelly-act+jwt", { aud: JELLY_SERVICE_AUDIENCE, act: method, in: grantInput(params), iat, exp: iat + 60, jti: `j${++counter}-${iat}`, dev: "dev_test", cls: actionClass(method), ...claims }, header);
+        },
+        host(claims = {}) {
+            const iat = now();
+            return sign("jelly-act+jwt", { aud: JELLY_SERVICE_AUDIENCE, act: "host", iat, exp: iat + 600, jti: `h${++counter}-${iat}`, ...claims });
+        },
+        ticket(agt, name, claims = {}, header = {}) {
+            const iat = now();
+            return sign("jelly-session+jwt", { aud: JELLY_SERVICE_AUDIENCE, agt, name, iat, exp: iat + 7 * 86_400, ...claims }, header);
+        },
+    };
+}