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

package/README.md

@@ -0,0 +1,42 @@
+# `libs/dopa-open-client-ts`
+
+Status: implemented
+Ownership: Optional official TypeScript SDK for DOPA-OPEN self-custody agents:
+key custody, canonical signatures, and the Participant Session loop. Never a
+required gateway — server admission checks protocol conformance and
+signatures, not whether this package is used. Allowed dependencies:
+`@mysten/sui` and `@noble/hashes` only. Never product-private packages.
+
+## Surface
+
+- `generateKeypair` / `saveKeypair` / `loadKeypair` — one Sui-format Ed25519
+  keypair in `.dopa-keypair` (mode 0600). Under self-custody its derived
+  address is the registration `owner` and the key is the generation-1 action
+  key (ADR-0169).
+- `deriveAgentId` / `registerCanonicalPayload` / `signOwnerAuthenticator` —
+  self-allocation and the registration the product verifies.
+- `joinSigningBytes` / `actionSigningBytes` / `resumeSigningBytes` +
+  `signRaw` — the Participant Session signatures.
+- `playSeat` / `SessionClient` — the HTTP session loop against
+  `session_base_url` (join, act, ack, resume, seat-authorization).
+- `recomputeSettlementDigest` / `buildConsentRequest` — settlement consent
+  over the disclosed terminal-state preimage.
+- `channel.ts` — the npm channel-to-install mapping every teaching surface
+  reads (`prod` = bare install, `dev`/`canary` = dist tags, local tarball
+  override).
+- `dopa-open` CLI — `keygen`, `address`, `register`, `play`, `consent`, `sign`.
+
+## Parity
+
+Preimages and signatures are pinned byte-identical to the Rust signer by
+`libs/dopa-open-client-rs/vectors/ts-signer-parity.json`, generated by
+`libs/dopa-open-client-rs/tests/ts_parity_vectors.rs` and replayed by
+`src/parity.test.ts` here. Regenerate with
+`WRITE_TS_PARITY_VECTORS=1 cargo test -p dopa-open-client-rs --test
+ts_parity_vectors`; a wire change updates both sides together.
+
+## Publishing
+
+`bun run scripts/workflow/publish-open-sdk.mjs --channel <canary|dev|prod>`
+(mutate-gated). `--pack-only` builds the tarball a local stack teaches via
+`DOPA_OPEN_SDK_INSTALL`.

package/dist/acceptance.d.ts

@@ -0,0 +1,24 @@
+import { type AgentKeypair } from "./keypair.js";
+export declare const ACCEPTANCE_NONCE_BYTES = 32;
+export interface OfferAcceptance {
+    /** 32 bytes */
+    offerId: Uint8Array;
+    /** 1-based seat index, as the offer states it */
+    seat: number;
+    /** 32 bytes */
+    agentId: Uint8Array;
+    /** the generation the offer admitted this seat under */
+    keyGeneration: number;
+    /** 32 bytes */
+    agentPublicKey: Uint8Array;
+    accepted: boolean;
+    /** 32 bytes */
+    acceptanceNonce: Uint8Array;
+}
+export declare function offerAcceptanceCanonicalPayload(acceptance: OfferAcceptance): Uint8Array;
+export declare function offerAcceptanceSigningBytes(acceptance: OfferAcceptance): Uint8Array;
+export interface SignedOfferAcceptance extends OfferAcceptance {
+    /** 64 bytes */
+    signature: Uint8Array;
+}
+export declare function signOfferAcceptance(agent: AgentKeypair, acceptance: OfferAcceptance): Promise<SignedOfferAcceptance>;

package/dist/acceptance.js

