@jixo/opendweb-client-sdk 0.0.0 → 0.1.0

package/index.d.ts

@@ -0,0 +1,106 @@
+export interface FabricEventJs {
+  type: 'peer-connected' | 'peer-disconnected' | 'roster-updated' | 'message' | 'path-changed'
+  endpointId?: string
+  from?: string
+  data?: Buffer
+  status?: 'direct' | 'relay' | 'unknown'
+}
+
+/* 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 + 兑换 + 持久化名册。 */
+  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. 前缀的自包含字符串。 */
+  invite(ttlMs: number, recipient?: string | 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>
+  /**
+   * 显式导出身份（identity export，不含 roster）为 `dwebkey1.` 加密串。
+   * 交由产品自行安全保存（如账号系统加密托管——密文上云、口令在用户）。
+   */
+  exportSecretPassphrase(passphrase: string): Promise<string>
+  /**
+   * 注册事件回调（可多次调用，多个回调都会收到全部事件）。
+   * 事件对象见 FabricEventJs：{ type, endpointId?, from?, data?, status? }
+   */
+  on(callback: (event: FabricEventJs) => void): 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） */
+  advertiseAddrs?: Array<string>
+}
+
+/**
+ * 导入 `dwebkey1.` 身份导出串：口令派生解密，返回受保护的种子句柄。
+ * （不落盘；注入 Fabric 用工厂的 secret 参数。Argon2 在阻塞线程池执行。）
+ */
+export declare function importSecret(token: string, passphrase: string): Promise<SecretSeedHandle>
+
+/** 成员信息 */
+export interface Member {
+  endpointId: string
+  displayName?: string
+  sinceMs: number
+}
+
+/** SDK 原生层版本 */
+export declare function nativeVersion(): string
+
+/** relay 配置 */
+export interface RelayOptions {
+  /** "disabled" | "custom" | "n0"（默认 "n0"） */
+  mode?: string
+  /** mode = "custom" 时的 relay URL 列表（自托管 docker 或其它 iroh relay） */
+  urls?: Array<string>
+}

package/index.js

@@ -1 +1,63 @@
-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);
+
+const nativeOn = Native.Fabric.prototype.on;
+Native.Fabric.prototype.on = function onWrapped(callback) {
+  // 原生 TSFN 为 error-first 回调：(err, jsonString)
+  return 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);
+  });
+};
+
+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.1.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"
+  }
 }