@anycon/protocol 0.1.0

package/dist/constants.js

@@ -0,0 +1,159 @@
+/**
+ * 常量。全部镜像 `crates/protocol`，`constants.test.ts` 会解析 Rust 源码做漂移检查：
+ * 改了 Rust 侧的方法名 / 版本号 / close code / 错误码数值，这里不同步测试就会红。
+ */
+/** 内层 JSON-RPC 协议版本。相邻 minor 兼容，0.x 阶段可 break。 */
+export const PROTOCOL_VERSION = 1;
+/** 外层信封版本。极少改动。 */
+export const ENVELOPE_VERSION = 1;
+/** 短码字母表：大写字母数字去掉 0 O 1 I L。 */
+export const PAIR_CODE_ALPHABET = '23456789ABCDEFGHJKMNPQRSTUVWXYZ';
+/** 短码长度：8 位（约 40 bit），`anycon pair --short` 生成的；只适合自建 hub，经不信任的 hub 配对不要用。 */
+export const PAIR_CODE_LEN = 8;
+/** 长短码长度：16 位（约 79 bit），`anycon pair` 的**默认**长度，链接 / 二维码 / `--json` 都是它。与 `crates/crypto` 的 `PAIR_CODE_LEN_LONG` 一致。 */
+export const PAIR_CODE_LEN_LONG = 16;
+/** WebSocket close code（hub → 设备）。 */
+export const CLOSE_CODE = {
+    /** 同一设备的新连接顶掉了这条。不要自动重连，否则两条连接会互相踢。 */
+    SUPERSEDED: 4001,
+    /** hub 优雅关停。1–3 秒抖动后重连，而不是指数退避。 */
+    RESTARTING: 4002,
+    /** 接收太慢，发送缓冲持续满。 */
+    SLOW_CONSUMER: 4003,
+    /** 设备已被吊销。 */
+    REVOKED: 4004,
+    /** 第一帧 auth 超时。 */
+    AUTH_TIMEOUT: 4005,
+};
+/** 内层方法名。`域.动作`。键名与 `crates/protocol/src/methods.rs` 的常量名一致。 */
+export const METHODS = {
+    // pairing（握手刚完成、PairDone 之后，daemon → joiner 的第一条加密通知；joiner 收到并校验后才落盘）
+    /** D→C notification，params = PairAck */
+    PAIR_ACK: 'pair.ack',
+    // node
+    NODE_INFO: 'node.info',
+    NODE_DEVICES: 'node.devices',
+    NODE_REVOKE_DEVICE: 'node.revoke_device',
+    NODE_PAIR_BEGIN: 'node.pair_begin',
+    NODE_STATS: 'node.stats',
+    NODE_DOCTOR: 'node.doctor',
+    NODE_AUDIT: 'node.audit',
+    NODE_SET_AGENT_DEFAULTS: 'node.set_agent_defaults',
+    // 账号内接入（ADR-36）
+    /** 进行中的接入会话。 */
+    NODE_ENROLL_LIST: 'node.enroll_list',
+    /** 批准一个接入请求：`code` 返回 6 位码，`scan` 带二维码里的密钥。 */
+    NODE_ENROLL_APPROVE: 'node.enroll_approve',
+    NODE_ENROLL_DENY: 'node.enroll_deny',
+    /** 主动生成 6 位接入码（「添加设备」、`anycon pair --enroll`）。 */
+    NODE_ENROLL_CODE: 'node.enroll_code',
+    NODE_ENROLL_STATUS: 'node.enroll_status',
+    NODE_SET_ENROLL_PASSWORD: 'node.set_enroll_password',
+    NODE_SET_ENROLL_ENABLED: 'node.set_enroll_enabled',
+    /** D→C notification，params = EnrollInfo */
+    NODE_ENROLL_REQUESTED: 'node.enroll_requested',
+    /** D→C notification，params = NodeEnrollResolved */
+    NODE_ENROLL_RESOLVED: 'node.enroll_resolved',
+    /** D→C notification，params = NodeSecurityEvent */
+    NODE_SECURITY_EVENT: 'node.security_event',
+    // agent
+    AGENT_LIST: 'agent.list',
+    AGENT_DIAGNOSE: 'agent.diagnose',
+    /** D→C notification，params = AgentListResult */
+    AGENT_CHANGED: 'agent.changed',
+    // workspace
+    WORKSPACE_LIST: 'workspace.list',
+    WORKSPACE_CREATE: 'workspace.create',
+    WORKSPACE_CLONE: 'workspace.clone',
+    WORKSPACE_RENAME: 'workspace.rename',
+    WORKSPACE_TRASH: 'workspace.trash',
+    WORKSPACE_TRASH_LIST: 'workspace.trash_list',
+    WORKSPACE_RESTORE: 'workspace.restore',
+    WORKSPACE_PURGE: 'workspace.purge',
+    /** 把本机已有目录关联为项目（params = WorkspaceLinkParams → Project）。 */
+    WORKSPACE_LINK: 'workspace.link',
+    /** 解除关联（不删除目录；params = WorkspaceNameParams）。 */
+    WORKSPACE_UNLINK: 'workspace.unlink',
+    /** 列本机目录供选择（params = WorkspaceBrowseParams → WorkspaceBrowseResult）。 */
+    WORKSPACE_BROWSE: 'workspace.browse',
+    /** 列项目的分支（params = WorkspaceBranchesParams → WorkspaceBranchesResult，ADR-34）。 */
+    WORKSPACE_BRANCHES: 'workspace.branches',
+    /** 列 anycon 建的 worktree（params = WorkspaceWorktreesParams → WorkspaceWorktreesResult）。 */
+    WORKSPACE_WORKTREES: 'workspace.worktrees',
+    /** 删掉一个已保留 / 没有会话的 worktree（params = WorkspaceRemoveWorktreeParams）。 */
+    WORKSPACE_REMOVE_WORKTREE: 'workspace.remove_worktree',
+    /** D→C notification */
+    WORKSPACE_CHANGED: 'workspace.changed',
+    /** D→C notification */
+    JOB_PROGRESS: 'job.progress',
+    /** D→C notification */
+    JOB_DONE: 'job.done',
+    JOB_CANCEL: 'job.cancel',
+    // fs
+    FS_LIST: 'fs.list',
+    FS_READ: 'fs.read',
+    // session
+    SESSION_LIST: 'session.list',
+    SESSION_GET: 'session.get',
+    SESSION_CREATE: 'session.create',
+    SESSION_SEND: 'session.send',
+    SESSION_CANCEL: 'session.cancel',
+    SESSION_SET_SETTINGS: 'session.set_settings',
+    SESSION_WATCH: 'session.watch',
+    SESSION_UNWATCH: 'session.unwatch',
+    SESSION_HISTORY: 'session.history',
+    /** D→C notification，params = SessionEvent */
+    SESSION_EVENT: 'session.event',
+    /** D→C notification，params = SessionChanged */
+    SESSION_CHANGED: 'session.changed',
+    SESSION_RENAME: 'session.rename',
+    SESSION_ARCHIVE: 'session.archive',
+    SESSION_UNARCHIVE: 'session.unarchive',
+    SESSION_DELETE: 'session.delete',
+    SESSION_RESTART: 'session.restart',
+    SESSION_SEARCH: 'session.search',
+    SESSION_PROMOTE: 'session.promote',
+    /** params = SessionGitStatusParams → SessionGitStatus（ADR-34） */
+    SESSION_GIT_STATUS: 'session.git_status',
+    /** params = SessionDiffParams → SessionDiffResult */
+    SESSION_DIFF: 'session.diff',
+    /** params = SessionSyncBaseParams → SessionSyncBaseResult */
+    SESSION_SYNC_BASE: 'session.sync_base',
+    // blob（附件，ADR-35）
+    /** params = BlobPutBeginParams → BlobPutBeginResult */
+    BLOB_PUT_BEGIN: 'blob.put_begin',
+    /** params = BlobPutChunkParams */
+    BLOB_PUT_CHUNK: 'blob.put_chunk',
+    /** params = BlobIdParams → AttachmentRef */
+    BLOB_PUT_END: 'blob.put_end',
+    /** params = BlobGetParams → BlobGetResult */
+    BLOB_GET: 'blob.get',
+    /** params = BlobIdParams */
+    BLOB_DISCARD: 'blob.discard',
+    // permission
+    /** D→C notification，params = PermissionRequest */
+    PERMISSION_REQUEST: 'permission.request',
+    PERMISSION_RESPOND: 'permission.respond',
+    /** D→C notification，params = PermissionResolved */
+    PERMISSION_RESOLVED: 'permission.resolved',
+    PERMISSION_LIST: 'permission.list',
+};
+/**
+ * `ErrorCode` → JSON-RPC 数字 code（`crates/protocol/src/error.rs` 的 `rpc_code`）。
+ * 客户端只应依赖 `error.data.code`；数字 code 仅在对端没带 `data` 时做兜底。
+ */
+export const ERROR_CODE_NUMBERS = {
+    invalid: -32602,
+    invalid_settings: -32001,
+    agent_unavailable: -32002,
+    node_busy: -32003,
+    busy: -32004,
+    already_resolved: -32005,
+    exists: -32006,
+    not_found: -32007,
+    forbidden: -32008,
+    unsupported: -32009,
+    protocol_mismatch: -32010,
+    internal: -32603,
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/dist/crypto.d.ts

@@ -0,0 +1,202 @@
+export type Role = 'initiator' | 'responder';
+/** X25519 静态密钥对。纯数据，可序列化保存（`secret` 是敏感信息，0600 / IndexedDB）。 */
+export interface Keypair {
+    readonly public: Uint8Array;
+    readonly secret: Uint8Array;
+}
+/** `derivePairSecrets` 的结果。`psk` 是拷贝，用完 `fill(0)`。 */
+export interface PairSecrets {
+    /** 16 个 hex，发给 hub 撮合。 */
+    readonly matchId: string;
+    /** 32 字节预共享密钥，不离开本机。 */
+    readonly psk: Uint8Array;
+}
+/** 握手完成后的双向加密通道。一个 Transport 只能单线程顺序使用。 */
+export interface Transport {
+    /** 加密任意长度明文（自动分片）。 */
+    encrypt(plaintext: Uint8Array): Uint8Array;
+    /** 解密 `encrypt` 的输出，还原整条明文。乱序 / 篡改会抛错。 */
+    decrypt(ciphertext: Uint8Array): Uint8Array;
+    /** 对端静态公钥。 */
+    readonly remotePublic: Uint8Array;
+    /** 释放 wasm 内存。之后不能再用。 */
+    free(): void;
+}
+/** 进行中的握手。 */
+export interface Handshake {
+    /** 现在该我写消息吗。 */
+    isMyTurn(): boolean;
+    /** 写下一条握手消息（可带 payload，通常为空）。 */
+    write(payload?: Uint8Array): Uint8Array;
+    /** 读对方的握手消息，返回其 payload。 */
+    read(message: Uint8Array): Uint8Array;
+    isFinished(): boolean;
+    /** 对方静态公钥；握手进行到能知道的时候起可用（IK responder 读完第一条后就有）。 */
+    remotePublic(): Uint8Array | undefined;
+    /** 握手完成后转成 Transport，之后这个 Handshake 不能再用。 */
+    intoTransport(): Transport;
+    /** 握手中途放弃时释放。 */
+    free(): void;
+}
+export interface Crypto {
+    generateKeypair(): Keypair;
+    keypairFromSecret(secret: Uint8Array): Keypair;
+    /** 配对握手 `Noise_XXpsk3`。 */
+    pairing(role: Role, local: Keypair, psk: Uint8Array): Handshake;
+    /** 重连握手 `Noise_IK`。initiator 必须给 `remotePublic`，responder 不给。 */
+    reconnect(role: Role, local: Keypair, remotePublic?: Uint8Array): Handshake;
+    /**
+     * 短码 → `{ matchId, psk }`，**配对路径用它，只算一次**。一次 Argon2id（`salt = "anycon-pair-v2"`，
+     * m = 64 MiB、t = 3、p = 1，输出 64 字节）：前 8 字节的 hex 是 hub 撮合用的 `matchId`（16 个 hex，hub 永远看不到短码
+     * 本身），后 32 字节是 PSK。8 位或 16 位短码都合法，否则抛错。
+     *
+     * 耗时：Node / 本机 wasm 约 0.1–0.3 s，浏览器 wasm 约 0.1–1 s，会同步占用线程（UI 要先显示「正在派生密钥…」
+     * 再调用）。返回的 `psk` 是拷贝，调用方用完 `fill(0)`。
+     */
+    derivePairSecrets(code: string): PairSecrets;
+    /** 短码 → PSK（一次完整 Argon2id，约等于 `derivePairSecrets` 的耗时）。配对请直接用 `derivePairSecrets`，别和 `deriveMatchId` 各算一遍。 */
+    derivePsk(code: string): Uint8Array;
+    /** 短码 → hub 撮合用的 match id（16 个 hex；一次完整 Argon2id）。8 位或 16 位都合法，否则抛错。 */
+    deriveMatchId(code: string): string;
+    /** 大写，去掉 `-` 和空白。 */
+    normalizeCode(code: string): string;
+    /** 生成 `XXXX-XXXX` 形式的 8 位短码（`anycon pair --short`，约 40 bit，只适合自建 hub）。 */
+    generatePairCode(): string;
+    /** 生成 `XXXX-XXXX-XXXX-XXXX` 形式的 16 位短码（约 79 bit，`anycon pair` 的默认长度）。 */
+    generatePairCodeLong(): string;
+    /** 公钥指纹：`3f:a2:…`。 */
+    fingerprint(publicKey: Uint8Array): string;
+}
+/** 一方的 CPace 状态（账号内接入，ADR-36）。新设备用 `'initiator'`，daemon 用 `'responder'`。 */
+export interface Cpace {
+    /** 自己的份额（32 字节），放进 `EnrollFrame.cpace` / `share` 发给对方。 */
+    readonly share: Uint8Array;
+    /** 用对方的份额得到 32 字节 PSK（喂给 `pairing`）。份额不合法时抛 `invalid key`。之后这个对象不能再用。 */
+    finish(role: Role, peerShare: Uint8Array): Uint8Array;
+    /** 中途放弃时释放（私有标量随之清零）。 */
+    free(): void;
+}
+/**
+ * 账号内接入（ADR-36，protocol.md § 4.4）用到的密码学。`loadCrypto()` 返回的对象带这些方法；
+ * 只做配对 / 重连的 fake 可以只实现 `Crypto`。
+ */
+export interface EnrollCrypto {
+    /** `prs`：口令的 `deriveEnrollPasswordPrs`，或规范化后 6 位码的 ASCII 字节；`ci`：`enrollChannelId`；`sid`：`enrollSid`。 */
+    cpace(prs: Uint8Array, ci: Uint8Array, sid: Uint8Array): Cpace;
+    /** 16 字节随机数（`EnrollHello.nonce`）。 */
+    generateEnrollNonce(): Uint8Array;
+    /** 32 字节扫码密钥（放进二维码）。 */
+    generateEnrollSecret(): Uint8Array;
+    /** 去掉空白和 `-`，必须是 6 个数字，否则抛错。 */
+    normalizeEnrollCode(code: string): string;
+    /** 设置口令时校验：NFC 之后至少 8 个字符，否则抛 `enroll password too short`。 */
+    validateEnrollPassword(password: string): void;
+    /** `Argon2id(NFC(口令), salt)`，浏览器里约 0.5–1 s，会同步占用线程。`salt` 是 `EnrollReply.salt`（16 字节）。 */
+    deriveEnrollPasswordPrs(password: string, salt: Uint8Array): Uint8Array;
+    /** 扫码接入的 PSK：`HKDF-BLAKE2s(secret, info = "anycon-enroll-scan-v1" ‖ nodeId)`。 */
+    deriveEnrollScanPsk(secret: Uint8Array, nodeId: string): Uint8Array;
+    /** CPace 信道标识，`method` 是 `'code'` 或 `'password'`。 */
+    enrollChannelId(nodeId: string, method: string): Uint8Array;
+    /** CPace 会话标识：新设备的 nonce ‖ daemon 的 nonce。 */
+    enrollSid(initiatorNonce: Uint8Array, responderNonce: Uint8Array): Uint8Array;
+}
+/** `loadCrypto()` 的结果：配对 / 重连 / 传输 + 账号内接入。 */
+export type FullCrypto = Crypto & EnrollCrypto;
+/** wasm 产物不存在或加载失败。 */
+export declare class CryptoUnavailableError extends Error {
+    readonly name = "CryptoUnavailableError";
+}
+interface RawKeypair {
+    readonly public: Uint8Array;
+    readonly secret: Uint8Array;
+    free(): void;
+}
+interface RawTransport {
+    encrypt(plaintext: Uint8Array): Uint8Array;
+    decrypt(ciphertext: Uint8Array): Uint8Array;
+    readonly remotePublic: Uint8Array | (() => Uint8Array);
+    free(): void;
+}
+interface RawHandshake {
+    readonly isMyTurn: boolean | (() => boolean);
+    write(payload: Uint8Array): Uint8Array;
+    read(message: Uint8Array): Uint8Array;
+    readonly isFinished: boolean | (() => boolean);
+    readonly remotePublic: Uint8Array | undefined | (() => Uint8Array | undefined);
+    intoTransport(): RawTransport;
+    free(): void;
+}
+interface RawCpace {
+    readonly share: Uint8Array;
+    finish(role: Role, peerShare: Uint8Array): Uint8Array;
+    free(): void;
+}
+interface RawPairSecrets {
+    readonly matchId: string;
+    readonly psk: Uint8Array;
+    free(): void;
+}
+/** 动态 import 得到的模块。 */
+export interface WasmModule {
+    default: (input?: unknown) => Promise<unknown>;
+    WasmKeypair: {
+        generate(): RawKeypair;
+        fromSecret(secret: Uint8Array): RawKeypair;
+    };
+    WasmHandshake: {
+        pairing(role: Role, local: RawKeypair, psk: Uint8Array): RawHandshake;
+        reconnect(role: Role, local: RawKeypair, remotePublic?: Uint8Array): RawHandshake;
+    };
+    derivePairSecrets(code: string): RawPairSecrets;
+    derivePsk(code: string): Uint8Array;
+    deriveMatchId(code: string): string;
+    normalizeCode(code: string): string;
+    generatePairCode(): string;
+    generatePairCodeLong(): string;
+    fingerprint(publicKey: Uint8Array): string;
+    WasmCpace: new (prs: Uint8Array, ci: Uint8Array, sid: Uint8Array) => RawCpace;
+    generateEnrollNonce(): Uint8Array;
+    generateEnrollSecret(): Uint8Array;
+    normalizeEnrollCode(code: string): string;
+    validateEnrollPassword(password: string): void;
+    deriveEnrollPasswordPrs(password: string, salt: Uint8Array): Uint8Array;
+    deriveEnrollScanPsk(secret: Uint8Array, nodeId: string): Uint8Array;
+    enrollChannelId(nodeId: string, method: string): Uint8Array;
+    enrollSid(initiatorNonce: Uint8Array, responderNonce: Uint8Array): Uint8Array;
+}
+/** `.wasm` 的来源：URL / 字节 / 已编译的 Module / fetch 的 Response。 */
+export type WasmSource = string | URL | BufferSource | WebAssembly.Module | Response | Promise<Response | BufferSource | WebAssembly.Module>;
+export interface LoadCryptoOptions {
+    /**
+     * `.wasm` 的位置。浏览器里交给打包器：
+     * `loadCrypto({ wasm: new URL('@anycon/protocol/wasm/anycon_crypto_bg.wasm', import.meta.url) })`
+     * 或 Vite 的 `?url` 导入。Node / Bun 下不给就自动读 `../wasm/anycon_crypto_bg.wasm`。
+     */
+    wasm?: WasmSource;
+    /** 直接给 wasm-bindgen 的 JS 模块（打包器想自己控制 import 路径时用）。 */
+    module?: WasmModule | Promise<WasmModule>;
+}
+/**
+ * 加载并初始化 wasm。进程内只初始化一次（第二次调用返回同一个 Promise；失败不缓存，可重试）。
+ * wasm 产物不存在时抛 `CryptoUnavailableError`，消息里写明要跑 `just gen-wasm`。
+ */
+export declare function loadCrypto(options?: LoadCryptoOptions): Promise<FullCrypto>;
+/** 短码规范化（纯 JS）：大写，去掉 `-` 和空白。与 `crates/crypto` 的 `normalize_code` 一致。 */
+export declare function normalizePairCode(code: string): string;
+/** 短码格式校验：规范化后是 8 位或 16 位，且都在字母表内。纯 JS，不需要 wasm。 */
+export declare function isValidPairCode(code: string): boolean;
+/**
+ * `XXXXXXXX` → `XXXX-XXXX`，16 位 → `XXXX-XXXX-XXXX-XXXX`（每 4 位一组）。
+ * 长度既不是 8 也不是 16 时原样返回规范化结果。
+ */
+export declare function formatPairCode(code: string): string;
+/**
+ * 从用户输入里取出短码：接受裸短码（8 / 16 位，大小写、`-`、空白随意）、完整配对链接
+ * `https://hub.example/pair#code=XXXX-XXXX`、或只有 fragment 的 `#code=…` / `code=…`。
+ * 短码在 fragment 里，浏览器不会把它发给 hub。格式不合法返回 `undefined`。
+ */
+export declare function extractPairCode(input: string): string | undefined;
+export declare function hexOf(bytes: Uint8Array): string;
+export declare function bytesOfHex(hex: string): Uint8Array;
+export {};
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}

