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

package/dist/claim.d.ts

@@ -0,0 +1,39 @@
+import type { AgentKeypair } from "./keypair.js";
+export declare const AGENT_CLAIM_INVITE_DOMAIN: Uint8Array<ArrayBufferLike>;
+export declare const AGENT_CLAIM_INVITE_NONCE_BYTES = 16;
+/** The longest an invitation may stay open: a week. */
+export declare const AGENT_CLAIM_INVITE_MAX_WINDOW_MS: number;
+/** `agent_id || owner-or-zero || agent_public_key || issued || expires ||
+ *  nonce || signature`, every field fixed-width. */
+export declare const AGENT_CLAIM_INVITE_TOKEN_BYTES: number;
+export interface ClaimInvite {
+    /** 32 bytes */
+    agentId: Uint8Array;
+    /** 32 bytes, or null for whoever holds the token */
+    owner: Uint8Array | null;
+    /** 32 bytes: the key that signed, which must be the agent's current one */
+    agentPublicKey: Uint8Array;
+    issuedAtMs: bigint;
+    expiresAtMs: bigint;
+    /** 16 bytes, never all zero */
+    nonce: Uint8Array;
+    /** 64 bytes; empty until signed */
+    signature: Uint8Array;
+}
+/** `AgentClaimInvite::canonical_payload` -- the framed fields. */
+export declare function claimInviteCanonicalPayload(invite: ClaimInvite): Uint8Array;
+/** The bytes the agent's key signs, raw ed25519. */
+export declare function claimInviteSigningBytes(invite: ClaimInvite): Uint8Array;
+export declare function mintClaimInvite(agent: AgentKeypair, agentId: Uint8Array, options?: {
+    /** the one wallet that may accept; omit for whoever holds the link */
+    owner?: Uint8Array | null;
+    issuedAtMs?: number;
+    /** how long the link stays good; a day unless said otherwise */
+    ttlMs?: number;
+    nonce?: Uint8Array;
+}): Promise<ClaimInvite>;
+/** The token the link carries and the claim body posts back: 0x-hex. */
+export declare function encodeClaimInvite(invite: ClaimInvite): string;
+export declare function decodeClaimInvite(token: string): ClaimInvite;
+/** Where the owner goes to accept: the agent's claim page with the token. */
+export declare function claimInviteLink(arenaOrigin: string, agentIdHex: string, token: string): string;

package/dist/claim.js

