@dopamint-fun/open-sdk 0.1.0-dev.0

package/dist/crypto.d.ts

@@ -0,0 +1,3 @@
+export declare function blake2b256(input: Uint8Array): Uint8Array;
+export declare function digestFramed(domain: Uint8Array, payload: Uint8Array): Uint8Array;
+export declare function verifyEd25519(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;

package/dist/crypto.js

@@ -0,0 +1,20 @@
+import { createPublicKey, verify } from "node:crypto";
+import { blake2b } from "@noble/hashes/blake2.js";
+import { frameSigningBytes } from "./bytes.js";
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+export function blake2b256(input) {
+    return blake2b(input, { dkLen: 32 });
+}
+export function digestFramed(domain, payload) {
+    return blake2b256(frameSigningBytes(domain, payload));
+}
+export function verifyEd25519(publicKey, message, signature) {
+    if (publicKey.length !== 32 || signature.length !== 64)
+        return false;
+    const key = createPublicKey({
+        key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(publicKey)]),
+        format: "der",
+        type: "spki",
+    });
+    return verify(null, message, key, signature);
+}

package/dist/identity.d.ts

@@ -0,0 +1,32 @@
+import { type AgentKeypair } from "./keypair.js";
+export interface AgentIdentityFields {
+    /** shown at a table and in a replay; up to 32 characters */
+    name?: string | null;
+    /** unique across the arena and used in a URL; 3-20 of a-z, 0-9, _ */
+    handle?: string | null;
+    /** one line on the agent's page; up to 50 characters */
+    bio?: string | null;
+}
+/** The form the product stores, which is the form the signature covers. */
+export declare function parseIdentityFields(fields: AgentIdentityFields): Required<AgentIdentityFields>;
+/** The exact bytes the owning address signs to name an agent. */
+export declare function canonicalIdentityPayload(edit: {
+    agentId: string;
+    owner: string;
+    fields: AgentIdentityFields;
+    issuedAtMs: number;
+    expiresAtMs: number;
+}): Uint8Array;
+export interface NameAgentArgs {
+    productUrl: string;
+    agentId: string;
+    /** the address that owns the agent: this key's own, before a claim */
+    owner: string;
+    agent: AgentKeypair;
+    fields: AgentIdentityFields;
+    windowMs?: number;
+    nowMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/** Name an agent, as the address that owns it. Answers what the arena stored. */
+export declare function nameAgent(args: NameAgentArgs): Promise<Required<AgentIdentityFields>>;

package/dist/identity.js

@@ -0,0 +1,100 @@
+/* Naming an agent: what it is called at a table, signed by the address that
+ * owns it.
+ *
+ * On the self-custody path that address is the agent's own key, so an agent
+ * can arrive named rather than playing as "seat 1" until a wallet turns up
+ * and names it. After a claim the same route belongs to the claiming wallet,
+ * and this key can no longer sign for it -- which is the point of a claim.
+ *
+ * The payload mirrors `AgentIdentityEdit::canonical_payload` in
+ * `backend/dopa-open/product/src/domain/custodial/key_rotation.rs`: every
+ * field is length-framed, so "ab"/"c" and "a"/"bc" cannot sign the same
+ * bytes. The product parses before it verifies -- it trims each field and
+ * lower-cases the handle -- so this signs the parsed form, or the signature
+ * is over bytes the store never holds. */
+import { signOwnerAuthenticator } from "./keypair.js";
+const IDENTITY_DOMAIN = "dopa_open::agent_identity::v1";
+/** How long a naming request is good for, unless the caller says otherwise. */
+const DEFAULT_WINDOW_MS = 5 * 60 * 1000;
+/** The form the product stores, which is the form the signature covers. */
+export function parseIdentityFields(fields) {
+    return {
+        name: fields.name?.trim() || null,
+        handle: fields.handle?.trim().toLowerCase() || null,
+        bio: fields.bio?.trim() || null,
+    };
+}
+function u64be(value) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, BigInt(value));
+    return out;
+}
+function fromHex(value) {
+    const hex = value.replace(/^0x/i, "");
+    const out = new Uint8Array(hex.length / 2);
+    for (let index = 0; index < out.length; index++)
+        out[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+    return out;
+}
+/** The exact bytes the owning address signs to name an agent. */
+export function canonicalIdentityPayload(edit) {
+    const encoder = new TextEncoder();
+    const domain = encoder.encode(IDENTITY_DOMAIN);
+    const parsed = parseIdentityFields(edit.fields);
+    const parts = [parsed.name ?? "", parsed.handle ?? "", parsed.bio ?? ""].map((field) => encoder.encode(field));
+    const chunks = [
+        u64be(domain.length),
+        domain,
+        fromHex(edit.agentId),
+        fromHex(edit.owner),
+        ...parts.flatMap((field) => [u64be(field.length), field]),
+        u64be(edit.issuedAtMs),
+        u64be(edit.expiresAtMs),
+    ];
+    const out = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.length, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/** Name an agent, as the address that owns it. Answers what the arena stored. */
+export async function nameAgent(args) {
+    const fetchImpl = args.fetchImpl ?? fetch;
+    const issuedAtMs = args.nowMs ?? Date.now();
+    const expiresAtMs = issuedAtMs + (args.windowMs ?? DEFAULT_WINDOW_MS);
+    const fields = parseIdentityFields(args.fields);
+    const signature = await signOwnerAuthenticator(args.agent, canonicalIdentityPayload({
+        agentId: args.agentId,
+        owner: args.owner,
+        fields,
+        issuedAtMs,
+        expiresAtMs,
+    }));
+    const agentId = `0x${args.agentId.replace(/^0x/i, "")}`;
+    const response = await fetchImpl(`${args.productUrl.replace(/\/$/, "")}/open/v1/agents/${agentId}/identity`, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            name: fields.name,
+            handle: fields.handle,
+            bio: fields.bio,
+            issuedAtMs,
+            expiresAtMs,
+            signature,
+        }),
+    });
+    if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        /* Named plainly, because the one refusal a caller meets in practice is a
+           handle somebody else already holds, and "409" does not say to pick
+           another one. */
+        const taken = detail.includes("handle_taken");
+        throw new Error(taken
+            ? `handle "${fields.handle}" belongs to another agent; choose another`
+            : `naming refused (${response.status}): ${detail}`);
+    }
+    const body = (await response.json());
+    return parseIdentityFields(body);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { DEFAULT_KEY_FILE, generateKeypair, keypairFromSeed, loadKeypair, saveKeypair, signOwnerAuthenticator, signRaw, type AgentKeypair, } from "./keypair.js";
+export { deriveAgentId, registerCanonicalPayload, registerPayloadDigest, type RegisterAgentPayload, } from "./registration.js";
+export { canonicalIdentityPayload, nameAgent, parseIdentityFields, type AgentIdentityFields, type NameAgentArgs, } from "./identity.js";
+export { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, resumeSigningBytes, type ActionProposal, type ArtifactReference, type JoinRequest, type ResumeRequest, type SessionContext, } from "./sessionWire.js";
+export { encodeAckFrame, SESSION_ERROR_NAMES, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
+export { type OpenTableView, type PlayReport, type SeatDecision, type SeatDecisionResult, type SeatPosition, SessionClient, SessionRefusal, chooseSeatAction, playSeat, } from "./session.js";
+export { cardFromByte, decodeLegalActions, decodeParticipantView, encodeAction, pickAction, type Card, type Rank, type Suit, type TexasAction, type TexasLegalActions, type TexasSeatView, } from "./texas.js";
+export { authorityOriginFromSessionBase, buildConsentRequest, digestForPrompt, recomputeSettlementDigest, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
+export { PACKAGE_NAME, RELEASE_CHANNELS, channelDistTag, installCommand, installSpec, resolveChannel, versionMatchesChannel, type ReleaseChannel, } from "./channel.js";
+export { fromHex, toHex } from "./bytes.js";
+export { AGENT_HTTP_CAPABILITY_HEADER, AGENT_HTTP_CAPABILITY_NONCE_BYTES, MAX_AGENT_HTTP_CAPABILITY_WINDOW_MS, agentHttpCanonicalPayload, agentHttpSigningBytes, decodeAgentHttpHeader, encodeAgentHttpHeader, mintAgentHttpCapability, type AgentHttpBinding, type AgentHttpCapability, } from "./agentHttp.js";
+export { act, enterTour, foldHeavy, playTour, queueUntilSeated, readPosition, type TableMove, type TourClient, type TourEntry, type TourKind, type TurnView, } from "./tour.js";
+export { AGENT_CLAIM_INVITE_DOMAIN, AGENT_CLAIM_INVITE_MAX_WINDOW_MS, AGENT_CLAIM_INVITE_TOKEN_BYTES, claimInviteCanonicalPayload, claimInviteLink, claimInviteSigningBytes, decodeClaimInvite, encodeClaimInvite, mintClaimInvite, type ClaimInvite, } from "./claim.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+/* @dopamint-fun/open-sdk - the self-custody agent SDK for DOPA-OPEN.
+ *
+ * Generate and hold an ed25519 keypair (Sui format, `.dopa-keypair`), produce
+ * the canonical signatures, and drive the Participant Session against
+ * `session_base_url`. Byte parity with the Rust client is pinned by
+ * `libs/dopa-open-client-rs/vectors/ts-signer-parity.json`.
+ */
+export { DEFAULT_KEY_FILE, generateKeypair, keypairFromSeed, loadKeypair, saveKeypair, signOwnerAuthenticator, signRaw, } from "./keypair.js";
+export { deriveAgentId, registerCanonicalPayload, registerPayloadDigest, } from "./registration.js";
+export { canonicalIdentityPayload, nameAgent, parseIdentityFields, } from "./identity.js";
+export { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, resumeSigningBytes, } from "./sessionWire.js";
+export { encodeAckFrame, SESSION_ERROR_NAMES, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
+export { SessionClient, SessionRefusal, chooseSeatAction, playSeat, } from "./session.js";
+export { cardFromByte, decodeLegalActions, decodeParticipantView, encodeAction, pickAction, } from "./texas.js";
+export { authorityOriginFromSessionBase, buildConsentRequest, digestForPrompt, recomputeSettlementDigest, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
+export { PACKAGE_NAME, RELEASE_CHANNELS, channelDistTag, installCommand, installSpec, resolveChannel, versionMatchesChannel, } from "./channel.js";
+export { fromHex, toHex } from "./bytes.js";
+export { AGENT_HTTP_CAPABILITY_HEADER, AGENT_HTTP_CAPABILITY_NONCE_BYTES, MAX_AGENT_HTTP_CAPABILITY_WINDOW_MS, agentHttpCanonicalPayload, agentHttpSigningBytes, decodeAgentHttpHeader, encodeAgentHttpHeader, mintAgentHttpCapability, } from "./agentHttp.js";
+export { act, enterTour, foldHeavy, playTour, queueUntilSeated, readPosition, } from "./tour.js";
+/* The agent's half of a claim: an invitation its own key signs, carried as a
+   token in the claim link its operator hands the owner. */
+export { AGENT_CLAIM_INVITE_DOMAIN, AGENT_CLAIM_INVITE_MAX_WINDOW_MS, AGENT_CLAIM_INVITE_TOKEN_BYTES, claimInviteCanonicalPayload, claimInviteLink, claimInviteSigningBytes, decodeClaimInvite, encodeClaimInvite, mintClaimInvite, } from "./claim.js";

package/dist/keypair.d.ts

@@ -0,0 +1,25 @@
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+export declare const DEFAULT_KEY_FILE = ".dopa-keypair";
+export interface AgentKeypair {
+    keypair: Ed25519Keypair;
+    /** the ed25519 verifying key, 32 bytes - `agent_public_key` at registration */
+    publicKey: Uint8Array;
+    /** the derived Sui address bytes, 32 bytes - `owner` under path A custody */
+    ownerAddress: Uint8Array;
+    /** the same address, 0x-prefixed, for anything that prints it */
+    ownerAddressHex: string;
+}
+export declare function generateKeypair(): AgentKeypair;
+/** For tests and vectors: the deterministic keypair for a 32-byte seed. */
+export declare function keypairFromSeed(seed: Uint8Array): AgentKeypair;
+/** Write the key file: one `suiprivkey...` line, owner-readable only. The
+ *  format is Sui's own bech32, so every ecosystem tool that understands a Sui
+ *  key understands this file. */
+export declare function saveKeypair(agent: AgentKeypair, path?: string): void;
+export declare function loadKeypair(path?: string): AgentKeypair;
+/** Raw ed25519 over a canonical preimage - the session signatures. */
+export declare function signRaw(agent: AgentKeypair, preimage: Uint8Array): Promise<Uint8Array>;
+/** The registration authenticator: a Sui personal-message signature over the
+ *  canonical payload, base64-serialized the way `UserSignature::from_base64`
+ *  expects. The product checks the embedded public key derives `owner`. */
+export declare function signOwnerAuthenticator(agent: AgentKeypair, canonicalPayload: Uint8Array): Promise<string>;

package/dist/keypair.js

@@ -0,0 +1,69 @@
+/* The agent's own key: generate it, keep it, and sign with it.
+ *
+ * One Sui-format ed25519 keypair serves as both the allocating identity (its
+ * derived address is `owner`, and it signs the registration as a personal
+ * message) and the generation-1 action key (it signs session messages raw
+ * over the arena-session framings). Domain separation in the framings keeps
+ * the two roles apart. Note for rotation later: the original key remains the
+ * owner forever - `owner` is hashed into the agent id - even after the action
+ * key rotates to a new generation.
+ *
+ * The key file is `.dopa-keypair`, not `.dopa-credentials`. A bearer
+ * credential is per-deployment and server-revocable; a private key is
+ * portable and agent-owned. One file carrying both semantics is how one ends
+ * up pasted into the other's slot.
+ */
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { fromHex } from "./bytes.js";
+export const DEFAULT_KEY_FILE = ".dopa-keypair";
+function describe(keypair) {
+    const address = keypair.getPublicKey().toSuiAddress();
+    return {
+        keypair,
+        publicKey: keypair.getPublicKey().toRawBytes(),
+        ownerAddress: fromHex(address.replace(/^0x/, "")),
+        ownerAddressHex: address,
+    };
+}
+export function generateKeypair() {
+    return describe(new Ed25519Keypair());
+}
+/** For tests and vectors: the deterministic keypair for a 32-byte seed. */
+export function keypairFromSeed(seed) {
+    return describe(Ed25519Keypair.fromSecretKey(seed));
+}
+/** Write the key file: one `suiprivkey...` line, owner-readable only. The
+ *  format is Sui's own bech32, so every ecosystem tool that understands a Sui
+ *  key understands this file. */
+export function saveKeypair(agent, path = DEFAULT_KEY_FILE) {
+    writeFileSync(path, `${agent.keypair.getSecretKey()}\n`, { mode: 0o600 });
+    // mode on writeFileSync only applies at creation; an existing file keeps
+    // its bits, so tighten explicitly rather than trusting the happy path
+    chmodSync(path, 0o600);
+}
+export function loadKeypair(path = DEFAULT_KEY_FILE) {
+    const line = readFileSync(path, "utf8").trim();
+    if (line.startsWith("suiprivkey")) {
+        const decoded = decodeSuiPrivateKey(line);
+        if (decoded.scheme !== "ED25519")
+            throw new Error(`expected an ed25519 key in ${path}, found ${decoded.scheme}`);
+        return describe(Ed25519Keypair.fromSecretKey(decoded.secretKey));
+    }
+    const seed = fromHex(line.startsWith("0x") ? line.slice(2) : line);
+    if (seed.length !== 32)
+        throw new Error(`${path} must be a suiprivkey line or a 32-byte hex seed`);
+    return keypairFromSeed(seed);
+}
+/** Raw ed25519 over a canonical preimage - the session signatures. */
+export async function signRaw(agent, preimage) {
+    return agent.keypair.sign(preimage);
+}
+/** The registration authenticator: a Sui personal-message signature over the
+ *  canonical payload, base64-serialized the way `UserSignature::from_base64`
+ *  expects. The product checks the embedded public key derives `owner`. */
+export async function signOwnerAuthenticator(agent, canonicalPayload) {
+    const { signature } = await agent.keypair.signPersonalMessage(canonicalPayload);
+    return signature;
+}

package/dist/offer.d.ts

@@ -0,0 +1,36 @@
+import type { AgentKeypair } from "./keypair.js";
+export interface OfferSeat {
+    seat: number;
+    agentId: string;
+    keyGeneration: number;
+    agentPublicKey: string;
+}
+export interface OfferRecord {
+    state: string;
+    seats: OfferSeat[];
+    acceptedSeats: number[];
+    admission?: {
+        sessionBaseUrl: string;
+        coordinatorPublicKey: string;
+        timeAuthorityPublicKey?: string;
+        executionId: string;
+    };
+}
+export declare function readOffer(productUrl: string, offerId: string): Promise<OfferRecord>;
+/** Sign and submit this seat's acceptance. Already-accepted is not an error:
+ *  a retry after a lost response must not strand the seat. */
+export declare function acceptOffer(productUrl: string, offerId: string, seat: OfferSeat, agent: AgentKeypair): Promise<void>;
+export interface AdmittedSeat {
+    seat: number;
+    coordinatorKey: Uint8Array;
+    timeAuthorityKey: Uint8Array;
+    executionId: string;
+}
+export interface AwaitOptions {
+    pollMs?: number;
+    timeoutMs?: number;
+    onWaiting?: (accepted: number, total: number) => void;
+}
+/** Accept this agent's seat, then wait for the offer to admit, admitting it
+ *  as soon as every seat has accepted. */
+export declare function acceptAndAwaitAdmission(productUrl: string, offerId: string, agentId: Uint8Array, agent: AgentKeypair, options?: AwaitOptions): Promise<AdmittedSeat>;

package/dist/offer.js

@@ -0,0 +1,138 @@
+/* Taking a composed playground offer to a seat this agent can play.
+ *
+ * The queue pairs strangers and composes the offer; it stops there, because
+ * the acceptance and every later session frame have to be signed by a key the
+ * platform does not hold. So the three steps below are the agent's, not the
+ * product's: read the offer, accept it, and admit it once every seat has.
+ *
+ * `admit` is deliberately shared rather than assigned to one seat. Whoever
+ * gets there first admits and everybody reads the same admission back, which
+ * means no seat is load-bearing for the others - an agent that accepted and
+ * then died does not strand the table before it starts. The POST carries a
+ * freshly minted `AgentHttpCapability`; knowing the offer id is not enough.
+ */
+import { signOfferAcceptance } from "./acceptance.js";
+import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
+import { fromHex, toHex } from "./bytes.js";
+import { randomBytes } from "node:crypto";
+const hexBytes = (value) => fromHex(value.replace(/^0x/, ""));
+async function readJson(url, init) {
+    const response = await fetch(url, init);
+    const text = await response.text();
+    return {
+        status: response.status,
+        json: text.length === 0 ? undefined : JSON.parse(text),
+    };
+}
+function record(raw) {
+    const seats = (raw?.offer?.seats ?? []).map((seat) => ({
+        seat: seat.seat,
+        agentId: seat.agent_id ?? seat.agentId,
+        keyGeneration: seat.key_generation ?? seat.keyGeneration,
+        agentPublicKey: seat.agent_public_key ?? seat.agentPublicKey,
+    }));
+    const admissionRaw = raw?.admission;
+    return {
+        state: raw?.state,
+        seats,
+        acceptedSeats: (raw?.acceptances ?? []).map((entry) => entry.seat),
+        admission: admissionRaw
+            ? {
+                sessionBaseUrl: admissionRaw.session_base_url ?? admissionRaw.sessionBaseUrl,
+                coordinatorPublicKey: admissionRaw.coordinator_public_key ??
+                    admissionRaw.coordinatorPublicKey,
+                timeAuthorityPublicKey: admissionRaw.time_authority_public_key ??
+                    admissionRaw.timeAuthorityPublicKey ??
+                    undefined,
+                executionId: admissionRaw.execution_id ?? admissionRaw.executionId,
+            }
+            : undefined,
+    };
+}
+export async function readOffer(productUrl, offerId) {
+    const { status, json } = await readJson(`${productUrl.replace(/\/$/, "")}/open/v1/playground/matches/${offerId}`);
+    if (status !== 200)
+        throw new Error(`offer read refused (${status}): ${JSON.stringify(json)}`);
+    return record(json);
+}
+/** Sign and submit this seat's acceptance. Already-accepted is not an error:
+ *  a retry after a lost response must not strand the seat. */
+export async function acceptOffer(productUrl, offerId, seat, agent) {
+    const acceptance = {
+        offerId: hexBytes(offerId),
+        seat: seat.seat,
+        agentId: hexBytes(seat.agentId),
+        keyGeneration: seat.keyGeneration,
+        agentPublicKey: hexBytes(seat.agentPublicKey),
+        accepted: true,
+        acceptanceNonce: new Uint8Array(randomBytes(32)),
+    };
+    const signed = await signOfferAcceptance(agent, acceptance);
+    const body = JSON.stringify({
+        offer_id: offerId,
+        seat: signed.seat,
+        agent_id: seat.agentId,
+        key_generation: signed.keyGeneration,
+        agent_public_key: seat.agentPublicKey,
+        accepted: true,
+        acceptance_nonce: Array.from(signed.acceptanceNonce),
+        signature: Array.from(signed.signature),
+    });
+    const { status, json } = await readJson(`${productUrl.replace(/\/$/, "")}/open/v1/playground/matches/${offerId}/acceptances`, { method: "POST", headers: { "content-type": "application/json" }, body });
+    if (status === 200 || status === 201)
+        return;
+    if (status === 409)
+        return;
+    throw new Error(`acceptance refused (${status}): ${JSON.stringify(json)}`);
+}
+async function admit(productUrl, offerId, agentId, agent) {
+    const target = `/open/v1/playground/matches/${offerId}/admit`;
+    const { header } = await mintAgentHttpCapability(agent, agentId, {
+        method: "POST",
+        requestTarget: target,
+        body: new Uint8Array(),
+    });
+    const { status, json } = await readJson(`${productUrl.replace(/\/$/, "")}${target}`, { method: "POST", headers: { [AGENT_HTTP_CAPABILITY_HEADER]: header } });
+    // A seat that raced another to admit is not in trouble; the offer is admitted
+    // either way, and the next read returns the same admission.
+    if (status === 200 || status === 201 || status === 409)
+        return;
+    throw new Error(`admit refused (${status}): ${JSON.stringify(json)}`);
+}
+/** Accept this agent's seat, then wait for the offer to admit, admitting it
+ *  as soon as every seat has accepted. */
+export async function acceptAndAwaitAdmission(productUrl, offerId, agentId, agent, options = {}) {
+    const pollMs = options.pollMs ?? 2_000;
+    const deadline = Date.now() + (options.timeoutMs ?? 300_000);
+    const wanted = `0x${toHex(agentId)}`;
+    let offer = await readOffer(productUrl, offerId);
+    const mine = offer.seats.find((seat) => seat.agentId.toLowerCase() === wanted.toLowerCase());
+    if (!mine)
+        throw new Error(`offer ${offerId} holds no seat for ${wanted}`);
+    if (!offer.acceptedSeats.includes(mine.seat))
+        await acceptOffer(productUrl, offerId, mine, agent);
+    for (;;) {
+        offer = await readOffer(productUrl, offerId);
+        if (offer.admission) {
+            const { coordinatorPublicKey, timeAuthorityPublicKey, executionId } = offer.admission;
+            if (!timeAuthorityPublicKey)
+                throw new Error("the admission carried no time-authority key; this seat cannot authenticate arrival evidence");
+            return {
+                seat: mine.seat,
+                coordinatorKey: hexBytes(coordinatorPublicKey),
+                timeAuthorityKey: hexBytes(timeAuthorityPublicKey),
+                executionId,
+            };
+        }
+        if (offer.acceptedSeats.length >= offer.seats.length) {
+            await admit(productUrl, offerId, agentId, agent);
+            continue;
+        }
+        if (offer.state === "cancelled" || offer.state === "declined")
+            throw new Error(`the offer is ${offer.state}`);
+        options.onWaiting?.(offer.acceptedSeats.length, offer.seats.length);
+        if (Date.now() >= deadline)
+            throw new Error(`offer ${offerId} did not admit; ${offer.acceptedSeats.length} of ${offer.seats.length} seats accepted`);
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+}

package/dist/registration.d.ts

@@ -0,0 +1,53 @@
+/** Blake2b-256(domain, owner, nonce) - `AgentId::derive` in Rust. */
+export declare function deriveAgentId(owner: Uint8Array, allocationNonce: Uint8Array): Uint8Array;
+export interface RegisterAgentPayload {
+    /** 32 bytes; must equal deriveAgentId(owner, allocationNonce) */
+    agentId: Uint8Array;
+    /** 32 bytes */
+    allocationNonce: Uint8Array;
+    /** 32 bytes */
+    owner: Uint8Array;
+    /** 32 bytes - the ed25519 verifying key that will sign session messages */
+    agentPublicKey: Uint8Array;
+    /** each list strictly ascending, at least one entry */
+    productApiVersions: number[];
+    participantSessionVersions: number[];
+    protocolVersions: number[];
+    /** 32 bytes */
+    metadataCommitment: Uint8Array;
+    createdAtMs: number | bigint;
+    expiresAtMs?: number | bigint | null;
+}
+/** `RegisterAgentRequest::canonical_payload` - the bytes the owner signs as a
+ *  Sui personal message. */
+export declare function registerCanonicalPayload(payload: RegisterAgentPayload): Uint8Array;
+/** Blake2b-256 of the canonical payload - `payload_digest` in Rust. */
+export declare function registerPayloadDigest(payload: RegisterAgentPayload): Uint8Array;
+/** What a rotation binds: the agent, the generation it replaces, and the key
+ *  that takes over. */
+export interface RotateAgentKeyPayload {
+    agentId: Uint8Array;
+    owner: Uint8Array;
+    /** the generation the caller believes is current, refused when it is not */
+    expectedCurrentGeneration: number;
+    predecessorAuthorizationDigest: Uint8Array;
+    nextAgentPublicKey: Uint8Array;
+    issuedAtMs: number | bigint;
+    expiresAtMs: number | bigint;
+}
+/** `RotateAgentKeyRequest::canonical_payload` — the bytes the key holder signs
+ *  as a Sui personal message. */
+export declare function rotateCanonicalPayload(payload: RotateAgentKeyPayload): Uint8Array;
+/** What a retirement binds. No successor key: nothing follows a retirement. */
+export interface RevokeAgentPayload {
+    agentId: Uint8Array;
+    owner: Uint8Array;
+    expectedCurrentGeneration: number;
+    predecessorAuthorizationDigest: Uint8Array;
+    issuedAtMs: number | bigint;
+    expiresAtMs: number | bigint;
+}
+/** `RevokeAgentRequest::canonical_payload`. Same shape as a rotation without
+ *  the successor, and a different domain and operation tag -- so a signature
+ *  taken for one cannot be replayed as the other. */
+export declare function revokeCanonicalPayload(payload: RevokeAgentPayload): Uint8Array;

package/dist/registration.js

@@ -0,0 +1,104 @@
+/* The registration canonical payload and the agent identity it binds,
+ * byte-identical to `dopa_open_api`.
+ *
+ * Path A custody: the agent allocates itself. The address derived from its
+ * own key is the `owner`, so the same key both authorizes the registration
+ * (as a Sui personal-message signature the product verifies with
+ * `verify_owner_authenticator`) and later signs every session message. The
+ * agent id is a Blake2b-256 over the owner and an allocation nonce - `owner`
+ * is hashed into the identity, which is why it can never be rewritten and why
+ * claim-later binds a human separately.
+ */
+import { blake2b } from "@noble/hashes/blake2.js";
+import { ByteWriter, textBytes } from "./bytes.js";
+const AGENT_ID_DOMAIN = textBytes("dopa_open::agent_id::v1");
+const REGISTER_DOMAIN = textBytes("dopa_open::registration::v1");
+const CANONICAL_WIRE_VERSION = 1;
+const REGISTER_OPERATION = 1;
+const ROTATE_DOMAIN = textBytes("dopa_open::key_rotation::v1");
+const ROTATE_OPERATION = 2;
+const REVOKE_DOMAIN = textBytes("dopa_open::revocation::v1");
+const REVOKE_OPERATION = 3;
+/** Blake2b-256(domain, owner, nonce) - `AgentId::derive` in Rust. */
+export function deriveAgentId(owner, allocationNonce) {
+    if (owner.length !== 32)
+        throw new Error("owner must be 32 bytes");
+    if (allocationNonce.length !== 32)
+        throw new Error("allocation nonce must be 32 bytes");
+    const input = new Uint8Array(AGENT_ID_DOMAIN.length + owner.length + allocationNonce.length);
+    input.set(AGENT_ID_DOMAIN, 0);
+    input.set(owner, AGENT_ID_DOMAIN.length);
+    input.set(allocationNonce, AGENT_ID_DOMAIN.length + owner.length);
+    return blake2b(input, { dkLen: 32 });
+}
+function pushVersions(writer, versions) {
+    if (versions.length === 0 || versions.length > 0xff)
+        throw new Error("version list must hold 1 to 255 entries");
+    writer.pushByte(versions.length);
+    for (const version of versions)
+        writer.pushU16(version);
+}
+/** `RegisterAgentRequest::canonical_payload` - the bytes the owner signs as a
+ *  Sui personal message. */
+export function registerCanonicalPayload(payload) {
+    const writer = new ByteWriter()
+        .pushBytes(REGISTER_DOMAIN)
+        .pushByte(0)
+        .pushByte(CANONICAL_WIRE_VERSION)
+        .pushByte(REGISTER_OPERATION)
+        .pushFixed(payload.agentId, 32, "agent id")
+        .pushFixed(payload.allocationNonce, 32, "allocation nonce")
+        .pushFixed(payload.owner, 32, "owner")
+        .pushFixed(payload.agentPublicKey, 32, "agent public key");
+    pushVersions(writer, payload.productApiVersions);
+    pushVersions(writer, payload.participantSessionVersions);
+    pushVersions(writer, payload.protocolVersions);
+    writer
+        .pushFixed(payload.metadataCommitment, 32, "metadata commitment")
+        .pushU64(payload.createdAtMs);
+    if (payload.expiresAtMs === undefined || payload.expiresAtMs === null) {
+        writer.pushByte(0);
+    }
+    else {
+        writer.pushByte(1).pushU64(payload.expiresAtMs);
+    }
+    return writer.bytes();
+}
+/** Blake2b-256 of the canonical payload - `payload_digest` in Rust. */
+export function registerPayloadDigest(payload) {
+    return blake2b(registerCanonicalPayload(payload), { dkLen: 32 });
+}
+/** `RotateAgentKeyRequest::canonical_payload` — the bytes the key holder signs
+ *  as a Sui personal message. */
+export function rotateCanonicalPayload(payload) {
+    return new ByteWriter()
+        .pushBytes(ROTATE_DOMAIN)
+        .pushByte(0)
+        .pushByte(CANONICAL_WIRE_VERSION)
+        .pushByte(ROTATE_OPERATION)
+        .pushFixed(payload.agentId, 32, "agent id")
+        .pushFixed(payload.owner, 32, "owner")
+        .pushU32(payload.expectedCurrentGeneration)
+        .pushFixed(payload.predecessorAuthorizationDigest, 32, "predecessor authorization digest")
+        .pushFixed(payload.nextAgentPublicKey, 32, "next agent public key")
+        .pushU64(payload.issuedAtMs)
+        .pushU64(payload.expiresAtMs)
+        .bytes();
+}
+/** `RevokeAgentRequest::canonical_payload`. Same shape as a rotation without
+ *  the successor, and a different domain and operation tag -- so a signature
+ *  taken for one cannot be replayed as the other. */
+export function revokeCanonicalPayload(payload) {
+    return new ByteWriter()
+        .pushBytes(REVOKE_DOMAIN)
+        .pushByte(0)
+        .pushByte(CANONICAL_WIRE_VERSION)
+        .pushByte(REVOKE_OPERATION)
+        .pushFixed(payload.agentId, 32, "agent id")
+        .pushFixed(payload.owner, 32, "owner")
+        .pushU32(payload.expectedCurrentGeneration)
+        .pushFixed(payload.predecessorAuthorizationDigest, 32, "predecessor authorization digest")
+        .pushU64(payload.issuedAtMs)
+        .pushU64(payload.expiresAtMs)
+        .bytes();
+}

package/dist/seatAuth.d.ts

@@ -0,0 +1,30 @@
+import type { ArtifactReference } from "./sessionWire.js";
+export declare const DOPA_OPEN_COORDINATOR_ROLE: Uint8Array<ArrayBuffer>;
+export declare const DOPA_OPEN_TIME_AUTHORITY_ROLE: Uint8Array<ArrayBuffer>;
+export declare function seatGenerationDigest(generation?: number): Uint8Array;
+export declare function roleGenerationDigest(role: Uint8Array): Uint8Array;
+export declare function coordinatorGenerationDigest(): Uint8Array;
+export declare function timeAuthorityGenerationDigest(): Uint8Array;
+export declare function transitionProofSigningBytes(payload: Uint8Array, principal: Uint8Array, generation: Uint8Array, scheme?: number): Uint8Array;
+export interface PendingProposal {
+    actionId: Uint8Array;
+    actionPayload: Uint8Array;
+    signingBytes: Uint8Array;
+    expectedStateNonce: bigint;
+    expectedStateCommitment: Uint8Array;
+    participantDeadlineMs: bigint;
+    payloadSchemaVersion: number;
+    executionId: Uint8Array;
+    protocolId: Uint8Array;
+    protocolVersion: number;
+    artifactReferences: ArtifactReference[];
+}
+export declare function authorizeSeatChallenge(args: {
+    seat: number;
+    coordinatorPublicKey: Uint8Array;
+    challengeCoordinatorKey: Uint8Array;
+    coordinatorProof: Uint8Array;
+    authorizationPayload: Uint8Array;
+    timeAuthorityPublicKey: Uint8Array;
+    pending: PendingProposal;
+}): Uint8Array;