package/dist/crypto.js

@@ -0,0 +1,218 @@
+/**
+ * `crates/crypto` 的 wasm 封装。`loadCrypto()` 动态加载 `../wasm/anycon_crypto.js`（`just gen-wasm` 的产物，
+ * 已 gitignore），初始化后返回一个 Promise 无关的同步 API：`Uint8Array` 进出，没有 wasm-bindgen 的所有权语义。
+ *
+ * 为什么包一层：
+ * - 密钥对是纯数据（`public` / `secret`），每次握手时才在 wasm 里临时重建，不存在「传进去就被消费」的问题；
+ * - 隐藏 wasm-bindgen 产物的细节（getter / 方法、`init` 签名、Node 下读 .wasm 文件）；
+ * - SDK 和测试可以注入别的实现（`Crypto` 接口），比如不需要真密码学的 fake。
+ *
+ * 角色：配对（XXpsk3）joiner 是 initiator、host（daemon）是 responder；重连（IK）客户端是 initiator。
+ */
+import { PAIR_CODE_ALPHABET, PAIR_CODE_LEN, PAIR_CODE_LEN_LONG } from './constants.js';
+/** wasm 产物不存在或加载失败。 */
+export class CryptoUnavailableError extends Error {
+    name = 'CryptoUnavailableError';
+}
+function member(obj, name) {
+    const value = obj[name];
+    return (typeof value === 'function' ? value.call(obj) : value);
+}
+function wrapTransport(raw) {
+    const remote = member(raw, 'remotePublic').slice();
+    return {
+        encrypt: (plaintext) => raw.encrypt(plaintext),
+        decrypt: (ciphertext) => raw.decrypt(ciphertext),
+        remotePublic: remote,
+        free: () => raw.free(),
+    };
+}
+function wrapHandshake(raw) {
+    return {
+        isMyTurn: () => member(raw, 'isMyTurn'),
+        write: (payload) => raw.write(payload ?? new Uint8Array(0)),
+        read: (message) => raw.read(message),
+        isFinished: () => member(raw, 'isFinished'),
+        remotePublic: () => {
+            const key = member(raw, 'remotePublic');
+            return key ? key.slice() : undefined;
+        },
+        intoTransport: () => wrapTransport(raw.intoTransport()),
+        free: () => raw.free(),
+    };
+}
+function toKeypair(raw) {
+    const kp = { public: raw.public.slice(), secret: raw.secret.slice() };
+    raw.free();
+    return kp;
+}
+function wrapCpace(raw) {
+    let done = false;
+    return {
+        share: raw.share.slice(),
+        // wasm 侧 `finish` 按值消费对象，之后 `free` 是空操作
+        finish: (role, peerShare) => {
+            done = true;
+            return raw.finish(role, peerShare);
+        },
+        free: () => {
+            if (!done)
+                raw.free();
+            done = true;
+        },
+    };
+}
+function wrapModule(mod) {
+    // 传给 wasm 的 Keypair 每次临时重建。握手对象建好后释放它：wasm 若按值消费了它，free 是空操作。
+    const withKeypair = (kp, build) => {
+        const raw = mod.WasmKeypair.fromSecret(kp.secret);
+        try {
+            return wrapHandshake(build(raw));
+        }
+        finally {
+            try {
+                raw.free();
+            }
+            catch {
+                // 已被消费
+            }
+        }
+    };
+    return {
+        generateKeypair: () => toKeypair(mod.WasmKeypair.generate()),
+        keypairFromSecret: (secret) => toKeypair(mod.WasmKeypair.fromSecret(secret)),
+        pairing: (role, local, psk) => withKeypair(local, (raw) => mod.WasmHandshake.pairing(role, raw, psk)),
+        reconnect: (role, local, remotePublic) => withKeypair(local, (raw) => mod.WasmHandshake.reconnect(role, raw, remotePublic)),
+        derivePairSecrets: (code) => {
+            const raw = mod.derivePairSecrets(code);
+            try {
+                // `psk` getter 每次返回一份新的 JS 拷贝（wasm 内存里的原件随 `free()` 清零），所以直接交给调用方，
+                // 不再 `.slice()` 多复制一份——多出来的那份没人能清零。调用方用完要 `psk.fill(0)`。
+                return { matchId: raw.matchId, psk: raw.psk };
+            }
+            finally {
+                raw.free();
+            }
+        },
+        derivePsk: (code) => mod.derivePsk(code),
+        deriveMatchId: (code) => mod.deriveMatchId(code),
+        normalizeCode: (code) => mod.normalizeCode(code),
+        generatePairCode: () => mod.generatePairCode(),
+        generatePairCodeLong: () => mod.generatePairCodeLong(),
+        fingerprint: (publicKey) => mod.fingerprint(publicKey),
+        cpace: (prs, ci, sid) => wrapCpace(new mod.WasmCpace(prs, ci, sid)),
+        generateEnrollNonce: () => mod.generateEnrollNonce(),
+        generateEnrollSecret: () => mod.generateEnrollSecret(),
+        normalizeEnrollCode: (code) => mod.normalizeEnrollCode(code),
+        validateEnrollPassword: (password) => mod.validateEnrollPassword(password),
+        deriveEnrollPasswordPrs: (password, salt) => mod.deriveEnrollPasswordPrs(password, salt),
+        deriveEnrollScanPsk: (secret, nodeId) => mod.deriveEnrollScanPsk(secret, nodeId),
+        enrollChannelId: (nodeId, method) => mod.enrollChannelId(nodeId, method),
+        enrollSid: (a, b) => mod.enrollSid(a, b),
+    };
+}
+const isNode = () => typeof globalThis.process?.versions?.node ===
+    'string';
+async function importWasmModule() {
+    try {
+        // 字面量路径：打包器（Vite 等）能静态分析并把 wasm 胶水 js 打进来。
+        // @ts-ignore -- 产物由 `just gen-wasm` 生成，可能不存在，类型也由本文件的 WasmModule 描述。
+        return (await import('../wasm/anycon_crypto.js'));
+    }
+    catch (cause) {
+        throw new CryptoUnavailableError('anycon crypto wasm is not built: packages/protocol/wasm/anycon_crypto.js is missing. ' +
+            'Run `just gen-wasm` (wasm-pack build of crates/crypto) first.', { cause });
+    }
+}
+async function nodeWasmBytes() {
+    // 变量指定符：不让浏览器打包器解析 node 内置模块。
+    const fsSpecifier = 'node:fs/promises';
+    const { readFile } = (await import(/* @vite-ignore */ fsSpecifier));
+    const url = new URL('../wasm/anycon_crypto_bg.wasm', import.meta.url);
+    try {
+        return await readFile(url);
+    }
+    catch (cause) {
+        throw new CryptoUnavailableError(`anycon crypto wasm binary not found at ${url.pathname}. Run \`just gen-wasm\`.`, { cause });
+    }
+}
+async function initialize(options) {
+    const mod = await (options.module ?? importWasmModule());
+    const input = options.wasm ?? (isNode() ? await nodeWasmBytes() : undefined);
+    // wasm-bindgen ≥ 0.2.93 的对象形参；不给 input 时浏览器走胶水 js 里的 `new URL(…, import.meta.url)`。
+    await mod.default(input === undefined ? undefined : { module_or_path: input });
+    return wrapModule(mod);
+}
+let cached;
+/**
+ * 加载并初始化 wasm。进程内只初始化一次（第二次调用返回同一个 Promise；失败不缓存，可重试）。
+ * wasm 产物不存在时抛 `CryptoUnavailableError`，消息里写明要跑 `just gen-wasm`。
+ */
+export function loadCrypto(options = {}) {
+    if (!cached) {
+        cached = initialize(options).catch((err) => {
+            cached = undefined;
+            throw err;
+        });
+    }
+    return cached;
+}
+/** 短码规范化（纯 JS）：大写，去掉 `-` 和空白。与 `crates/crypto` 的 `normalize_code` 一致。 */
+export function normalizePairCode(code) {
+    return code.replace(/[\s-]/g, '').toUpperCase();
+}
+/** 短码格式校验：规范化后是 8 位或 16 位，且都在字母表内。纯 JS，不需要 wasm。 */
+export function isValidPairCode(code) {
+    const normalized = normalizePairCode(code);
+    if (normalized.length !== PAIR_CODE_LEN && normalized.length !== PAIR_CODE_LEN_LONG)
+        return false;
+    for (const ch of normalized)
+        if (!PAIR_CODE_ALPHABET.includes(ch))
+            return false;
+    return true;
+}
+/**
+ * `XXXXXXXX` → `XXXX-XXXX`，16 位 → `XXXX-XXXX-XXXX-XXXX`（每 4 位一组）。
+ * 长度既不是 8 也不是 16 时原样返回规范化结果。
+ */
+export function formatPairCode(code) {
+    const normalized = normalizePairCode(code);
+    if (normalized.length !== PAIR_CODE_LEN && normalized.length !== PAIR_CODE_LEN_LONG) {
+        return normalized;
+    }
+    return normalized.match(/.{4}/g).join('-');
+}
+/**
+ * 从用户输入里取出短码：接受裸短码（8 / 16 位，大小写、`-`、空白随意）、完整配对链接
+ * `https://hub.example/pair#code=XXXX-XXXX`、或只有 fragment 的 `#code=…` / `code=…`。
+ * 短码在 fragment 里，浏览器不会把它发给 hub。格式不合法返回 `undefined`。
+ */
+export function extractPairCode(input) {
+    const text = input.trim();
+    if (text === '')
+        return undefined;
+    let candidate = text;
+    const hashAt = text.indexOf('#');
+    if (hashAt >= 0) {
+        candidate = new URLSearchParams(text.slice(hashAt + 1)).get('code') ?? '';
+    }
+    else if (/^code=/i.test(text)) {
+        candidate = new URLSearchParams(text).get('code') ?? '';
+    }
+    return isValidPairCode(candidate) ? formatPairCode(candidate) : undefined;
+}
+export function hexOf(bytes) {
+    let out = '';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+export function bytesOfHex(hex) {
+    if (hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex))
+        throw new Error('invalid hex string');
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}