@@ -0,0 +1,48 @@
+/* Accepting a match offer with the agent's own key.
+ *
+ * This is what makes a playground seat possible without platform custody. The
+ * offer names a seat, an agent id and the key generation the product admitted;
+ * accepting it signs those four facts together, so an acceptance cannot be
+ * lifted onto another seat, another offer, or a rotated key. The authority
+ * verifies the signature against the registered public key, which is why the
+ * platform cannot produce one for an agent whose key it does not hold.
+ *
+ * Byte-identical to `OfferAcceptance::canonical_payload` in `dopa_open_api`;
+ * `acceptance.test.ts` pins it against a Rust-generated vector.
+ */
+import { ByteWriter, frameSigningBytes, textBytes } from "./bytes.js";
+import { signRaw } from "./keypair.js";
+const OFFER_ACCEPTANCE_DOMAIN = textBytes("dopa_open::offer_acceptance::v1");
+const CANONICAL_WIRE_VERSION = 1;
+const OFFER_ACCEPTANCE_OPERATION = 5;
+export const ACCEPTANCE_NONCE_BYTES = 32;
+export function offerAcceptanceCanonicalPayload(acceptance) {
+    if (!Number.isInteger(acceptance.seat) || acceptance.seat < 1 || acceptance.seat > 0xff)
+        throw new Error("seat must be a 1-byte index");
+    if (!Number.isInteger(acceptance.keyGeneration) ||
+        acceptance.keyGeneration < 0 ||
+        acceptance.keyGeneration > 0xffff_ffff)
+        throw new Error("key generation must fit in u32");
+    return new ByteWriter()
+        .pushBytes(OFFER_ACCEPTANCE_DOMAIN)
+        .pushByte(0)
+        .pushByte(CANONICAL_WIRE_VERSION)
+        .pushByte(OFFER_ACCEPTANCE_OPERATION)
+        .pushFixed(acceptance.offerId, 32, "offer id")
+        .pushByte(acceptance.seat)
+        .pushFixed(acceptance.agentId, 32, "agent id")
+        .pushU32(acceptance.keyGeneration)
+        .pushFixed(acceptance.agentPublicKey, 32, "agent public key")
+        .pushByte(acceptance.accepted ? 1 : 0)
+        .pushFixed(acceptance.acceptanceNonce, ACCEPTANCE_NONCE_BYTES, "acceptance nonce")
+        .bytes();
+}
+export function offerAcceptanceSigningBytes(acceptance) {
+    return frameSigningBytes(OFFER_ACCEPTANCE_DOMAIN, offerAcceptanceCanonicalPayload(acceptance));
+}
+export async function signOfferAcceptance(agent, acceptance) {
+    return {
+        ...acceptance,
+        signature: await signRaw(agent, offerAcceptanceSigningBytes(acceptance)),
+    };
+}

package/dist/agentHttp.d.ts

@@ -0,0 +1,52 @@
+import { type AgentKeypair } from "./keypair.js";
+/** The request header an agent HTTP capability travels in. */
+export declare const AGENT_HTTP_CAPABILITY_HEADER = "x-dopa-open-agent-capability";
+/** The widest window a signer may claim. Without a cap, freshness would reduce
+ *  to the signer's own opinion of how long its capability should live. */
+export declare const MAX_AGENT_HTTP_CAPABILITY_WINDOW_MS = 120000;
+export declare const AGENT_HTTP_CAPABILITY_NONCE_BYTES = 16;
+/** The request a capability authorizes, as the server will reconstruct it. */
+export interface AgentHttpBinding {
+    method: string;
+    /** Origin-form target: path plus query string when one is present. */
+    requestTarget: string;
+    body: Uint8Array;
+}
+export interface AgentHttpCapability {
+    /** 32 bytes */
+    agentId: Uint8Array;
+    /** 32 bytes */
+    agentPublicKey: Uint8Array;
+    issuedAtMs: number | bigint;
+    expiresAtMs: number | bigint;
+    /** 16 bytes, single-use */
+    nonce: Uint8Array;
+    /** 64 bytes */
+    signature: Uint8Array;
+}
+/** `AgentHttpCapability::canonical_payload`. */
+export declare function agentHttpCanonicalPayload(capability: Omit<AgentHttpCapability, "signature">, binding: AgentHttpBinding): Uint8Array;
+/** `AgentHttpCapability::signing_preimage` - what the agent key signs. */
+export declare function agentHttpSigningBytes(capability: Omit<AgentHttpCapability, "signature">, binding: AgentHttpBinding): Uint8Array;
+/** `0x`-hex of `agent_id || agent_public_key || issued_at_ms ||
+ *  expires_at_ms || nonce || signature`, big-endian. The fixed layout is its
+ *  own length check. */
+export declare function encodeAgentHttpHeader(capability: AgentHttpCapability): string;
+export declare function decodeAgentHttpHeader(value: string): AgentHttpCapability;
+export interface MintAgentHttpCapabilityOptions {
+    /** Defaults to now. */
+    issuedAtMs?: number | bigint;
+    /** Defaults to the maximum window the server admits. */
+    windowMs?: number;
+    /** Defaults to 16 fresh random bytes. Supply one only to reproduce a vector. */
+    nonce?: Uint8Array;
+}
+/** Mint and sign one capability, and return the header to send with it.
+ *
+ *  The nonce is single-use: the server records it and refuses a second
+ *  presentation, so callers must mint a fresh capability per request rather
+ *  than caching one for the window's duration. */
+export declare function mintAgentHttpCapability(agent: AgentKeypair, agentId: Uint8Array, binding: AgentHttpBinding, options?: MintAgentHttpCapabilityOptions): Promise<{
+    capability: AgentHttpCapability;
+    header: string;
+}>;

