@joe-broadhead/messaging 0.0.0-stage → 0.7.0

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

@@ -0,0 +1,454 @@
+import { randomBytes } from "node:crypto";
+import { b64u, utf8 } from "./b64u.js";
+import { asMessagingError, parseWith } from "./check.js";
+import { sha256 } from "./hash.js";
+import { canonicalize } from "./jcs.js";
+import { assertEd25519PublicKey, privateKeyFromRaw, rawPublicKey } from "./keys.js";
+import { DOMAIN, LIMITS, PROTOCOL, RELAY_PROTOCOL, } from "./schema/common.js";
+import { MessagingError } from "./schema/errors.js";
+import { GenesisEntry, InviteTicket, RosterEntry, TICKET_PREFIX, } from "./schema/roster.js";
+import { signWith, sign, verify } from "./sign.js";
+import { ulid } from "./ulid.js";
+import { parseWire } from "./wire.js";
+/** SHA-256 of the JCS form of the full entry, including `sig`. The genesis hash is the team id. */
+export function entryHash(entry) {
+    return sha256(canonicalize(entry));
+}
+/**
+ * A verified roster. Every entry passes schema, chain, signature and authority checks (the rules
+ * in `schema/roster.ts`) before it is appended; a failed `apply` leaves the roster unchanged.
+ * Entries are stored as frozen copies of the received JSON, so hashes cover unknown fields too.
+ * Members are stored as fresh `{machine, enc, person, role, label}` objects, never as received.
+ * Every method throws only MessagingError.
+ */
+export class Roster {
+    team;
+    name;
+    #entries = [];
+    #members = new Map();
+    #removed = new Set();
+    #invites = new Map();
+    #head;
+    constructor(genesis, hash) {
+        const { body } = genesis;
+        this.team = hash;
+        this.name = body.name;
+        this.#entries.push(genesis);
+        this.#members.set(body.founder.machine, memberOf(body.founder));
+        this.#head = { seq: 0, hash };
+    }
+    /** Verifies the whole chain from genesis. Throws the first failing entry's MessagingError. */
+    static fromEntries(entries) {
+        try {
+            return Roster.#replay(entries);
+        }
+        catch (error) {
+            throw asMessagingError(error, "roster");
+        }
+    }
+    static #replay(entries) {
+        if (!Array.isArray(entries) || entries.length === 0)
+            throw new MessagingError("invalid_request", "a roster needs a genesis entry");
+        const { entry, hash } = admit(entries[0]);
+        if (entry.kind !== "genesis")
+            throw new MessagingError("roster_conflict", "the first roster entry must be genesis");
+        if (entry.seq !== 0)
+            throw new MessagingError("roster_conflict", "genesis must have seq 0");
+        if (!verifyEntry(entry))
+            throw new MessagingError("bad_signature", "genesis signature is invalid");
+        const { founder } = entry.body;
+        if (entry.by !== founder.machine)
+            throw new MessagingError("forbidden", "genesis must be signed by the founder");
+        if (founder.role !== "admin")
+            throw new MessagingError("forbidden", "the founder must be an admin");
+        const roster = new Roster(entry, hash);
+        for (const next of entries.slice(1))
+            roster.#append(next, {});
+        return roster;
+    }
+    /**
+     * Validates one entry against the head and appends it. Checks run in order: schema, I-JSON and keys
+     * (`invalid_request`), chain (`roster_conflict` for seq/prev; `invalid_request` for team and ts),
+     * freshness (`expired`), signature (`bad_signature`), then authority (`forbidden`) and invites
+     * (`invite_invalid`). Pass `now` when accepting a live append: `ts` must then be within `skewMs`
+     * (default `LIMITS.clockSkewMs`) of `now`, so a joiner cannot backdate a redeem past its invite's expiry.
+     */
+    apply(raw, options = {}) {
+        try {
+            this.#append(raw, options);
+        }
+        catch (error) {
+            throw asMessagingError(error, "roster entry");
+        }
+    }
+    /**
+     * Checks `raw` as `apply` would have when the head was at `seq − 1`, without appending it: schema, chain
+     * (its `prev` must be the hash of this roster's entry at `seq − 1`), team, signature and authority, all
+     * against the state at that point. Returns the entry's hash. An entry that passes and whose hash differs
+     * from `entries()[seq]` proves a fork: two valid entries at one seq. `seq` more than one past the head is
+     * `roster_conflict`; a seq-0 entry passes only if it is this team's genesis. Other errors are as for
+     * `apply`. Checking an entry below the head replays the chain up to it.
+     */
+    checkAt(raw) {
+        try {
+            const { entry, hash } = admit(raw);
+            if (entry.seq === 0) {
+                Roster.#replay([raw]);
+                if (hash !== this.team)
+                    throw new MessagingError("invalid_request", "genesis is for another team");
+                return hash;
+            }
+            if (entry.seq > this.#head.seq + 1)
+                throw new MessagingError("roster_conflict", `entry is past head ${this.#head.seq} + 1`);
+            const before = entry.seq === this.#head.seq + 1 ? this : Roster.#replay(this.#entries.slice(0, entry.seq));
+            before.#check(entry, {});
+            return hash;
+        }
+        catch (error) {
+            throw asMessagingError(error, "roster entry");
+        }
+    }
+    #append(raw, options) {
+        const { now, skewMs } = options;
+        if (now !== undefined && !Number.isSafeInteger(now))
+            throw new MessagingError("invalid_request", "now must be an integer");
+        if (skewMs !== undefined && (!Number.isSafeInteger(skewMs) || skewMs < 0)) {
+            throw new MessagingError("invalid_request", "skewMs must be a non-negative integer");
+        }
+        const { entry, hash } = admit(raw);
+        const commit = this.#check(entry, options);
+        commit();
+        this.#entries.push(entry);
+        this.#head = { seq: entry.seq, hash };
+    }
+    /** Every check of `apply` after admission; returns the state change to make. Changes nothing itself. */
+    #check(entry, options) {
+        if (entry.kind === "genesis" || entry.seq !== this.#head.seq + 1 || entry.prev !== this.#head.hash) {
+            throw new MessagingError("roster_conflict", `entry does not extend head ${this.#head.seq}`);
+        }
+        if (entry.team !== this.team)
+            throw new MessagingError("invalid_request", "entry is for another team");
+        const last = this.#entries[this.#entries.length - 1];
+        if (entry.ts < last.ts - LIMITS.clockSkewMs)
+            throw new MessagingError("invalid_request", "entry ts goes backwards");
+        if (options.now !== undefined && Math.abs(entry.ts - options.now) > (options.skewMs ?? LIMITS.clockSkewMs)) {
+            throw new MessagingError("expired", "entry ts is outside the clock skew window");
+        }
+        if (!verifyEntry(entry))
+            throw new MessagingError("bad_signature", "roster entry signature is invalid");
+        return this.#authorize(entry);
+    }
+    head() {
+        return { ...this.#head };
+    }
+    entries() {
+        return [...this.#entries];
+    }
+    member(machine) {
+        const member = this.#members.get(machine);
+        return member && { ...member };
+    }
+    // ---- the realm view (spec §5): a roster realm is the team, its anchor the head ----
+    /** The realm's id: the team id. */
+    get realm() {
+        return this.team;
+    }
+    /** A current member's machine; the same as `member`. */
+    device(machine) {
+        return this.member(machine);
+    }
+    /** `{kind: "roster"}` and the head. */
+    anchor() {
+        return { kind: "roster", ...this.#head };
+    }
+    /** `ahead` past the head; `consistent` for an entry of this chain; `diverged` for another hash at a seq it has. */
+    relate(anchor) {
+        // A roster realm has no epochs: `verifyEnvelope` refuses another kind's anchor first.
+        if (anchor.kind !== "roster")
+            throw new MessagingError("invalid_request", "a roster realm relates roster anchors only");
+        const own = this.#head;
+        if (anchor.seq > own.seq)
+            return { relation: "ahead" };
+        const ours = anchor.seq === own.seq ? own.hash : entryHash(this.#entries[anchor.seq]);
+        return ours === anchor.hash ? { relation: "consistent" } : { relation: "diverged", ours };
+    }
+    members() {
+        return [...this.#members.values()].map((m) => ({ ...m }));
+    }
+    isAdmin(machine) {
+        return this.#members.get(machine)?.role === "admin";
+    }
+    /** The invite and its state at `now` (an open invite is `expired` once `now >= expires`). */
+    invite(inviteId, now = Date.now()) {
+        const record = this.#invites.get(inviteId);
+        if (!record)
+            return undefined;
+        const state = record.state === "open" && now >= record.entry.body.expires ? "expired" : record.state;
+        return { entry: record.entry, state };
+    }
+    wasRemoved(machine) {
+        return this.#removed.has(machine);
+    }
+    /** Checks authority for `entry` without changing state; returns the state change to apply. */
+    #authorize(entry) {
+        switch (entry.kind) {
+            case "member.add": {
+                this.#requireAdmin(entry.by);
+                this.#requireNew(entry.body);
+                return () => this.#members.set(entry.body.machine, memberOf(entry.body));
+            }
+            case "member.remove": {
+                const target = this.#requireMember(entry.body.machine);
+                if (entry.by !== target.machine)
+                    this.#requireAdmin(entry.by);
+                this.#requireNotLastAdmin(target);
+                return () => {
+                    this.#members.delete(target.machine);
+                    this.#removed.add(target.machine);
+                };
+            }
+            case "member.role": {
+                this.#requireAdmin(entry.by);
+                const target = this.#requireMember(entry.body.machine);
+                if (entry.body.role !== "admin")
+                    this.#requireNotLastAdmin(target);
+                return () => this.#members.set(target.machine, { ...target, role: entry.body.role });
+            }
+            case "member.rekey": {
+                // A removed machine is not a current member, so it can never be rekeyed (or rekey itself).
+                const target = this.#requireMember(entry.body.machine);
+                if (entry.by !== target.machine)
+                    this.#requireAdmin(entry.by);
+                return () => this.#members.set(target.machine, { ...target, enc: entry.body.enc });
+            }
+            case "invite.create": {
+                this.#requireAdmin(entry.by);
+                if (this.#invites.has(entry.body.inviteId))
+                    throw new MessagingError("invite_invalid", "invite id already exists");
+                if (entry.body.expires - entry.ts > LIMITS.ttlMs)
+                    throw new MessagingError("invite_invalid", "invite lifetime exceeds LIMITS.ttlMs");
+                return () => this.#invites.set(entry.body.inviteId, { entry, state: "open" });
+            }
+            case "invite.redeem": {
+                const { inviteId, proof, member } = entry.body;
+                if (entry.by !== member.machine)
+                    throw new MessagingError("forbidden", "a redeem must be signed by the joining machine");
+                const record = this.#invites.get(inviteId);
+                if (!record)
+                    throw new MessagingError("invite_invalid", "unknown invite");
+                if (record.state !== "open")
+                    throw new MessagingError("invite_invalid", `invite is ${record.state}`);
+                const invite = record.entry.body;
+                if (entry.ts >= invite.expires)
+                    throw new MessagingError("invite_invalid", "invite has expired");
+                if (!verify(invite.invitePub, DOMAIN.invite, redeemClaim(this.team, inviteId, member), proof)) {
+                    throw new MessagingError("invite_invalid", "invite proof does not verify for this member");
+                }
+                if (member.person !== invite.person || member.role !== "member") {
+                    throw new MessagingError("invite_invalid", "member does not match the invite");
+                }
+                this.#requireNew(member);
+                return () => {
+                    record.state = "redeemed";
+                    this.#members.set(member.machine, memberOf(member));
+                };
+            }
+            case "invite.revoke": {
+                this.#requireAdmin(entry.by);
+                const record = this.#invites.get(entry.body.inviteId);
+                if (!record)
+                    throw new MessagingError("invite_invalid", "unknown invite");
+                if (record.state !== "open")
+                    throw new MessagingError("invite_invalid", `invite is ${record.state}`);
+                return () => {
+                    record.state = "revoked";
+                };
+            }
+        }
+    }
+    #requireAdmin(machine) {
+        if (!this.isAdmin(machine))
+            throw new MessagingError("forbidden", "only a current admin may do this");
+    }
+    #requireMember(machine) {
+        const member = this.#members.get(machine);
+        if (!member)
+            throw new MessagingError("forbidden", "target is not a current member");
+        return member;
+    }
+    /**
+     * A machine joins once: never while it is a member, and never again after removal (so its person never
+     * changes). Its (person, label) must not be used by a current member, so `person/session@label` names one machine.
+     */
+    #requireNew(member) {
+        if (this.#members.has(member.machine))
+            throw new MessagingError("forbidden", "machine is already a member");
+        if (this.#removed.has(member.machine))
+            throw new MessagingError("forbidden", "a removed machine can never rejoin");
+        for (const current of this.#members.values()) {
+            if (current.person === member.person && current.label === member.label) {
+                throw new MessagingError("forbidden", "a current member already uses this person and label");
+            }
+        }
+    }
+    #requireNotLastAdmin(target) {
+        if (target.role !== "admin")
+            return;
+        const admins = [...this.#members.values()].filter((m) => m.role === "admin").length;
+        if (admins <= 1)
+            throw new MessagingError("forbidden", "the last admin cannot be removed or demoted");
+    }
+}
+/**
+ * Checks that a raw entry is I-JSON within `LIMITS.jsonDepth`, matches the schema and admits only usable
+ * keys, then returns a frozen JSON copy with its hash. Canonicalizing first bounds every later step.
+ */
+function admit(raw) {
+    const json = canonicalize(raw);
+    parseWith(RosterEntry, raw, "roster entry");
+    const entry = deepFreeze(JSON.parse(json));
+    for (const [key, what] of admittedKeys(entry))
+        assertEd25519PublicKey(key, what);
+    return { entry, hash: sha256(json) };
+}
+/** Ed25519 keys an entry brings into the roster: they must be canonical and not of small order (spec §3). */
+function admittedKeys(entry) {
+    switch (entry.kind) {
+        case "genesis":
+            return [[entry.body.founder.machine, "founder machine"]];
+        case "member.add":
+            return [[entry.body.machine, "member machine"]];
+        case "invite.redeem":
+            return [[entry.body.member.machine, "member machine"]];
+        case "invite.create":
+            return [[entry.body.invitePub, "invitePub"]];
+        default:
+            return [];
+    }
+}
+function verifyEntry(entry) {
+    const { sig, ...unsigned } = entry;
+    return verify(entry.by, DOMAIN.roster, unsigned, sig);
+}
+/** Copies exactly the member fields, so signer-chosen extra keys (even an own `__proto__`) never reach roster state. */
+function memberOf(member) {
+    return { machine: member.machine, enc: member.enc, person: member.person, role: member.role, label: member.label };
+}
+/** The value an invite seed signs (with `DOMAIN.invite`) for a redeem. `member` is the raw member object of the entry. */
+function redeemClaim(team, inviteId, member) {
+    return { team, inviteId, member };
+}
+/** Freezes a JSON value and everything in it, iteratively. */
+function deepFreeze(value) {
+    const pending = [value];
+    while (pending.length > 0) {
+        const next = pending.pop();
+        if (typeof next !== "object" || next === null || Object.isFrozen(next))
+            continue;
+        Object.freeze(next);
+        for (const child of Object.values(next))
+            pending.push(child);
+    }
+    return value;
+}
+/** The invite seed of a ticket as an Ed25519 private key. */
+function seedKey(secret) {
+    return privateKeyFromRaw("ed25519", b64u.decode(secret));
+}
+export function createGenesis(args) {
+    const { identity } = args;
+    const founder = { machine: identity.machine, enc: identity.enc, person: args.person, role: "admin", label: args.label };
+    const unsigned = {
+        v: PROTOCOL,
+        seq: 0,
+        ts: args.now ?? Date.now(),
+        by: identity.machine,
+        prev: null,
+        kind: "genesis",
+        body: { name: args.name, founder },
+    };
+    parseWith(GenesisEntry, { ...unsigned, sig: "" }, "genesis");
+    return { ...unsigned, sig: sign(identity, DOMAIN.roster, unsigned) };
+}
+/** Signs a new entry that extends the roster head. Authority is checked when the entry is applied. */
+export function createEntry(roster, identity, kind, body, now = Date.now()) {
+    const head = roster.head();
+    const unsigned = { v: PROTOCOL, seq: head.seq + 1, ts: now, by: identity.machine, team: roster.team, prev: head.hash, kind, body };
+    const parsed = parseWith(RosterEntry, { ...unsigned, sig: "" }, `${kind} entry`);
+    const { sig: _sig, ...canonical } = parsed;
+    return { ...canonical, sig: sign(identity, DOMAIN.roster, canonical) };
+}
+/**
+ * An `invite.create` entry and its ticket. The secret is a fresh 32-byte Ed25519 seed; only its public key
+ * (`invitePub`) goes in the roster. `ttlMs` is at most `LIMITS.ttlMs`.
+ */
+export function createInvite(roster, identity, args) {
+    if (!Number.isSafeInteger(args.ttlMs) || args.ttlMs <= 0 || args.ttlMs > LIMITS.ttlMs) {
+        throw new MessagingError("invalid_request", "ttlMs must be a positive integer up to LIMITS.ttlMs");
+    }
+    const now = args.now ?? Date.now();
+    const secret = b64u.encode(randomBytes(32));
+    const inviteId = ulid(now);
+    const expires = now + args.ttlMs;
+    const ticket = encodeTicket({
+        v: PROTOCOL,
+        team: roster.team,
+        name: roster.name,
+        relay: args.relay,
+        inviteId,
+        secret,
+        person: args.person,
+        expires,
+    });
+    const entry = createEntry(roster, identity, "invite.create", {
+        inviteId,
+        invitePub: rawPublicKey(seedKey(secret)),
+        person: args.person,
+        expires,
+    }, now);
+    return { entry, ticket, secret };
+}
+/** `messaging1.` + base64url(UTF-8(JCS(ticket))). */
+export function encodeTicket(ticket) {
+    return TICKET_PREFIX + b64u.encode(utf8(canonicalize(parseWith(InviteTicket, ticket, "invite ticket"))));
+}
+/** Parses a ticket with `parseWire`. Errors never quote the ticket and chain no `cause`. */
+export function decodeTicket(text) {
+    if (typeof text !== "string" || !text.startsWith(TICKET_PREFIX))
+        throw new MessagingError("invalid_request", "not a messaging1 invite ticket");
+    let json;
+    try {
+        json = new TextDecoder("utf-8", { fatal: true }).decode(b64u.decode(text.slice(TICKET_PREFIX.length)));
+    }
+    catch {
+        throw new MessagingError("invalid_request", "invite ticket is not encoded correctly");
+    }
+    return parseWith(InviteTicket, parseWire(json), "invite ticket");
+}
+/**
+ * The `invite.redeem` entry for a ticket, signed by the joining identity. Its `proof` is signed with the
+ * ticket's seed over {team, inviteId, member}, so the redeem holds only for this member; the seed is not in it.
+ */
+export function createRedeem(roster, ticket, identity, args) {
+    if (ticket.team !== roster.team)
+        throw new MessagingError("invite_invalid", "ticket is for another team");
+    const member = { machine: identity.machine, enc: identity.enc, person: ticket.person, role: "member", label: args.label };
+    const proof = signWith(seedKey(ticket.secret), DOMAIN.invite, redeemClaim(roster.team, ticket.inviteId, member));
+    return createEntry(roster, identity, "invite.redeem", { inviteId: ticket.inviteId, proof, member }, args.now);
+}
+/** The value a machine signs (with `DOMAIN.relayAuth`) in the relay `hello` frame. */
+export function relayAuthPayload(args) {
+    return { proto: RELAY_PROTOCOL, relay: args.relay, team: args.team, machine: args.machine, nonce: args.nonce, ts: args.ts };
+}
+/**
+ * The value an invite seed signs (with `DOMAIN.inviteJoin`) in a pre-auth `join` frame: the relay id and
+ * nonce from the connection's challenge, and the invite. The relay verifies it under the open invite's `invitePub`.
+ */
+export function inviteJoinPayload(args) {
+    return { relay: args.relay, team: args.team, inviteId: args.inviteId, nonce: args.nonce };
+}
+/** The `join` frame `proof` for `ticket` on a connection whose challenge carried `relay` and `nonce`. It proves the seed without revealing it. */
+export function inviteJoinProof(ticket, challenge) {
+    const payload = inviteJoinPayload({ relay: challenge.relay, team: ticket.team, inviteId: ticket.inviteId, nonce: challenge.nonce });
+    return signWith(seedKey(ticket.secret), DOMAIN.inviteJoin, payload);
+}

package/dist/lib/modules/core/schema/a2a.js

@@ -0,0 +1,85 @@
+/**
+ * A2A v1 JSON shapes (proto3 JSON mapping of `lf.a2a.v1`, specification/a2a.proto).
+ * Field names are lowerCamelCase; enums are their proto names; bytes are base64.
+ * Objects strip unknown keys on parse, so newer peers' extra fields are tolerated.
+ * Signatures are always verified over the raw received JSON, before parsing.
+ */
+import { z } from "../../vendor/zod/index.js";
+const Struct = z.record(z.string(), z.unknown());
+export const TaskState = z.enum([
+    "TASK_STATE_SUBMITTED",
+    "TASK_STATE_WORKING",
+    "TASK_STATE_COMPLETED",
+    "TASK_STATE_FAILED",
+    "TASK_STATE_CANCELED",
+    "TASK_STATE_INPUT_REQUIRED",
+    "TASK_STATE_REJECTED",
+    "TASK_STATE_AUTH_REQUIRED",
+]);
+export const TERMINAL_STATES = [
+    "TASK_STATE_COMPLETED",
+    "TASK_STATE_FAILED",
+    "TASK_STATE_CANCELED",
+    "TASK_STATE_REJECTED",
+];
+export const INTERRUPTED_STATES = ["TASK_STATE_INPUT_REQUIRED", "TASK_STATE_AUTH_REQUIRED"];
+export const Role = z.enum(["ROLE_USER", "ROLE_AGENT"]);
+/** Exactly one of text | raw | url | data. `data` may be any JSON value, including null. */
+export const Part = z
+    .object({
+    text: z.string().optional(),
+    raw: z.string().optional().describe("base64 bytes"),
+    url: z.string().optional(),
+    data: z.unknown().optional(),
+    metadata: Struct.optional(),
+    filename: z.string().max(255).optional(),
+    mediaType: z.string().max(255).optional(),
+})
+    .refine((p) => [p.text, p.raw, p.url].filter((v) => v !== undefined).length + ("data" in p ? 1 : 0) === 1, {
+    message: "a part has exactly one of text, raw, url or data",
+});
+export const Message = z.object({
+    messageId: z.string().min(1).max(128),
+    contextId: z.string().max(128).optional(),
+    taskId: z.string().max(128).optional(),
+    role: Role,
+    parts: z.array(Part).min(1),
+    metadata: Struct.optional(),
+    extensions: z.array(z.string()).optional(),
+    referenceTaskIds: z.array(z.string()).optional(),
+});
+export const TaskStatus = z.object({
+    state: TaskState,
+    message: Message.optional(),
+    timestamp: z.string().optional().describe("ISO 8601"),
+});
+export const Artifact = z.object({
+    artifactId: z.string().min(1).max(128),
+    name: z.string().max(200).optional(),
+    description: z.string().max(2000).optional(),
+    parts: z.array(Part).min(1),
+    metadata: Struct.optional(),
+    extensions: z.array(z.string()).optional(),
+});
+export const Task = z.object({
+    id: z.string().min(1).max(128),
+    contextId: z.string().max(128).optional(),
+    status: TaskStatus,
+    artifacts: z.array(Artifact).optional(),
+    history: z.array(Message).optional(),
+    metadata: Struct.optional(),
+});
+export const TaskStatusUpdateEvent = z.object({
+    taskId: z.string().min(1),
+    contextId: z.string(),
+    status: TaskStatus,
+    metadata: Struct.optional(),
+});
+export const TaskArtifactUpdateEvent = z.object({
+    taskId: z.string().min(1),
+    contextId: z.string(),
+    artifact: Artifact,
+    append: z.boolean().optional(),
+    lastChunk: z.boolean().optional(),
+    metadata: Struct.optional(),
+});