@joe-broadhead/messaging 0.0.0-stage → 0.7.1

package/dist/types/core/roster.d.ts

@@ -0,0 +1,146 @@
+import type { Identity } from "./identity.js";
+import { type Hash, type MachineId, type MachineLabel, type PersonName, RELAY_PROTOCOL, type TeamId, type Ulid } from "./schema/common.js";
+import type { AnchorRelation, RealmView } from "./realm.js";
+import type { Anchor, RealmId, RosterAnchor } from "./schema/realm.js";
+import { InviteTicket, type Member, RosterEntry, type RosterHead, type RosterKind } from "./schema/roster.js";
+type ChainedKind = Exclude<RosterKind, "genesis">;
+type EntryOf<K extends RosterKind> = Extract<RosterEntry, {
+    kind: K;
+}>;
+export type RosterBody<K extends RosterKind> = EntryOf<K>["body"];
+export type InviteState = "open" | "redeemed" | "revoked" | "expired";
+/** Options for `Roster.apply`. */
+export interface ApplyOptions {
+    /** Wall-clock time of a live append. When set, the entry `ts` must be within `skewMs` of it (`expired`). */
+    now?: number;
+    /**
+     * The freshness window around `now`; default `LIMITS.clockSkewMs`. The relay uses the default; a daemon
+     * applying a live roster broadcast passes `2 * LIMITS.clockSkewMs`, because the relay's clock may differ
+     * from its own by up to the skew (spec §4).
+     */
+    skewMs?: number;
+}
+/** SHA-256 of the JCS form of the full entry, including `sig`. The genesis hash is the team id. */
+export declare function entryHash(entry: RosterEntry): Hash;
+/**
+ * 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 declare class Roster implements RealmView {
+    #private;
+    readonly team: TeamId;
+    readonly name: string;
+    private constructor();
+    /** Verifies the whole chain from genesis. Throws the first failing entry's MessagingError. */
+    static fromEntries(entries: unknown[]): 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: unknown, options?: ApplyOptions): void;
+    /**
+     * 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: unknown): Hash;
+    head(): RosterHead;
+    entries(): RosterEntry[];
+    member(machine: MachineId): Member | undefined;
+    /** The realm's id: the team id. */
+    get realm(): RealmId;
+    /** A current member's machine; the same as `member`. */
+    device(machine: MachineId): Member | undefined;
+    /** `{kind: "roster"}` and the head. */
+    anchor(): RosterAnchor;
+    /** `ahead` past the head; `consistent` for an entry of this chain; `diverged` for another hash at a seq it has. */
+    relate(anchor: Anchor): AnchorRelation;
+    members(): Member[];
+    isAdmin(machine: MachineId): boolean;
+    /** The invite and its state at `now` (an open invite is `expired` once `now >= expires`). */
+    invite(inviteId: string, now?: number): {
+        entry: EntryOf<"invite.create">;
+        state: InviteState;
+    } | undefined;
+    wasRemoved(machine: MachineId): boolean;
+}
+export declare function createGenesis(args: {
+    identity: Identity;
+    name: string;
+    person: PersonName;
+    label: MachineLabel;
+    now?: number;
+}): EntryOf<"genesis">;
+/** Signs a new entry that extends the roster head. Authority is checked when the entry is applied. */
+export declare function createEntry<K extends ChainedKind>(roster: Roster, identity: Identity, kind: K, body: RosterBody<K>, now?: number): EntryOf<K>;
+/**
+ * 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 declare function createInvite(roster: Roster, identity: Identity, args: {
+    person: PersonName;
+    ttlMs: number;
+    relay: string;
+    now?: number;
+}): {
+    entry: EntryOf<"invite.create">;
+    ticket: string;
+    secret: string;
+};
+/** `messaging1.` + base64url(UTF-8(JCS(ticket))). */
+export declare function encodeTicket(ticket: InviteTicket): string;
+/** Parses a ticket with `parseWire`. Errors never quote the ticket and chain no `cause`. */
+export declare function decodeTicket(text: string): InviteTicket;
+/**
+ * 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 declare function createRedeem(roster: Roster, ticket: InviteTicket, identity: Identity, args: {
+    label: MachineLabel;
+    now?: number;
+}): EntryOf<"invite.redeem">;
+/** The value a machine signs (with `DOMAIN.relayAuth`) in the relay `hello` frame. */
+export declare function relayAuthPayload(args: {
+    relay: string;
+    team: TeamId;
+    machine: MachineId;
+    nonce: string;
+    ts: number;
+}): {
+    proto: typeof RELAY_PROTOCOL;
+    relay: string;
+    team: TeamId;
+    machine: MachineId;
+    nonce: string;
+    ts: number;
+};
+/**
+ * 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 declare function inviteJoinPayload(args: {
+    relay: string;
+    team: TeamId;
+    inviteId: Ulid;
+    nonce: string;
+}): {
+    relay: string;
+    team: TeamId;
+    inviteId: Ulid;
+    nonce: string;
+};
+/** The `join` frame `proof` for `ticket` on a connection whose challenge carried `relay` and `nonce`. It proves the seed without revealing it. */
+export declare function inviteJoinProof(ticket: InviteTicket, challenge: {
+    relay: string;
+    nonce: string;
+}): string;
+export {};