package/dist/agentHttp.js

@@ -0,0 +1,139 @@
+/* The agent-key HTTP capability: how a self-custodied agent authorizes one
+ * tour or table request without ever holding a bearer credential.
+ *
+ * Byte-identical to `dopa_open_api::agent_http`, pinned by
+ * `libs/dopa-open-api/vectors/agent_http_capability_v1.json`. A bearer token
+ * is a secret presented per request; a signature is not, so each capability is
+ * bound to the method, the request target, a digest of the exact body bytes,
+ * and a single-use nonce inside a bounded window. One minted to enter the
+ * playground therefore cannot act at a table, and a captured request cannot be
+ * replayed inside its own validity window.
+ *
+ * Method, target and body are deliberately absent from the wire struct: the
+ * server reconstructs them from the request it actually received, so there is
+ * no restated copy to compare and therefore no comparison to forget.
+ */
+import { ByteWriter, frameSigningBytes, fromHex, textBytes, toHex } from "./bytes.js";
+import { blake2b256 } from "./crypto.js";
+import { signRaw } from "./keypair.js";
+const AGENT_HTTP_CAPABILITY_DOMAIN = textBytes("dopa_open::agent_http_capability::v1");
+const CANONICAL_WIRE_VERSION = 1;
+const AGENT_HTTP_CAPABILITY_OPERATION = 1;
+/** The request header an agent HTTP capability travels in. */
+export const AGENT_HTTP_CAPABILITY_HEADER = "x-dopa-open-agent-capability";
+/** The widest window a signer may claim. Without a cap, freshness would reduce
+ *  to the signer's own opinion of how long its capability should live. */
+export const MAX_AGENT_HTTP_CAPABILITY_WINDOW_MS = 120_000;
+export const AGENT_HTTP_CAPABILITY_NONCE_BYTES = 16;
+const SIGNATURE_BYTES = 64;
+const HEADER_BYTES = 32 + 32 + 8 + 8 + AGENT_HTTP_CAPABILITY_NONCE_BYTES + SIGNATURE_BYTES;
+const asBigInt = (value) => typeof value === "bigint" ? value : BigInt(value);
+/** The same refusals `AgentHttpCapability::validate` makes, so a capability
+ *  this package mints is never one the server would reject on shape alone. */
+function validateUnsigned(capability) {
+    if (capability.agentId.length !== 32)
+        throw new Error("agent id must be 32 bytes");
+    if (capability.agentPublicKey.length !== 32)
+        throw new Error("agent public key must be 32 bytes");
+    if (capability.nonce.length !== AGENT_HTTP_CAPABILITY_NONCE_BYTES)
+        throw new Error(`nonce must be ${AGENT_HTTP_CAPABILITY_NONCE_BYTES} bytes`);
+    if (capability.nonce.every((byte) => byte === 0))
+        throw new Error("nonce must not be all zero");
+    const issued = asBigInt(capability.issuedAtMs);
+    const expires = asBigInt(capability.expiresAtMs);
+    if (expires <= issued)
+        throw new Error("expires_at_ms must be after issued_at_ms");
+    if (expires - issued > BigInt(MAX_AGENT_HTTP_CAPABILITY_WINDOW_MS))
+        throw new Error(`capability window must not exceed ${MAX_AGENT_HTTP_CAPABILITY_WINDOW_MS} ms`);
+}
+/** `AgentHttpCapability::canonical_payload`. */
+export function agentHttpCanonicalPayload(capability, binding) {
+    validateUnsigned(capability);
+    const method = textBytes(binding.method);
+    const target = textBytes(binding.requestTarget);
+    return new ByteWriter()
+        .pushBytes(AGENT_HTTP_CAPABILITY_DOMAIN)
+        .pushByte(0)
+        .pushByte(CANONICAL_WIRE_VERSION)
+        .pushByte(AGENT_HTTP_CAPABILITY_OPERATION)
+        .pushU32(method.length)
+        .pushBytes(method)
+        .pushU32(target.length)
+        .pushBytes(target)
+        .pushFixed(blake2b256(binding.body), 32, "body digest")
+        .pushFixed(capability.agentId, 32, "agent id")
+        .pushFixed(capability.agentPublicKey, 32, "agent public key")
+        .pushU64(capability.issuedAtMs)
+        .pushU64(capability.expiresAtMs)
+        .pushFixed(capability.nonce, AGENT_HTTP_CAPABILITY_NONCE_BYTES, "nonce")
+        .bytes();
+}
+/** `AgentHttpCapability::signing_preimage` - what the agent key signs. */
+export function agentHttpSigningBytes(capability, binding) {
+    return frameSigningBytes(AGENT_HTTP_CAPABILITY_DOMAIN, agentHttpCanonicalPayload(capability, binding));
+}
+/** `0x`-hex of `agent_id || agent_public_key || issued_at_ms ||
+ *  expires_at_ms || nonce || signature`, big-endian. The fixed layout is its
+ *  own length check. */
+export function encodeAgentHttpHeader(capability) {
+    if (capability.signature.length !== SIGNATURE_BYTES)
+        throw new Error(`signature must be ${SIGNATURE_BYTES} bytes`);
+    validateUnsigned(capability);
+    return `0x${toHex(new ByteWriter()
+        .pushFixed(capability.agentId, 32, "agent id")
+        .pushFixed(capability.agentPublicKey, 32, "agent public key")
+        .pushU64(capability.issuedAtMs)
+        .pushU64(capability.expiresAtMs)
+        .pushFixed(capability.nonce, AGENT_HTTP_CAPABILITY_NONCE_BYTES, "nonce")
+        .pushBytes(capability.signature)
+        .bytes())}`;
+}
+export function decodeAgentHttpHeader(value) {
+    if (!value.startsWith("0x") || /[A-F]/.test(value))
+        throw new Error("capability header must be lowercase 0x-hex");
+    const bytes = fromHex(value);
+    if (bytes.length !== HEADER_BYTES)
+        throw new Error(`capability header must be ${HEADER_BYTES} bytes, got ${bytes.length}`);
+    const readU64 = (offset) => {
+        let out = 0n;
+        for (let index = 0; index < 8; index++)
+            out = (out << 8n) | BigInt(bytes[offset + index]);
+        return out;
+    };
+    return {
+        agentId: bytes.slice(0, 32),
+        agentPublicKey: bytes.slice(32, 64),
+        issuedAtMs: readU64(64),
+        expiresAtMs: readU64(72),
+        nonce: bytes.slice(80, 80 + AGENT_HTTP_CAPABILITY_NONCE_BYTES),
+        signature: bytes.slice(80 + AGENT_HTTP_CAPABILITY_NONCE_BYTES),
+    };
+}
+/** Mint and sign one capability, and return the header to send with it.
+ *
+ *  The nonce is single-use: the server records it and refuses a second
+ *  presentation, so callers must mint a fresh capability per request rather
+ *  than caching one for the window's duration. */
+export async function mintAgentHttpCapability(agent, agentId, binding, options = {}) {
+    const issuedAtMs = options.issuedAtMs ?? Date.now();
+    const windowMs = options.windowMs ?? MAX_AGENT_HTTP_CAPABILITY_WINDOW_MS;
+    const unsigned = {
+        agentId,
+        agentPublicKey: agent.publicKey,
+        issuedAtMs,
+        expiresAtMs: asBigInt(issuedAtMs) + BigInt(windowMs),
+        nonce: options.nonce ?? randomNonce(),
+    };
+    const signature = await signRaw(agent, agentHttpSigningBytes(unsigned, binding));
+    const capability = { ...unsigned, signature };
+    return { capability, header: encodeAgentHttpHeader(capability) };
+}
+function randomNonce() {
+    const nonce = new Uint8Array(AGENT_HTTP_CAPABILITY_NONCE_BYTES);
+    globalThis.crypto.getRandomValues(nonce);
+    // An all-zero draw is refused by the server, and is astronomically unlikely
+    // rather than impossible; bias the last byte rather than reject-and-retry.
+    if (nonce.every((byte) => byte === 0))
+        nonce[nonce.length - 1] = 1;
+    return nonce;
+}

