@jixo/opendweb-client-sdk 0.0.0 → 0.2.0

package/index.d.ts

@@ -0,0 +1,158 @@
+/** 事件判别联合：relay-* 事件必携带完整快照 payload（非可选） */
+/** 代理策略：none=直连；from-env=读环境代理；url 形态仅 SDK 使用 */
+export type HttpProxyOptions = 'none' | 'from-env' | { url: string }
+
+/** 从 SDK 错误消息的 [<kebab-code>] 前缀派生稳定错误码（SCREAMING_SNAKE）；无前缀返回 null */
+export declare function deriveErrorCode(message: string): string | null
+
+export type FabricEventJs =
+  | {
+      type: 'peer-connected' | 'peer-disconnected'
+      endpointId: string
+    }
+  | { type: 'roster-updated' }
+  | { type: 'message'; from: string; data: Buffer }
+  | { type: 'path-changed'; endpointId: string; status: 'direct' | 'relay' | 'unknown' }
+  | { type: 'relay-online' | 'relay-offline'; relay: RelayStatusJs }
+
+/** relay 状态快照（relayStatus() 返回值与 relay-* 事件 payload 同构） */
+export interface RelayStatusJs {
+  /** 字面量联合（非 string） */
+  mode: 'disabled' | 'custom' | 'n0'
+  /** 配置的 relay URL 列表（disabled 为空数组；n0 恒为 ["https://relay.iroh.network"]） */
+  urls: string[]
+  /** null <=> mode === "disabled"；否则为任一 relay 已连接 */
+  online: boolean | null
+  /** 最近一次连接错误类别（脱敏：无凭证段；无错误为 null） */
+  lastError: string | null
+}
+
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * dweb fabric：应用级组网的 Node SDK 入口。
+ * 工厂：Fabric.createRoot / Fabric.open / Fabric.attach；完成后调用 shutdown 释放资源。
+ */
+export declare class Fabric {
+  /** 创建新 fabric（本节点成为 root，可签发邀请与撤销）。 */
+  static createRoot(opts: FabricOptions, secret?: SecretSeedHandle | undefined | null): Promise<Fabric>
+  /** 打开已有 fabric（数据目录已含名册）。 */
+  static open(opts: FabricOptions, secret?: SecretSeedHandle | undefined | null): Promise<Fabric>
+  /** 以加入者身份起步（空名册；随后调用 join 兑换邀请）。 */
+  static attach(opts: FabricOptions, fabricIdHex: string, secret?: SecretSeedHandle | undefined | null): Promise<Fabric>
+  /**
+   *  一步加入：从令牌解析 fabric_id，attach + 兑换 + 持久化名册。
+   *  令牌前置检查（解码/过期/地址规范化）先于本地数据面加载与身份句柄消费
+   * （D11 冻结顺序：令牌自身错误优先于目录检查）。
+   */
+  static joinWithToken(opts: FabricOptions, token: string, secret?: SecretSeedHandle | undefined | null): Promise<Fabric>
+  /** 本节点 EndpointId（z-base-32，52 字符） */
+  get endpointId(): string
+  /** fabric id（hex） */
+  fabricIdHex(): Promise<string>
+  /** 当前有效成员投影 */
+  members(): Promise<Array<Member>>
+  /** 查询 EndpointId 是否为有效成员 */
+  isMember(endpointId: string): Promise<boolean>
+  /**
+   * 签发邀请令牌（root-only）。返回 dweb1. 前缀的自包含字符串。
+   * 第三参 opts 透传签发安全门逃生阀：relay 为空且 advertiseAddrs 为空时，
+   * 无 opts 或 allowRelayless !== true => reject（[invite-without-relay]）。
+   */
+  invite(ttlMs: number, recipient?: string | undefined | null, opts?: InviteOptions | undefined | null): Promise<string>
+  /** 兑换邀请令牌加入 fabric（issuer-online 单次兑换）。 */
+  join(token: string): Promise<void>
+  /** 连接成员（常规通道；双向门控 + 名册同步）。幂等（活跃连接直接成功）。 */
+  connect(endpointId: string): Promise<void>
+  /** 断开与某成员的会话 */
+  disconnect(endpointId: string): Promise<void>
+  /** 发送不透明二进制 envelope */
+  send(endpointId: string, data: Buffer): Promise<void>
+  /** 撤销成员（root-only）；投影收紧并断开既有会话。 */
+  revoke(endpointId: string): Promise<void>
+  /** 设置本节点显示名 */
+  setDisplayName(name: string): Promise<void>
+  /** 查询与某成员的当前路径类型："direct" | "relay" | "unknown" */
+  linkStatus(endpointId: string): Promise<string>
+  /**
+   * relay 状态快照（零等待，读内核缓存）。快照优先于事件：初始事实一律先查
+   * 本方法，事件只承载后续跳变。禁用模式 online 为 null（而非 false）。
+   */
+  relayStatus(): Promise<RelayStatusJs>
+  /**
+   * 显式导出身份（identity export，不含 roster）为 `dwebkey1.` 加密串。
+   * 交由产品自行安全保存（如账号系统加密托管——密文上云、口令在用户）。
+   */
+  exportSecretPassphrase(passphrase: string): Promise<string>
+  /**
+   * 注册事件回调（可多次调用，多个回调都会收到全部事件）。
+   * 返回句柄 id；off(id) 注销（index.js 包装为取消订阅函数）。
+   */
+  on(callback: (event: FabricEventJs) => void): () => void
+  /** 注销事件回调（on 返回的 id）。 */
+  off(id: number): void
+  /** 优雅关闭：断开全部会话并释放网络资源。幂等。 */
+  shutdown(): Promise<void>
+}
+
+/**
+ * 受保护的身份种子句柄：内部持有 [`SecretSeed`]（zeroize-on-drop），
+ * 被 Fabric 构造消费（take）后即失效。用于"导入 token / 产品托管解密后"
+ * 向 Fabric 注入身份而不经手明文 JS 字符串。内部 Arc：句柄可 clone 进
+ * 配置对象，take 语义全局共享（一次消费）。
+ */
+export declare class SecretSeedHandle {
+  /** 派生 EndpointId（z32 展示串；不暴露种子本体）。 */
+  get endpointId(): string
+  /** 是否仍持有种子（未被消费）。 */
+  get available(): boolean
+}
+
+/** Fabric 构造配置 */
+export interface FabricOptions {
+  /** 数据目录（名册持久化位置；secret 默认实现也指向此目录） */
+  dataDir: string
+  relay?: RelayOptions
+  /** 写入邀请令牌的 issuer 直连地址（host:port；逐项校验，非法构造 reject） */
+  advertiseAddrs?: Array<string>
+  /**
+   * HTTP 控制面（relay 连接）代理所有权；缺省 "none"。
+   * iroh endpoint 不读进程环境变量；QUIC 数据面永不经代理。
+   */
+  httpProxy?: 'none' | 'from-env' | { url: string }
+  /** join 总时限（毫秒）；缺省 30000；值域 [1000, 600000]，越界构造 reject */
+  joinTimeoutMs?: number
+}
+
+/** httpProxy 的 `{ url }` 形态（"none" | "from-env" 为字符串形态）。 */
+export interface HttpProxyUrl {
+  url: string
+}
+
+/**
+ * 导入 `dwebkey1.` 身份导出串：口令派生解密，返回受保护的种子句柄。
+ * （不落盘；注入 Fabric 用工厂的 secret 参数。Argon2 在阻塞线程池执行。）
+ */
+export declare function importSecret(token: string, passphrase: string): Promise<SecretSeedHandle>
+
+/** invite 逃生阀选项（D3）。 */
+export interface InviteOptions {
+  /** 允许签发无 relay 令牌；调用方自担可达性责任（带外路径）。 */
+  allowRelayless?: boolean
+}
+
+/** 成员信息 */
+export interface Member {
+  endpointId: string
+  displayName?: string
+  sinceMs: number
+}
+
+/** SDK 原生层版本 */
+export declare function nativeVersion(): string
+
+/** relay 配置（判别联合：非法组合构造期拒绝） */
+export type RelayOptions =
+  | { mode?: 'n0' }
+  | { mode: 'disabled' }
+  | { mode: 'custom'; urls: [string, ...string[]] }