@@ -0,0 +1,91 @@
+import { randomBytes } from "node:crypto";
+import { signRaw } from "./keypair.js";
+import { concatBytes, equalBytes, frameSigningBytes, fromHex, textBytes, toHex0x, } from "./bytes.js";
+/* The agent's half of a claim: an invitation its own key signs.
+ *
+ * A wallet claims an agent by signing for it in the arena's UI. That proves
+ * the wallet wants the agent and nothing about whether you, holding the
+ * agent's key, agree -- so any wallet could once claim any unclaimed agent
+ * off the roster. Now a claim is accepted only with an invitation your key
+ * minted: name the wallet allowed to accept (or nobody, for whoever holds the
+ * link), pick a window, and hand the owner the link this prints.
+ *
+ * Mirrors `AgentClaimInvite` in `dopa_open_api::claim`: the same bytes, the
+ * same token, pinned by a shared vector in the tests. */
+export const AGENT_CLAIM_INVITE_DOMAIN = textBytes("dopa_open::agent_claim_invite::v1");
+const CANONICAL_WIRE_VERSION = 1;
+const INVITE_OPERATION = 4;
+export const AGENT_CLAIM_INVITE_NONCE_BYTES = 16;
+/** The longest an invitation may stay open: a week. */
+export const AGENT_CLAIM_INVITE_MAX_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/** `agent_id || owner-or-zero || agent_public_key || issued || expires ||
+ *  nonce || signature`, every field fixed-width. */
+export const AGENT_CLAIM_INVITE_TOKEN_BYTES = 32 + 32 + 32 + 8 + 8 + 16 + 64;
+const ZERO_OWNER = new Uint8Array(32);
+function u64be(value) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, value, false);
+    return out;
+}
+function fixed(bytes, length, what) {
+    if (bytes.length !== length)
+        throw new Error(`${what} must be ${length} bytes, got ${bytes.length}`);
+    return bytes;
+}
+/** `AgentClaimInvite::canonical_payload` -- the framed fields. */
+export function claimInviteCanonicalPayload(invite) {
+    if (invite.expiresAtMs <= invite.issuedAtMs)
+        throw new Error("the invitation's window is empty");
+    if (invite.expiresAtMs - invite.issuedAtMs >
+        BigInt(AGENT_CLAIM_INVITE_MAX_WINDOW_MS))
+        throw new Error("an invitation may stay open for at most a week");
+    if (invite.nonce.every((byte) => byte === 0))
+        throw new Error("the invitation's nonce must not be all zero");
+    return concatBytes(AGENT_CLAIM_INVITE_DOMAIN, Uint8Array.of(0, CANONICAL_WIRE_VERSION, INVITE_OPERATION), fixed(invite.agentId, 32, "agent id"), invite.owner ? fixed(invite.owner, 32, "owner") : ZERO_OWNER, fixed(invite.agentPublicKey, 32, "agent public key"), u64be(invite.issuedAtMs), u64be(invite.expiresAtMs), fixed(invite.nonce, AGENT_CLAIM_INVITE_NONCE_BYTES, "nonce"));
+}
+/** The bytes the agent's key signs, raw ed25519. */
+export function claimInviteSigningBytes(invite) {
+    return frameSigningBytes(AGENT_CLAIM_INVITE_DOMAIN, claimInviteCanonicalPayload(invite));
+}
+export async function mintClaimInvite(agent, agentId, options = {}) {
+    const issuedAtMs = BigInt(options.issuedAtMs ?? Date.now());
+    const ttl = options.ttlMs ?? 24 * 60 * 60 * 1000;
+    const invite = {
+        agentId,
+        owner: options.owner ?? null,
+        agentPublicKey: agent.publicKey,
+        issuedAtMs,
+        expiresAtMs: issuedAtMs + BigInt(ttl),
+        nonce: options.nonce ?? new Uint8Array(randomBytes(16)),
+        signature: new Uint8Array(),
+    };
+    invite.signature = await signRaw(agent, claimInviteSigningBytes(invite));
+    return invite;
+}
+/** The token the link carries and the claim body posts back: 0x-hex. */
+export function encodeClaimInvite(invite) {
+    if (invite.signature.length !== 64)
+        throw new Error("an invitation is encoded only once it is signed");
+    return toHex0x(concatBytes(fixed(invite.agentId, 32, "agent id"), invite.owner ?? ZERO_OWNER, fixed(invite.agentPublicKey, 32, "agent public key"), u64be(invite.issuedAtMs), u64be(invite.expiresAtMs), fixed(invite.nonce, 16, "nonce"), invite.signature));
+}
+export function decodeClaimInvite(token) {
+    const bytes = fromHex(token.trim());
+    if (bytes.length !== AGENT_CLAIM_INVITE_TOKEN_BYTES)
+        throw new Error(`an invitation token is ${AGENT_CLAIM_INVITE_TOKEN_BYTES} bytes, got ${bytes.length}`);
+    const view = new DataView(bytes.buffer, bytes.byteOffset);
+    const owner = bytes.slice(32, 64);
+    return {
+        agentId: bytes.slice(0, 32),
+        owner: equalBytes(owner, ZERO_OWNER) ? null : owner,
+        agentPublicKey: bytes.slice(64, 96),
+        issuedAtMs: view.getBigUint64(96, false),
+        expiresAtMs: view.getBigUint64(104, false),
+        nonce: bytes.slice(112, 128),
+        signature: bytes.slice(128),
+    };
+}
+/** Where the owner goes to accept: the agent's claim page with the token. */
+export function claimInviteLink(arenaOrigin, agentIdHex, token) {
+    const id = agentIdHex.startsWith("0x") ? agentIdHex : `0x${agentIdHex}`;
+    return `${arenaOrigin.replace(/\/$/, "")}/arena/agents/${id}/claim?invite=${token}`;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};