@cef-ai/wallet 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# @cef-ai/wallet
+
+Embed SCP Wallet into a host application. Passkey-native authentication
+via WebAuthn + PRF. No MetaMask, no seed phrases, no popup-blocker headaches.
+
+For runtime topology and the popup/cross-tab channels this SDK speaks,
+see [`ARCHITECTURE.md`](../../ARCHITECTURE.md) in the repo root.
+
+> **Status:** v2.0.0-alpha. Public API surface is stable but pre-1.0.
+> `private: true` in `package.json` — not yet published to npm.
+
+## Install
+
+```bash
+npm install @cef-ai/wallet
+```
+
+## TODO(publish) — must be addressed before flipping `private: false`
+
+1. **Workspace dep versions.** `@cef-ai/wallet-api-client`, `@cef-ai/wallet-identity`,
+   `@cef-ai/wallet-signers` are pinned at `0.0.0` (workspace placeholder). Choose:
+
+   - **Option A**: publish those three packages with real semver versions first,
+     then bump this package's dependencies to match.
+   - **Option B**: drop `external: [/^@cef-ai\/wallet/]` from `tsup.config.ts` so
+     the SDK bundle inlines them. Smaller dep tree for consumers; larger SDK.
+
+2. **Downstream type resolution.** Even after Option A above, the workspace
+   packages must publish their own `dist/` with `.d.ts` files. The current
+   workspace `package.json` files point `types` at `./src` (source). For publish
+   they'll need their own tsup configs and matching publishConfig.
+
+3. **Pack validation.** Add a `pack-dry-run` CI step that runs
+   `npm pack --dry-run --json` and asserts `dist/index.js`, `dist/index.cjs`,
+   `dist/index.d.ts`, `dist/index.d.cts` are all present and no source `.ts`
+   files leak through.
+
+## Quick start
+
+```ts
+import { EmbedWallet } from '@cef-ai/wallet';
+
+const wallet = new EmbedWallet({
+  appId: 'my-app',
+  appName: 'My App',
+  walletOrigin: 'https://wallet.example.com', // required: your wallet deployment origin
+});
+
+// First-time users register a passkey; returning users call login().
+const session = await wallet.login();
+console.log('Cere address:', session.addresses.cere);
+
+// Signing is per-chain. Pick a signer for the chain you need, then call its
+// `signMessage(bytes)` (returns raw signature bytes).
+const signer = wallet.getSigner({ chain: 'cere' });
+const sig = await signer.signMessage(new TextEncoder().encode('Hello'));
+console.log('Signature bytes:', sig);
+```
+
+## Architecture
+
+- A popup-window-based transport (`PopupTransport`) opens `wallet.example.com/embed/wallet?origin=...`
+- The popup runs the wallet UI, performs the WebAuthn ceremony, and posts results back
+- Cross-tab session sharing via `BroadcastChannel('scp-wallet-v2')` so a second host tab discovers an existing session
+
+Design specs and ADRs are maintained in the company memory bank.
+
+## Capabilities
+
+- `register({ label? })` / `login()` — opens the popup, performs the WebAuthn ceremony, returns the session
+- `getSigner({ chain })` — returns an `EthersSigner` (`'evm'`), `PolkadotSigner` (`'cere'`), or `SolanaSigner` (`'solana'`); each exposes `signMessage(bytes: Uint8Array): Promise<Uint8Array>`
+- `requestDelegation({ capabilities, ttl, appId?, agentPubkey?, constraints? })` — requests a scoped delegation token; the popup shows a consent UI
+- `saveApplication(record)` / `findApplications(filter)` — manage app context records
+- `logout()` — closes the session locally + broadcasts so other tabs do the same
+- `dispose()` — tear-down hook; closes any open popup and removes listeners
+
+## License
+
+MIT.

package/dist/index.cjs