package/dist/bytes.d.ts

@@ -0,0 +1,40 @@
+export declare function toHex(bytes: Uint8Array): string;
+export declare function fromHex(hex: string): Uint8Array;
+export declare function toHex0x(bytes: Uint8Array): string;
+/** Length-aware equality. `every()` on an empty left-hand side is vacuously
+ *  true, which would accept a truncated hex decode as a matching key. */
+export declare function equalBytes(left: Uint8Array, right: Uint8Array): boolean;
+/** An append-only byte buffer with the wire's own vocabulary. */
+export declare class ByteWriter {
+    private chunks;
+    pushByte(value: number): this;
+    pushU16(value: number): this;
+    pushU32(value: number): this;
+    pushU64(value: number | bigint): this;
+    pushBytes(bytes: Uint8Array): this;
+    /** A fixed-width field: the wire reads exactly `length` bytes, so writing
+     *  any other count would silently shift every field after it. */
+    pushFixed(bytes: Uint8Array, length: number, field: string): this;
+    bytes(): Uint8Array;
+}
+/** Strict reader for one canonical frame. Trailing bytes are a decode error. */
+export declare class ByteReader {
+    private readonly source;
+    private offset;
+    constructor(source: Uint8Array);
+    remaining(): number;
+    consumed(): number;
+    readByte(field: string): number;
+    readU16(field: string): number;
+    readU32(field: string): number;
+    readU64(field: string): bigint;
+    readFixed(length: number, field: string): Uint8Array;
+    readLengthPrefixed(lengthField: string, bytesField: string): Uint8Array;
+    finish(): void;
+}
+export declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
+/** The shared signing frame: length-prefixed domain, then length-prefixed
+ *  payload. Identical between `arena_session::wire::frame_signing_bytes` and
+ *  `dopa_open_api::encoding::signed_preimage` on purpose - one shape to pin. */
+export declare function frameSigningBytes(domain: Uint8Array, payload: Uint8Array): Uint8Array;
+export declare const textBytes: (value: string) => Uint8Array;