package/dist/types/core/schema/a2a.d.ts

@@ -0,0 +1,251 @@
+/**
+ * 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 "zod";
+export declare const TaskState: z.ZodEnum<{
+    TASK_STATE_SUBMITTED: "TASK_STATE_SUBMITTED";
+    TASK_STATE_WORKING: "TASK_STATE_WORKING";
+    TASK_STATE_COMPLETED: "TASK_STATE_COMPLETED";
+    TASK_STATE_FAILED: "TASK_STATE_FAILED";
+    TASK_STATE_CANCELED: "TASK_STATE_CANCELED";
+    TASK_STATE_INPUT_REQUIRED: "TASK_STATE_INPUT_REQUIRED";
+    TASK_STATE_REJECTED: "TASK_STATE_REJECTED";
+    TASK_STATE_AUTH_REQUIRED: "TASK_STATE_AUTH_REQUIRED";
+}>;
+export type TaskState = z.infer<typeof TaskState>;
+export declare const TERMINAL_STATES: readonly TaskState[];
+export declare const INTERRUPTED_STATES: readonly TaskState[];
+export declare const Role: z.ZodEnum<{
+    ROLE_USER: "ROLE_USER";
+    ROLE_AGENT: "ROLE_AGENT";
+}>;
+export type Role = z.infer<typeof Role>;
+/** Exactly one of text | raw | url | data. `data` may be any JSON value, including null. */
+export declare const Part: z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    raw: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodUnknown>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    filename: z.ZodOptional<z.ZodString>;
+    mediaType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Part = z.infer<typeof Part>;
+export declare const Message: z.ZodObject<{
+    messageId: z.ZodString;
+    contextId: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    role: z.ZodEnum<{
+        ROLE_USER: "ROLE_USER";
+        ROLE_AGENT: "ROLE_AGENT";
+    }>;
+    parts: z.ZodArray<z.ZodObject<{
+        text: z.ZodOptional<z.ZodString>;
+        raw: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodUnknown>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        filename: z.ZodOptional<z.ZodString>;
+        mediaType: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type Message = z.infer<typeof Message>;
+export declare const TaskStatus: z.ZodObject<{
+    state: z.ZodEnum<{
+        TASK_STATE_SUBMITTED: "TASK_STATE_SUBMITTED";
+        TASK_STATE_WORKING: "TASK_STATE_WORKING";
+        TASK_STATE_COMPLETED: "TASK_STATE_COMPLETED";
+        TASK_STATE_FAILED: "TASK_STATE_FAILED";
+        TASK_STATE_CANCELED: "TASK_STATE_CANCELED";
+        TASK_STATE_INPUT_REQUIRED: "TASK_STATE_INPUT_REQUIRED";
+        TASK_STATE_REJECTED: "TASK_STATE_REJECTED";
+        TASK_STATE_AUTH_REQUIRED: "TASK_STATE_AUTH_REQUIRED";
+    }>;
+    message: z.ZodOptional<z.ZodObject<{
+        messageId: z.ZodString;
+        contextId: z.ZodOptional<z.ZodString>;
+        taskId: z.ZodOptional<z.ZodString>;
+        role: z.ZodEnum<{
+            ROLE_USER: "ROLE_USER";
+            ROLE_AGENT: "ROLE_AGENT";
+        }>;
+        parts: z.ZodArray<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            raw: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodUnknown>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            filename: z.ZodOptional<z.ZodString>;
+            mediaType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    timestamp: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TaskStatus = z.infer<typeof TaskStatus>;
+export declare const Artifact: z.ZodObject<{
+    artifactId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    parts: z.ZodArray<z.ZodObject<{
+        text: z.ZodOptional<z.ZodString>;
+        raw: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodUnknown>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        filename: z.ZodOptional<z.ZodString>;
+        mediaType: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type Artifact = z.infer<typeof Artifact>;
+export declare const Task: z.ZodObject<{
+    id: z.ZodString;
+    contextId: z.ZodOptional<z.ZodString>;
+    status: z.ZodObject<{
+        state: z.ZodEnum<{
+            TASK_STATE_SUBMITTED: "TASK_STATE_SUBMITTED";
+            TASK_STATE_WORKING: "TASK_STATE_WORKING";
+            TASK_STATE_COMPLETED: "TASK_STATE_COMPLETED";
+            TASK_STATE_FAILED: "TASK_STATE_FAILED";
+            TASK_STATE_CANCELED: "TASK_STATE_CANCELED";
+            TASK_STATE_INPUT_REQUIRED: "TASK_STATE_INPUT_REQUIRED";
+            TASK_STATE_REJECTED: "TASK_STATE_REJECTED";
+            TASK_STATE_AUTH_REQUIRED: "TASK_STATE_AUTH_REQUIRED";
+        }>;
+        message: z.ZodOptional<z.ZodObject<{
+            messageId: z.ZodString;
+            contextId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            role: z.ZodEnum<{
+                ROLE_USER: "ROLE_USER";
+                ROLE_AGENT: "ROLE_AGENT";
+            }>;
+            parts: z.ZodArray<z.ZodObject<{
+                text: z.ZodOptional<z.ZodString>;
+                raw: z.ZodOptional<z.ZodString>;
+                url: z.ZodOptional<z.ZodString>;
+                data: z.ZodOptional<z.ZodUnknown>;
+                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                filename: z.ZodOptional<z.ZodString>;
+                mediaType: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        artifactId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        parts: z.ZodArray<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            raw: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodUnknown>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            filename: z.ZodOptional<z.ZodString>;
+            mediaType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    history: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        messageId: z.ZodString;
+        contextId: z.ZodOptional<z.ZodString>;
+        taskId: z.ZodOptional<z.ZodString>;
+        role: z.ZodEnum<{
+            ROLE_USER: "ROLE_USER";
+            ROLE_AGENT: "ROLE_AGENT";
+        }>;
+        parts: z.ZodArray<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            raw: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodUnknown>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            filename: z.ZodOptional<z.ZodString>;
+            mediaType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type Task = z.infer<typeof Task>;
+export declare const TaskStatusUpdateEvent: z.ZodObject<{
+    taskId: z.ZodString;
+    contextId: z.ZodString;
+    status: z.ZodObject<{
+        state: z.ZodEnum<{
+            TASK_STATE_SUBMITTED: "TASK_STATE_SUBMITTED";
+            TASK_STATE_WORKING: "TASK_STATE_WORKING";
+            TASK_STATE_COMPLETED: "TASK_STATE_COMPLETED";
+            TASK_STATE_FAILED: "TASK_STATE_FAILED";
+            TASK_STATE_CANCELED: "TASK_STATE_CANCELED";
+            TASK_STATE_INPUT_REQUIRED: "TASK_STATE_INPUT_REQUIRED";
+            TASK_STATE_REJECTED: "TASK_STATE_REJECTED";
+            TASK_STATE_AUTH_REQUIRED: "TASK_STATE_AUTH_REQUIRED";
+        }>;
+        message: z.ZodOptional<z.ZodObject<{
+            messageId: z.ZodString;
+            contextId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            role: z.ZodEnum<{
+                ROLE_USER: "ROLE_USER";
+                ROLE_AGENT: "ROLE_AGENT";
+            }>;
+            parts: z.ZodArray<z.ZodObject<{
+                text: z.ZodOptional<z.ZodString>;
+                raw: z.ZodOptional<z.ZodString>;
+                url: z.ZodOptional<z.ZodString>;
+                data: z.ZodOptional<z.ZodUnknown>;
+                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                filename: z.ZodOptional<z.ZodString>;
+                mediaType: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type TaskStatusUpdateEvent = z.infer<typeof TaskStatusUpdateEvent>;
+export declare const TaskArtifactUpdateEvent: z.ZodObject<{
+    taskId: z.ZodString;
+    contextId: z.ZodString;
+    artifact: z.ZodObject<{
+        artifactId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        parts: z.ZodArray<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            raw: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodUnknown>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            filename: z.ZodOptional<z.ZodString>;
+            mediaType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    append: z.ZodOptional<z.ZodBoolean>;
+    lastChunk: z.ZodOptional<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type TaskArtifactUpdateEvent = z.infer<typeof TaskArtifactUpdateEvent>;