package/index.js

@@ -1 +1,94 @@
-module.exports = {};
+// 平台守卫 + 原生模块加载 + 事件解包：v0.1 仅 darwin-arm64。
+// 加载策略：把 .node 拷贝到 os.tmpdir() 下的内容寻址新路径再 require——
+// 规避网络磁盘（SMB）页缓存不一致导致的 CODESIGNING "Invalid Page"，
+// 以及 dyld 对既有路径的坏闭包缓存（同名覆写后同字节仍加载失败）。
+// 事件解包：原生层以 JSON 字符串投递事件（TSFN 对象转换在 napi 3.12 不稳定），
+// 此处还原为带 Buffer 的类型化对象。
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const PLATFORM_BINARIES = {
+  "darwin-arm64": "dweb.darwin-arm64.node",
+  "win32-x64": "dweb.win32-x64.node",
+};
+const SUPPORTED = `${process.platform}-${process.arch}`;
+const BINARY = PLATFORM_BINARIES[SUPPORTED];
+
+if (!BINARY) {
+  throw new Error(
+    `@jixo/opendweb-client-sdk: 当前平台 ${SUPPORTED} 暂不支持。v0.1 提供 ${Object.keys(PLATFORM_BINARIES).join(" / ")} 原生二进制。`,
+  );
+}
+
+const SRC = path.join(__dirname, BINARY);
+
+function loadViaTmp() {
+  const buf = fs.readFileSync(SRC);
+  const hash = crypto.createHash("sha256").update(buf).digest("hex").slice(0, 24);
+  try {
+    // 0700 私有目录规避可预测路径的 symlink/TOCTOU 窗口
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "opendweb-sdk-"));
+    const dest = path.join(dir, `${hash}.node`);
+    const fd = fs.openSync(dest, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o755);
+    try {
+      fs.writeFileSync(fd, buf);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return require(dest);
+  } catch {
+    return null;
+  }
+}
+
+const Native = loadViaTmp() ?? require(SRC);
+
+// on() → 取消订阅函数：原生层返回回调 id，off(id) 注销（event_callbacks 移除句柄）。
+const nativeOn = Native.Fabric.prototype.on;
+const nativeOff = Native.Fabric.prototype.off;
+Native.Fabric.prototype.on = function onWrapped(callback) {
+  // 原生 TSFN 为 error-first 回调：(err, jsonString)
+  const id = nativeOn.call(this, (err, json) => {
+    if (err) return;
+    const ev = JSON.parse(json);
+    if (typeof ev.dataBase64 === "string") {
+      ev.data = Buffer.from(ev.dataBase64, "base64");
+      delete ev.dataBase64;
+    }
+    callback(ev);
+  });
+  return () => nativeOff.call(this, id);
+};
+
+/**
+ * 从 SDK 错误消息的 [<kebab-code>] 前缀派生稳定错误码（SCREAMING_SNAKE）。
+ * napi Error 无自定义 code 通道——前缀约定见 contracts/error-matrix.md。
+ * 无前缀时返回 null（未分类的底层错误）。
+ */
+function deriveErrorCode(message) {
+  if (typeof message !== "string") return null;
+  const m = message.match(/^\[([a-z0-9-]+)\]\s/);
+  if (!m) return null;
+  return m[1].replace(/-/g, "_").toUpperCase();
+}
+Native.deriveErrorCode = deriveErrorCode;
+
+// relayStatus()：napi Option::None 序列化为 undefined，契约（C0 d.ts）要求 null——
+// 包装归一（事件 payload 的 relay 快照经 JSON.parse 天然是 null，无需处理）。
+const nativeRelayStatus = Native.Fabric.prototype.relayStatus;
+if (typeof nativeRelayStatus === "function") {
+  Native.Fabric.prototype.relayStatus = async function relayStatusWrapped() {
+    const r = await nativeRelayStatus.call(this);
+    return {
+      mode: r.mode,
+      urls: r.urls ?? [],
+      online: r.online ?? null,
+      lastError: r.lastError ?? null,
+    };
+  };
+}
+
+module.exports = Native;