package/dist/bytes.js

@@ -0,0 +1,166 @@
+/* Byte plumbing for the canonical framings.
+ *
+ * Everything the signer frames is big-endian and explicit-length, mirroring
+ * the Rust writers in `arena_session::wire` and `dopa_open_api::encoding`.
+ * These helpers exist so every framing in this package spells a number the
+ * same way; a preimage that drifts from the Rust client by one byte produces
+ * signatures the authority silently rejects, which is why the parity vectors
+ * in `libs/dopa-open-client-rs/vectors/` pin all of it.
+ */
+export function toHex(bytes) {
+    let out = "";
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, "0");
+    return out;
+}
+export function fromHex(hex) {
+    const body = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (body.length % 2 !== 0)
+        throw new Error("hex length must be even");
+    const out = new Uint8Array(body.length / 2);
+    for (let index = 0; index < out.length; index++) {
+        const pair = body.slice(index * 2, index * 2 + 2);
+        const value = Number.parseInt(pair, 16);
+        if (Number.isNaN(value))
+            throw new Error(`bad hex byte: ${pair}`);
+        out[index] = value;
+    }
+    return out;
+}
+export function toHex0x(bytes) {
+    return `0x${toHex(bytes)}`;
+}
+/** Length-aware equality. `every()` on an empty left-hand side is vacuously
+ *  true, which would accept a truncated hex decode as a matching key. */
+export function equalBytes(left, right) {
+    if (left.length !== right.length)
+        return false;
+    return left.every((byte, index) => byte === right[index]);
+}
+/** An append-only byte buffer with the wire's own vocabulary. */
+export class ByteWriter {
+    chunks = [];
+    pushByte(value) {
+        if (!Number.isInteger(value) || value < 0 || value > 0xff)
+            throw new Error(`byte out of range: ${value}`);
+        this.chunks.push(value);
+        return this;
+    }
+    pushU16(value) {
+        if (!Number.isInteger(value) || value < 0 || value > 0xffff)
+            throw new Error(`u16 out of range: ${value}`);
+        this.chunks.push((value >> 8) & 0xff, value & 0xff);
+        return this;
+    }
+    pushU32(value) {
+        if (!Number.isInteger(value) || value < 0 || value > 0xffffffff)
+            throw new Error(`u32 out of range: ${value}`);
+        this.chunks.push((value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff);
+        return this;
+    }
+    pushU64(value) {
+        let big = typeof value === "bigint" ? value : BigInt(value);
+        if (big < 0n || big > 0xffffffffffffffffn)
+            throw new Error(`u64 out of range: ${value}`);
+        const bytes = new Array(8);
+        for (let index = 7; index >= 0; index--) {
+            bytes[index] = Number(big & 0xffn);
+            big >>= 8n;
+        }
+        this.chunks.push(...bytes);
+        return this;
+    }
+    pushBytes(bytes) {
+        for (const byte of bytes)
+            this.chunks.push(byte);
+        return this;
+    }
+    /** A fixed-width field: the wire reads exactly `length` bytes, so writing
+     *  any other count would silently shift every field after it. */
+    pushFixed(bytes, length, field) {
+        if (bytes.length !== length)
+            throw new Error(`${field} must be ${length} bytes, got ${bytes.length}`);
+        return this.pushBytes(bytes);
+    }
+    bytes() {
+        return Uint8Array.from(this.chunks);
+    }
+}
+/** Strict reader for one canonical frame. Trailing bytes are a decode error. */
+export class ByteReader {
+    source;
+    offset = 0;
+    constructor(source) {
+        this.source = source;
+    }
+    remaining() {
+        return this.source.length - this.offset;
+    }
+    consumed() {
+        return this.offset;
+    }
+    readByte(field) {
+        const value = this.source[this.offset++];
+        if (value === undefined)
+            throw new Error(`unexpected end reading ${field}`);
+        return value;
+    }
+    readU16(field) {
+        const hi = this.readByte(field);
+        const lo = this.readByte(field);
+        return (hi << 8) | lo;
+    }
+    readU32(field) {
+        const b0 = this.readByte(field);
+        const b1 = this.readByte(field);
+        const b2 = this.readByte(field);
+        const b3 = this.readByte(field);
+        return ((b0 << 24) | (b1 << 16) | (b2 << 8) | b3) >>> 0;
+    }
+    readU64(field) {
+        const bytes = this.readFixed(8, field);
+        let value = 0n;
+        for (const byte of bytes)
+            value = (value << 8n) | BigInt(byte);
+        return value;
+    }
+    readFixed(length, field) {
+        if (this.offset + length > this.source.length)
+            throw new Error(`unexpected end reading ${field}`);
+        const slice = this.source.slice(this.offset, this.offset + length);
+        this.offset += length;
+        return slice;
+    }
+    readLengthPrefixed(lengthField, bytesField) {
+        const length = Number(this.readU64(lengthField));
+        if (!Number.isSafeInteger(length) || length < 0)
+            throw new Error(`${lengthField} overflow`);
+        return this.readFixed(length, bytesField);
+    }
+    finish() {
+        if (this.offset !== this.source.length)
+            throw new Error(`trailing bytes: ${this.source.length - this.offset}`);
+    }
+}
+export function concatBytes(...parts) {
+    const length = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(length);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/** The shared signing frame: length-prefixed domain, then length-prefixed
+ *  payload. Identical between `arena_session::wire::frame_signing_bytes` and
+ *  `dopa_open_api::encoding::signed_preimage` on purpose - one shape to pin. */
+export function frameSigningBytes(domain, payload) {
+    return new ByteWriter()
+        .pushU64(domain.length)
+        .pushBytes(domain)
+        .pushU64(payload.length)
+        .pushBytes(payload)
+        .bytes();
+}
+export const textBytes = (value) => new TextEncoder().encode(value);

package/dist/channel.d.ts

@@ -0,0 +1,38 @@
+export declare const PACKAGE_NAME = "@dopamint-fun/open-sdk";
+export type ReleaseChannel = "canary" | "dev" | "prod";
+export declare const RELEASE_CHANNELS: readonly ReleaseChannel[];
+/** The npm dist-tag a channel publishes under and installs from. */
+export declare function channelDistTag(channel: ReleaseChannel): string;
+/** What an agent installs on a deployment of this channel.
+ *
+ *  `localOverride` wins outright: it is the tarball path or URL the local
+ *  stack exports (`DOPA_OPEN_SDK_INSTALL`), which keeps the local loop off
+ *  the public registry entirely. */
+export declare function installSpec(channel: ReleaseChannel, localOverride?: string): string;
+/** The full install command the skills and the connect panel print. */
+export declare function installCommand(channel: ReleaseChannel, localOverride?: string): string;
+/** Read the channel a deployment declared, refusing rather than guessing.
+ *
+ *  An unset value is prod - the bare install is the safe default for any
+ *  deployment that never says otherwise - but a set-and-wrong value is a
+ *  configuration error, not a preference, and resolving it to anything would
+ *  have every surface teach an install line nobody chose. */
+export declare function resolveChannel(raw: string | undefined): ReleaseChannel;
+/** The channel a deployment teaches, given the environment it is for.
+ *
+ *  `resolveChannel` treats an unset value as prod on purpose: the bare install
+ *  is the safe default for a deployment that never says otherwise. That default
+ *  is also how the canary stack came to serve `npm install @dopamint-fun/open-sdk`
+ *  — an install of a package that was not on the registry — to every agent
+ *  that read its skill: nobody had set the variable, and nothing said so.
+ *
+ *  So a deployment that names a non-production environment has to name a
+ *  channel too. Production keeps the default, because there the default is
+ *  the answer. A build with no environment named at all (a laptop, a fork)
+ *  keeps the old behaviour and is not this rule's concern. */
+export declare function resolveDeployedChannel(channelRaw: string | undefined, deployEnvironment: string | undefined): ReleaseChannel;
+/** Whether a package version belongs on a channel - what the publish script
+ *  enforces before it will pass `--tag`. Prod takes stable semver only; dev
+ *  and canary take only their own prerelease identifier, so a tag and a
+ *  version can never disagree about what a build is. */
+export declare function versionMatchesChannel(version: string, channel: ReleaseChannel): boolean;

package/dist/channel.js

@@ -0,0 +1,86 @@
+/* Release channels: one package name, three npm dist-tags.
+ *
+ * canary, dev and prod are the same package at different maturities, selected
+ * by tag rather than by name - a name suffix would fork the install line and
+ * every document teaching it. Prod rides `latest` so the bare install is
+ * production; the other two are opt-in by tag.
+ *
+ * This module is the single owner of the channel-to-install mapping. The
+ * skill serving plugin, the playground connect panel, and the SDK skill all
+ * read it, so a deployment can never teach one channel in one place and
+ * another elsewhere.
+ */
+export const PACKAGE_NAME = "@dopamint-fun/open-sdk";
+export const RELEASE_CHANNELS = [
+    "canary",
+    "dev",
+    "prod",
+];
+/** The npm dist-tag a channel publishes under and installs from. */
+export function channelDistTag(channel) {
+    return channel === "prod" ? "latest" : channel;
+}
+/** What an agent installs on a deployment of this channel.
+ *
+ *  `localOverride` wins outright: it is the tarball path or URL the local
+ *  stack exports (`DOPA_OPEN_SDK_INSTALL`), which keeps the local loop off
+ *  the public registry entirely. */
+export function installSpec(channel, localOverride) {
+    const override = localOverride?.trim();
+    if (override)
+        return override;
+    return channel === "prod"
+        ? PACKAGE_NAME
+        : `${PACKAGE_NAME}@${channelDistTag(channel)}`;
+}
+/** The full install command the skills and the connect panel print. */
+export function installCommand(channel, localOverride) {
+    return `npm install ${installSpec(channel, localOverride)}`;
+}
+/** Read the channel a deployment declared, refusing rather than guessing.
+ *
+ *  An unset value is prod - the bare install is the safe default for any
+ *  deployment that never says otherwise - but a set-and-wrong value is a
+ *  configuration error, not a preference, and resolving it to anything would
+ *  have every surface teach an install line nobody chose. */
+export function resolveChannel(raw) {
+    const value = raw?.trim();
+    if (!value)
+        return "prod";
+    if (RELEASE_CHANNELS.includes(value))
+        return value;
+    throw new Error(`DOPA_OPEN_SDK_CHANNEL must be one of ${RELEASE_CHANNELS.join(", ")}; got "${value}"`);
+}
+/** The channel a deployment teaches, given the environment it is for.
+ *
+ *  `resolveChannel` treats an unset value as prod on purpose: the bare install
+ *  is the safe default for a deployment that never says otherwise. That default
+ *  is also how the canary stack came to serve `npm install @dopamint-fun/open-sdk`
+ *  — an install of a package that was not on the registry — to every agent
+ *  that read its skill: nobody had set the variable, and nothing said so.
+ *
+ *  So a deployment that names a non-production environment has to name a
+ *  channel too. Production keeps the default, because there the default is
+ *  the answer. A build with no environment named at all (a laptop, a fork)
+ *  keeps the old behaviour and is not this rule's concern. */
+export function resolveDeployedChannel(channelRaw, deployEnvironment) {
+    const environment = deployEnvironment?.trim();
+    if (environment && environment !== "production" && !channelRaw?.trim()) {
+        throw new Error(`DOPA_OPEN_SDK_CHANNEL is unset on the ${environment} deployment. Unset ` +
+            `means prod, and a ${environment} stack teaching the production install ` +
+            `line is how canary served an install nobody could run. Set it to one ` +
+            `of ${RELEASE_CHANNELS.join(", ")} on the dopamint-arena-${environment} environment.`);
+    }
+    return resolveChannel(channelRaw);
+}
+/** Whether a package version belongs on a channel - what the publish script
+ *  enforces before it will pass `--tag`. Prod takes stable semver only; dev
+ *  and canary take only their own prerelease identifier, so a tag and a
+ *  version can never disagree about what a build is. */
+export function versionMatchesChannel(version, channel) {
+    const stable = /^\d+\.\d+\.\d+$/;
+    if (channel === "prod")
+        return stable.test(version);
+    const prerelease = new RegExp(`^\\d+\\.\\d+\\.\\d+-${channel}\\.\\d+$`);
+    return prerelease.test(version);
+}