@@ -0,0 +1,597 @@
+'use strict';
+
+var walletApiClient = require('@cef-ai/wallet-api-client');
+var walletIdentity = require('@cef-ai/wallet-identity');
+var walletSigners = require('@cef-ai/wallet-signers');
+
+var __defProp = Object.defineProperty;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+
+// src/transport/origin.ts
+var ALLOWED_ORIGIN_SCHEMES = ["https:", "http:"];
+function isMatchingOrigin(a, b) {
+  if (!a || !b) return false;
+  try {
+    const ua = new URL(a);
+    const ub = new URL(b);
+    return ua.origin === ub.origin;
+  } catch (e) {
+    return false;
+  }
+}
+
+// src/transport/PopupTransport.ts
+var DEFAULT_FEATURES = "width=420,height=640,resizable=yes,scrollbars=yes";
+var PopupTransport = class {
+  constructor(options) {
+    this.popup = null;
+    this.pending = /* @__PURE__ */ new Map();
+    this.listener = null;
+    this.popupReady = false;
+    this.outbox = [];
+    this.opts = __spreadValues({
+      openPopup: defaultOpener,
+      hostWindow: globalThis.window,
+      defaultTimeoutMs: 6e4
+    }, options);
+  }
+  request(_0, _1) {
+    return __async(this, arguments, function* (message, expectedTypes, init = {}) {
+      var _a, _b, _c;
+      if (!this.popup || this.popup.closed) {
+        const hostOrigin = (_b = (_a = globalThis.location) == null ? void 0 : _a.origin) != null ? _b : "";
+        const url = `${this.opts.walletOrigin}/embed/wallet?origin=${encodeURIComponent(hostOrigin)}`;
+        this.popup = this.opts.openPopup(url, DEFAULT_FEATURES);
+        if (!this.popup) {
+          throw new walletApiClient.WalletError("popup-blocked", "popup window failed to open");
+        }
+        this.popupReady = false;
+        this.outbox = [];
+        this.ensureListening();
+      }
+      const id = message.id;
+      const timeoutMs = (_c = init.timeoutMs) != null ? _c : this.opts.defaultTimeoutMs;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          if (this.pending.has(id)) {
+            this.pending.delete(id);
+            this.outbox = this.outbox.filter((m) => m.id !== id);
+            reject(new walletApiClient.WalletError("internal", `request "${message.type}" (id=${id}) timed out after ${timeoutMs}ms`));
+          }
+        }, timeoutMs);
+        this.pending.set(id, {
+          expectedTypes,
+          resolve: (msg) => resolve(msg),
+          reject,
+          timer
+        });
+        if (this.popupReady) {
+          this.popup.postMessage(message, this.opts.walletOrigin);
+        } else {
+          this.outbox.push(message);
+        }
+      });
+    });
+  }
+  /** Close the popup if open. Pending requests will time out normally. */
+  close() {
+    if (this.popup && !this.popup.closed) {
+      this.popup.close();
+    }
+    this.popup = null;
+    this.popupReady = false;
+    this.outbox = [];
+  }
+  /**
+   * Tear down the transport entirely. Closes the popup AND removes the host-
+   * window message listener. After `destroy()`, the transport instance cannot
+   * be reused — callers should drop the reference.
+   *
+   * Use `close()` if you only want to close the popup but keep the transport
+   * alive for a later re-open.
+   */
+  destroy() {
+    this.close();
+    if (this.listener) {
+      this.opts.hostWindow.removeEventListener("message", this.listener);
+      this.listener = null;
+    }
+  }
+  // ---- internal -------------------------------------------------------------
+  ensureListening() {
+    if (this.listener) return;
+    this.listener = (event) => this.onMessage(event);
+    this.opts.hostWindow.addEventListener("message", this.listener);
+  }
+  onMessage(event) {
+    if (!isMatchingOrigin(event.origin, this.opts.walletOrigin)) {
+      const data2 = event.data;
+      if (data2 && typeof data2.id === "string" && this.pending.has(data2.id)) {
+        const pending2 = this.pending.get(data2.id);
+        this.pending.delete(data2.id);
+        clearTimeout(pending2.timer);
+        pending2.reject(
+          new walletApiClient.WalletError(
+            "origin-mismatch",
+            `message from "${event.origin}" rejected (expected "${this.opts.walletOrigin}")`
+          )
+        );
+      }
+      return;
+    }
+    const data = event.data;
+    if (!data || typeof data.type !== "string" || typeof data.id !== "string") return;
+    if (data.type === "wallet:ready") {
+      if (this.popupReady) return;
+      this.popupReady = true;
+      const toFlush = this.outbox;
+      this.outbox = [];
+      if (this.popup && !this.popup.closed) {
+        for (const m of toFlush) {
+          this.popup.postMessage(m, this.opts.walletOrigin);
+        }
+      }
+      return;
+    }
+    const pending = this.pending.get(data.id);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    this.pending.delete(data.id);
+    if (data.type === "wallet:error") {
+      pending.reject(new walletApiClient.WalletError(data.code, data.message, data.traceId));
+      return;
+    }
+    if (!pending.expectedTypes.includes(data.type)) {
+      pending.reject(
+        new walletApiClient.WalletError("internal", `received unexpected response type "${data.type}" for id "${data.id}"`)
+      );
+      return;
+    }
+    pending.resolve(data);
+  }
+};
+function defaultOpener(url, features) {
+  const w = globalThis.window;
+  const opened = w == null ? void 0 : w.open(url, "_blank", features);
+  return opened;
+}
+
+// src/EmbedWallet.ts
+var EmbedWallet = class {
+  constructor(opts) {
+    this._addresses = null;
+    this._credentialId = null;
+    this._listeners = {};
+    var _a, _b, _c, _d, _e, _f, _g;
+    const injectedTransport = (_a = opts.__internal__) == null ? void 0 : _a.transport;
+    if (!injectedTransport && !opts.walletOrigin) {
+      throw new Error("EmbedWallet: `walletOrigin` is required (e.g. https://wallet.example.com).");
+    }
+    this.appId = opts.appId;
+    this.walletOrigin = (_b = opts.walletOrigin) != null ? _b : "";
+    this.popup = { width: (_d = (_c = opts.popup) == null ? void 0 : _c.width) != null ? _d : 420, height: (_f = (_e = opts.popup) == null ? void 0 : _e.height) != null ? _f : 640 };
+    this.appName = (_g = opts.appName) != null ? _g : "";
+    this.transport = injectedTransport != null ? injectedTransport : new PopupTransport({
+      walletOrigin: this.walletOrigin
+    });
+  }
+  get isLoggedIn() {
+    return this._addresses !== null;
+  }
+  get addresses() {
+    return this._addresses;
+  }
+  get credentialId() {
+    return this._credentialId;
+  }
+  register() {
+    return __async(this, arguments, function* (opts = {}) {
+      return this.helloAndAwaitLogin("register", opts);
+    });
+  }
+  login() {
+    return __async(this, null, function* () {
+      return this.helloAndAwaitLogin("login");
+    });
+  }
+  logout() {
+    return __async(this, null, function* () {
+      if (!this._addresses) {
+        this.transport.close();
+        return;
+      }
+      const id = crypto.randomUUID();
+      try {
+        yield this.transport.request({ type: "wallet:logout", id }, [
+          "wallet:result"
+        ]);
+      } catch (_err) {
+      }
+      this._addresses = null;
+      this._credentialId = null;
+      this.transport.close();
+      this.emit("logout", { type: "logout" });
+    });
+  }
+  getSigner(spec) {
+    this.assertLoggedIn("getSigner");
+    const sign = (chain, payload) => __async(this, null, function* () {
+      const id = crypto.randomUUID();
+      const result = yield this.transport.request(
+        { type: "wallet:sign", id, chain, payload, requestKind: "sdk" },
+        ["wallet:result"]
+      );
+      const sig = result.result;
+      if (!(sig instanceof Uint8Array)) {
+        throw new walletApiClient.WalletError("internal", `popup returned non-Uint8Array sign result (got ${typeof sig})`);
+      }
+      return sig;
+    });
+    const addresses = this._addresses;
+    switch (spec.chain) {
+      case "evm":
+        return new walletSigners.EthersSigner({ address: addresses.evm, sign });
+      case "cere":
+        return new walletSigners.PolkadotSigner({ address: addresses.cere, sign });
+      case "solana":
+        return new walletSigners.SolanaSigner({ address: addresses.solana, sign });
+      default:
+        throw new walletApiClient.WalletError("validation", `getSigner: unknown chain "${String(spec.chain)}"`);
+    }
+  }
+  /**
+   * Expose the wallet as a chain-free `@cef-ai/signer` over the Cere
+   * Ed25519 key — the pluggable-signer seam `@cef-ai/account` consumes for DDC
+   * and `@cef-ai/chain` adapts for extrinsics.
+   *
+   * `publicKey` is recovered from the (public) Solana address — no key material
+   * leaves the popup's `SessionVault`. `sign(bytes, 'extrinsic', { humanReadable })`
+   * routes through the popup's extrinsic-consent screen.
+   */
+  asSigner() {
+    this.assertLoggedIn("asSigner");
+    const addresses = this._addresses;
+    const send = (payload, intent, humanReadable) => __async(this, null, function* () {
+      if (!this.isLoggedIn) {
+        throw new walletApiClient.WalletError("unauthorized", "asSigner: wallet is no longer logged in");
+      }
+      const id = crypto.randomUUID();
+      const result = yield this.transport.request(
+        { type: "wallet:sign", id, chain: "cere", payload, requestKind: intent != null ? intent : "sdk", humanReadable },
+        ["wallet:result"]
+      );
+      const sig = result.result;
+      if (!(sig instanceof Uint8Array)) {
+        throw new walletApiClient.WalletError("internal", `popup returned non-Uint8Array sign result (got ${typeof sig})`);
+      }
+      return sig;
+    });
+    return {
+      type: "ed25519",
+      address: addresses.cere,
+      publicKey: walletIdentity.decodeEd25519Pubkey(addresses.solana),
+      isReady: () => __async(this, null, function* () {
+        return this.isLoggedIn;
+      }),
+      sign: (bytes, intent, opts) => send(bytes, intent, opts == null ? void 0 : opts.humanReadable)
+    };
+  }
+  requestDelegation(req) {
+    return __async(this, null, function* () {
+      this.assertLoggedIn("requestDelegation");
+      const id = crypto.randomUUID();
+      const scope = {
+        capabilities: req.capabilities,
+        appId: req.appId,
+        agentPubkey: req.agentPubkey,
+        constraints: req.constraints
+      };
+      const result = yield this.transport.request(
+        { type: "wallet:requestDelegation", id, scope, ttl: req.ttl },
+        ["wallet:result"]
+      );
+      return result.result;
+    });
+  }
+  findApplications() {
+    return __async(this, arguments, function* (filter = {}) {
+      this.assertLoggedIn("findApplications");
+      const id = crypto.randomUUID();
+      const result = yield this.transport.request(
+        { type: "wallet:findApplications", id, appId: filter.appId },
+        ["wallet:result"]
+      );
+      return result.result;
+    });
+  }
+  saveApplication(body) {
+    return __async(this, null, function* () {
+      this.assertLoggedIn("saveApplication");
+      const id = crypto.randomUUID();
+      const result = yield this.transport.request(
+        { type: "wallet:saveApplication", id, permissions: body.permissions, email: body.email },
+        ["wallet:result"]
+      );
+      return result.result;
+    });
+  }
+  on(type, listener) {
+    var _a;
+    const map = this._listeners;
+    ((_a = map[type]) != null ? _a : map[type] = /* @__PURE__ */ new Set()).add(listener);
+    return this;
+  }
+  off(type, listener) {
+    var _a;
+    const map = this._listeners;
+    (_a = map[type]) == null ? void 0 : _a.delete(listener);
+    return this;
+  }
+  /**
+   * Tear down the wallet instance. Closes any open popup, removes transport
+   * listeners, clears in-memory state. Call from your app's unmount hook.
+   *
+   * After dispose(), this instance is not reusable — construct a new one.
+   */
+  dispose() {
+    this._addresses = null;
+    this._credentialId = null;
+    this._listeners = {};
+    this.transport.destroy();
+  }
+  // ---- private --------------------------------------------------------------
+  appContext() {
+    const origin = typeof window !== "undefined" ? window.location.origin : "";
+    return { appId: this.appId, name: this.appName, origin };
+  }
+  helloAndAwaitLogin(_0) {
+    return __async(this, arguments, function* (intent, opts = {}) {
+      const id = crypto.randomUUID();
+      const helloMessage = {
+        type: "wallet:hello",
+        id,
+        appContext: this.appContext(),
+        intent,
+        label: opts.label
+      };
+      const result = yield this.transport.request(helloMessage, [
+        "wallet:login:ok"
+      ]);
+      this._addresses = result.addresses;
+      this._credentialId = result.credentialId;
+      this.emit("login", { type: "login", addresses: result.addresses });
+      return { addresses: result.addresses, credentialId: result.credentialId };
+    });
+  }
+  emit(type, ev) {
+    const set = this._listeners[type];
+    if (!set) return;
+    for (const listener of set) {
+      try {
+        listener(ev);
+      } catch (e) {
+      }
+    }
+  }
+  assertLoggedIn(method) {
+    if (!this._addresses) {
+      throw new walletApiClient.WalletError("unauthorized", `${method}: not logged in`);
+    }
+  }
+};
+
+// src/protocol.ts
+var BROADCAST_CHANNEL_NAME = "scp-wallet-v2";
+var PopupHostBridge = class {
+  constructor(options) {
+    this.handlers = {};
+    this.listener = null;
+    this.opts = __spreadValues({
+      popupWindow: globalThis.window
+    }, options);
+  }
+  /** Register a handler for a specific message type. Replaces any prior handler. */
+  on(type, handler) {
+    this.handlers[type] = handler;
+    return this;
+  }
+  /**
+   * Send a `PopupToHost` message back to the opener. The bridge does not
+   * remember the host-window reference itself — it reads `globalThis.opener`
+   * each call, so it survives popup re-opens.
+   */
+  send(message) {
+    const opener = globalThis.opener;
+    if (!opener || typeof opener.postMessage !== "function") {
+      return;
+    }
+    opener.postMessage(message, this.opts.hostOrigin);
+  }
+  /**
+   * Start listening for inbound messages.
+   *
+   * If `announceReady` is provided, sends a `wallet:ready` message immediately.
+   * Use this when the popup wants to signal "I'm here" without waiting for the
+   * host's first call.
+   */
+  start(opts = {}) {
+    if (this.listener) return;
+    this.listener = (event) => this.onMessage(event);
+    this.opts.popupWindow.addEventListener("message", this.listener);
+    if (opts.announceReady) {
+      this.send({ type: "wallet:ready", id: opts.announceReady.id });
+    }
+  }
+  stop() {
+    if (!this.listener) return;
+    this.opts.popupWindow.removeEventListener("message", this.listener);
+    this.listener = null;
+  }
+  // ---- internal -------------------------------------------------------------
+  onMessage(event) {
+    return __async(this, null, function* () {
+      var _a;
+      if (!isMatchingOrigin(event.origin, this.opts.hostOrigin)) {
+        return;
+      }
+      const data = event.data;
+      if (!data || typeof data.type !== "string" || typeof data.id !== "string") return;
+      const handler = this.handlers[data.type];
+      if (!handler) {
+        this.send({
+          type: "wallet:error",
+          id: data.id,
+          code: "internal",
+          message: `no handler registered for "${data.type}"`
+        });
+        return;
+      }
+      try {
+        yield handler(data, { origin: event.origin });
+      } catch (err) {
+        if (err instanceof walletApiClient.WalletError) {
+          this.send({
+            type: "wallet:error",
+            id: data.id,
+            code: err.code,
+            message: (_a = err.detail) != null ? _a : "",
+            traceId: err.traceId
+          });
+        } else {
+          this.send({
+            type: "wallet:error",
+            id: data.id,
+            code: "internal",
+            message: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+    });
+  }
+};
+
+// src/transport/BroadcastSessionShare.ts
+var DEFAULT_REQUEST_TIMEOUT_MS = 200;
+var BroadcastSessionShare = class {
+  constructor(opts) {
+    this.listening = false;
+    this.onMessage = (ev) => {
+      var _a, _b;
+      const msg = ev.data;
+      if (msg.type === "request-session") {
+        const session = this.opts.getSession();
+        if (!session || session.expMs <= Date.now()) return;
+        this.channel.postMessage({
+          type: "offer-session",
+          requestId: msg.requestId,
+          edSeed: session.edSeed,
+          secpKey: session.secpKey,
+          addresses: session.addresses,
+          expMs: session.expMs
+        });
+        return;
+      }
+      if (msg.type === "logout") {
+        (_b = (_a = this.opts).onLogout) == null ? void 0 : _b.call(_a);
+        return;
+      }
+    };
+    this.opts = opts;
+    this.channel = new BroadcastChannel(BROADCAST_CHANNEL_NAME);
+  }
+  /**
+   * Broadcast a `request-session` and wait for an `offer-session` from another
+   * tab. Resolves with the offered session, or null if nobody offered before
+   * the timeout.
+   */
+  request() {
+    return __async(this, arguments, function* (opts = {}) {
+      var _a;
+      const requestId = crypto.randomUUID();
+      const timeoutMs = (_a = opts.timeoutMs) != null ? _a : DEFAULT_REQUEST_TIMEOUT_MS;
+      return new Promise((resolve) => {
+        const onMsg = (ev) => {
+          if (ev.data.type === "offer-session" && ev.data.requestId === requestId && ev.data.expMs > Date.now()) {
+            this.channel.removeEventListener("message", onMsg);
+            clearTimeout(timer);
+            resolve({
+              edSeed: ev.data.edSeed,
+              secpKey: ev.data.secpKey,
+              addresses: ev.data.addresses,
+              expMs: ev.data.expMs
+            });
+          }
+        };
+        this.channel.addEventListener("message", onMsg);
+        const timer = setTimeout(() => {
+          this.channel.removeEventListener("message", onMsg);
+          resolve(null);
+        }, timeoutMs);
+        this.channel.postMessage({ type: "request-session", requestId });
+      });
+    });
+  }
+  /** Begin offering this tab's session in response to requests, and handle logouts. */
+  start() {
+    if (this.listening) return;
+    this.listening = true;
+    this.channel.addEventListener("message", this.onMessage);
+  }
+  stop() {
+    this.channel.removeEventListener("message", this.onMessage);
+    this.listening = false;
+  }
+  /** Notify peers that the user logged out. Peers wipe their sessions. */
+  broadcastLogout() {
+    this.channel.postMessage({ type: "logout" });
+  }
+  /** Free the underlying channel handle. Call from unload handlers. */
+  close() {
+    this.stop();
+    this.channel.close();
+  }
+};
+
+exports.ALLOWED_ORIGIN_SCHEMES = ALLOWED_ORIGIN_SCHEMES;
+exports.BROADCAST_CHANNEL_NAME = BROADCAST_CHANNEL_NAME;
+exports.BroadcastSessionShare = BroadcastSessionShare;
+exports.EmbedWallet = EmbedWallet;
+exports.PopupHostBridge = PopupHostBridge;
+exports.PopupTransport = PopupTransport;
+exports.isMatchingOrigin = isMatchingOrigin;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map