package/package.json

@@ -1,9 +1,36 @@
 {
   "name": "@jixo/opendweb-client-sdk",
-  "version": "0.0.0",
-  "description": "Generated placeholder package reserved by pnpm-pub.",
+  "version": "0.2.0",
+  "description": "@jixo/opendweb-client-sdk — dweb application-level fabric SDK for Node (napi-rs binding)",
+  "license": "MIT OR Apache-2.0",
   "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "binaryName": "dweb",
+    "targets": [
+      "aarch64-apple-darwin"
+    ]
+  },
+  "scripts": {
+    "build": "napi build --platform --release --target aarch64-apple-darwin --no-js && node scripts/fix-dts.mjs",
+    "build:debug": "napi build --platform --target aarch64-apple-darwin --no-js",
+    "test": "node --test --test-force-exit",
+    "typecheck": "tsc --noEmit",
+    "build:win": "PATH=\"$HOME/.cargo/bin:$PATH\" LIBNODE_PATH=\"$HOME/libnode-win\" cargo build --release --target x86_64-pc-windows-gnu -p dweb-client-sdk && cp \"$HOME/.cargo-target/dweb/x86_64-pc-windows-gnu/release/dweb_client_sdk.dll\" dweb.win32-x64.node"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "3.7.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
   "files": [
-    "index.js"
-  ]
+    "index.js",
+    "index.d.ts",
+    "dweb.darwin-arm64.node",
+    "dweb.win32-x64.node"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gaubee/dweb.git"
+  }
 }