@cef-ai/wallet 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,452 @@
+import { Addresses, Chain } from '@cef-ai/wallet-identity';
+import { EthersSigner, PolkadotSigner, SolanaSigner } from '@cef-ai/wallet-signers';
+import { WalletErrorCode } from '@cef-ai/wallet-api-client';
+
+/**
+ * The `@cef-ai/signer` contract, declared locally.
+ *
+ * `@cef-ai/signer` is published from the CEF-AI/sdk repo; until it is released
+ * we mirror its shape here so `EmbedWallet.asSigner()` can produce a
+ * structurally-compatible signer that `@cef-ai/account` consumes. When the
+ * package ships, replace this with `import type { Signer, SignIntent } from
+ * '@cef-ai/signer'`. The shape MUST stay in sync with that interface.
+ */
+type SignerType = 'ed25519' | 'sr25519' | 'ecdsa' | 'ethereum';
+type SignIntent = 'data' | 'token' | 'extrinsic';
+interface CefSigner {
+    readonly type: SignerType;
+    readonly address: string;
+    readonly publicKey: Uint8Array;
+    isReady(): Promise<boolean>;
+    /**
+     * Sign raw bytes. `intent` keys the wallet's consent UI ('extrinsic' raises
+     * the extrinsic-consent screen). `opts.humanReadable` is an out-of-band
+     * description shown best-effort on that screen — it is NOT part of the
+     * minimal `@cef-ai/signer` interface, just an extra the CEF wallet honors.
+     */
+    sign(bytes: Uint8Array, intent?: SignIntent, opts?: {
+        humanReadable?: string;
+    }): Promise<Uint8Array>;
+}
+
+interface AppContext {
+    appId: string;
+    name: string;
+    origin: string;
+}
+/** Spec §5.2. Messages sent from a host page to a wallet popup. */
+type HostToPopup = {
+    type: 'wallet:hello';
+    id: string;
+    appContext: AppContext;
+    intent: 'register' | 'login';
+    label?: string;
+} | {
+    type: 'wallet:requestDelegation';
+    id: string;
+    scope: DelegationScope;
+    ttl: string;
+} | {
+    type: 'wallet:sign';
+    id: string;
+    chain: Chain;
+    payload: Uint8Array;
+    requestKind: string;
+    humanReadable?: string;
+} | ({
+    type: 'wallet:saveApplication';
+    id: string;
+} & ApplicationBody) | ({
+    type: 'wallet:findApplications';
+    id: string;
+} & ApplicationFilter) | {
+    type: 'wallet:logout';
+    id: string;
+};
+/**
+ * Spec §5.2. Messages sent from a wallet popup back to the host.
+ *
+ * On `wallet:error`, `message` carries the human-readable detail
+ * (what `WalletError.detail` returns), NOT the compound `Error.message`
+ * (`"${code}: ${detail}"`). The compound is reconstructable from `code + message`
+ * on the receiving side. Serialisers in the popup MUST send `err.detail ?? ''`,
+ * not `err.message`.
+ */
+type PopupToHost = {
+    type: 'wallet:ready';
+    id: string;
+} | {
+    type: 'wallet:login:ok';
+    id: string;
+    addresses: Addresses;
+    credentialId: string;
+} | {
+    type: 'wallet:result';
+    id: string;
+    result: unknown;
+} | {
+    type: 'wallet:error';
+    id: string;
+    code: WalletErrorCode;
+    message: string;
+    traceId?: string;
+};
+/** Spec §5.5. Channel name: `scp-wallet-v2`. Wallet-origin tabs only. */
+type BroadcastChannelMessage = {
+    type: 'request-session';
+    requestId: string;
+} | {
+    type: 'offer-session';
+    requestId: string;
+    edSeed: Uint8Array;
+    secpKey: Uint8Array;
+    addresses: Addresses;
+    /** absolute Unix epoch ms when session keys expire */ expMs: number;
+} | {
+    type: 'logout';
+};
+declare const BROADCAST_CHANNEL_NAME = "scp-wallet-v2";
+
+/**
+ * The minimal subset of `Window` that we use for postMessage + lifecycle.
+ * Both real browser windows and `MessageChannel`-backed test doubles can
+ * satisfy this shape.
+ */
+interface PopupHandle {
+    postMessage(message: HostToPopup, targetOrigin: string): void;
+    close(): void;
+    readonly closed: boolean;
+}
+/** Opens a popup window. Defaults to `window.open(url, '_blank', features)`. */
+type PopupOpener = (url: string, features?: string) => PopupHandle | null;
+/**
+ * Subscriber for inbound messages on the host side. Both event.origin and
+ * event.data are passed through; the transport verifies origin before
+ * dispatching.
+ */
+type HostMessageListener = (event: {
+    data: PopupToHost;
+    origin: string;
+}) => void;
+/**
+ * Inbound message handler on the popup side. Receives only messages whose
+ * origin matched the expected host origin.
+ */
+type PopupMessageHandler<T extends HostToPopup = HostToPopup> = (message: T, meta: {
+    origin: string;
+}) => Promise<void> | void;
+
+interface PopupTransportOptions {
+    /** Expected origin of the wallet popup, e.g. 'https://wallet.example.com'. */
+    walletOrigin: string;
+    /** Defaults to `(url, features) => window.open(url, '_blank', features)`. */
+    openPopup?: PopupOpener;
+    /** Window object hosting the event listener. Defaults to `globalThis.window`. */
+    hostWindow?: Window;
+    /** Default per-request timeout. Defaults to 60_000 ms. */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Host-side popup transport. Spec §5.
+ *
+ * Use one `PopupTransport` instance per `EmbedWallet`. The instance owns a
+ * single popup window at a time, opens it on demand, auto-reopens on the next
+ * `request()` after it's been closed, and correlates each in-flight request
+ * by its message `id`.
+ *
+ * Wire handshake: every freshly opened popup must send `wallet:ready` before
+ * this transport will post any `HostToPopup` envelope. Without the handshake,
+ * `postMessage` may fire before the popup document has executed its `message`
+ * listener and the message is dropped. Outbound messages are queued in
+ * `outbox` while `popupReady === false`; `wallet:ready` flushes them.
+ */
+declare class PopupTransport {
+    private readonly opts;
+    private popup;
+    private pending;
+    private listener;
+    private popupReady;
+    private outbox;
+    constructor(options: PopupTransportOptions);
+    request<T extends PopupToHost>(message: HostToPopup, expectedTypes: T['type'][], init?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    /** Close the popup if open. Pending requests will time out normally. */
+    close(): void;
+    /**
+     * 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(): void;
+    private ensureListening;
+    private onMessage;
+}
+
+interface EmbedWalletOptions {
+    appId: string;
+    /**
+     * Origin where the wallet SPA is deployed, e.g. `https://wallet.example.com`.
+     * Required for real use (the SDK opens a popup to `${walletOrigin}/embed/wallet`
+     * and pins postMessage to this origin) — there is no default; the constructor
+     * throws if it is absent. Optional only when injecting a transport via the
+     * `__internal__` test seam, which already carries the origin.
+     */
+    walletOrigin?: string;
+    popup?: {
+        width?: number;
+        height?: number;
+    };
+    /** Optional name for the appContext sent via wallet:hello. Defaults to ''. */
+    appName?: string;
+    /**
+     * Test seam. Injects an alternative `PopupTransport` instance. Production
+     * callers leave this undefined and the SDK constructs its own transport.
+     */
+    __internal__?: {
+        transport?: PopupTransport;
+    };
+}
+
+interface LoginResult {
+    addresses: Addresses;
+    credentialId: string;
+}
+interface DelegationScope {
+    capabilities: string[];
+    appId?: string;
+    agentPubkey?: string;
+    constraints?: Record<string, unknown>;
+}
+interface DelegationRequest extends DelegationScope {
+    ttl: string;
+}
+interface DelegationResult {
+    token: string;
+    expiresAt: string;
+    issuer: string;
+}
+interface SignerSpec {
+    chain: Chain;
+}
+interface ApplicationFilter {
+    appId?: string;
+}
+interface ApplicationBody {
+    permissions: Record<string, unknown>;
+    email?: string;
+}
+/**
+ * Per-app record returned by `findApplications` / `saveApplication`. Mirrors
+ * the `Application` shape returned by wallet-api; duplicated here so
+ * embed-sdk consumers don't have to depend on `@cef-ai/wallet-api-client` for a
+ * type.
+ */
+interface ApplicationRecord {
+    appId: string;
+    address: string;
+    permissions: Record<string, unknown>;
+    email?: string;
+}
+type WalletEvent = {
+    type: 'login';
+    addresses: Addresses;
+} | {
+    type: 'logout';
+} | {
+    type: 'error';
+    code: WalletErrorCode;
+    message: string;
+};
+type WalletEventListener<T extends WalletEvent['type']> = (ev: Extract<WalletEvent, {
+    type: T;
+}>) => void;
+
+/**
+ * Public SDK class. v2.0.0. Spec §4.
+ *
+ * Drives the popup transport: every method that does meaningful work opens
+ * (or reuses) a popup at `walletOrigin/embed/*`, sends a `HostToPopup`
+ * message, awaits the matching `PopupToHost` response, and updates local
+ * state. See spec §5 for the wire protocol.
+ */
+declare class EmbedWallet {
+    readonly appId: string;
+    readonly walletOrigin: string;
+    readonly popup: {
+        width: number;
+        height: number;
+    };
+    readonly appName: string;
+    private _addresses;
+    private _credentialId;
+    private _listeners;
+    private readonly transport;
+    constructor(opts: EmbedWalletOptions);
+    get isLoggedIn(): boolean;
+    get addresses(): Addresses | null;
+    get credentialId(): string | null;
+    register(opts?: {
+        label?: string;
+    }): Promise<LoginResult>;
+    login(): Promise<LoginResult>;
+    logout(): Promise<void>;
+    getSigner(spec: {
+        chain: 'evm';
+    }): EthersSigner;
+    getSigner(spec: {
+        chain: 'cere';
+    }): PolkadotSigner;
+    getSigner(spec: {
+        chain: 'solana';
+    }): SolanaSigner;
+    getSigner(spec: SignerSpec): EthersSigner | PolkadotSigner | SolanaSigner;
+    /**
+     * 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(): CefSigner;
+    requestDelegation(req: DelegationRequest): Promise<DelegationResult>;
+    findApplications(filter?: ApplicationFilter): Promise<ApplicationRecord[]>;
+    saveApplication(body: ApplicationBody): Promise<ApplicationRecord>;
+    on<T extends WalletEvent['type']>(type: T, listener: WalletEventListener<T>): this;
+    off<T extends WalletEvent['type']>(type: T, listener: WalletEventListener<T>): 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(): void;
+    private appContext;
+    private helloAndAwaitLogin;
+    private emit;
+    private assertLoggedIn;
+}
+
+/**
+ * Origin verification helpers used by both ends of the popup transport.
+ * Spec §5.3.
+ */
+/**
+ * Schemes that we accept for origins. Production uses https only; we allow
+ * http here so test setups and `localhost:port` work — callers can layer
+ * tighter rules (e.g. "only https in production") on top.
+ */
+declare const ALLOWED_ORIGIN_SCHEMES: readonly string[];
+/**
+ * Strict origin equality check. Returns true iff both inputs are non-empty,
+ * URL-parseable, and have matching `origin` (scheme + host + port).
+ */
+declare function isMatchingOrigin(a: string | undefined, b: string | undefined): boolean;
+
+interface PopupHostBridgeOptions {
+    /** Expected origin of the host page (the page that opened this popup). */
+    hostOrigin: string;
+    /** The window this bridge runs in. Defaults to `globalThis`. */
+    popupWindow?: Window;
+}
+/**
+ * Popup-side bridge. Spec §5.
+ *
+ * The wallet SPA constructs one of these at boot, registers handlers via
+ * `on(type, fn)`, and calls `start()` to begin listening. Each inbound
+ * `HostToPopup` message that matches a registered handler is dispatched;
+ * the handler is responsible for calling `bridge.send(...)` to reply.
+ *
+ * Handlers may throw `WalletError`; the bridge automatically converts the
+ * throw into a `wallet:error` response keyed by the inbound message id.
+ */
+declare class PopupHostBridge {
+    private readonly opts;
+    private readonly handlers;
+    private listener;
+    constructor(options: PopupHostBridgeOptions);
+    /** Register a handler for a specific message type. Replaces any prior handler. */
+    on<T extends HostToPopup['type']>(type: T, handler: PopupMessageHandler<Extract<HostToPopup, {
+        type: T;
+    }>>): 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: PopupToHost): void;
+    /**
+     * 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?: {
+        announceReady?: {
+            id: string;
+        };
+    }): void;
+    stop(): void;
+    private onMessage;
+}
+
+interface BroadcastSession {
+    edSeed: Uint8Array;
+    secpKey: Uint8Array;
+    addresses: Addresses;
+    /** Absolute Unix epoch ms when the session expires. */
+    expMs: number;
+}
+interface BroadcastSessionShareOptions {
+    /**
+     * Returns the local session if this tab has one to offer. Called whenever
+     * another tab broadcasts `request-session`.
+     */
+    getSession: () => BroadcastSession | null;
+    /**
+     * Called when another tab broadcasts a `logout` message. The local handler
+     * should wipe its own session.
+     */
+    onLogout?: () => void;
+}
+/**
+ * Popup-side cross-tab session sharing. Spec §5.5.
+ *
+ * - `request()`: broadcast `request-session`, wait up to 200ms for an offer.
+ * - `start()`: listen for incoming requests; reply with `offer-session` if we
+ *   have a non-expired session and `getSession()` returns it.
+ * - `broadcastLogout()`: notify peers to wipe their sessions too.
+ *
+ * Channel name is the spec-locked `scp-wallet-v2`. Only wallet-origin popups
+ * join. Host pages do not participate.
+ */
+declare class BroadcastSessionShare {
+    private readonly channel;
+    private readonly opts;
+    private listening;
+    constructor(opts: BroadcastSessionShareOptions);
+    /**
+     * 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(opts?: {
+        timeoutMs?: number;
+    }): Promise<BroadcastSession | null>;
+    /** Begin offering this tab's session in response to requests, and handle logouts. */
+    start(): void;
+    stop(): void;
+    /** Notify peers that the user logged out. Peers wipe their sessions. */
+    broadcastLogout(): void;
+    /** Free the underlying channel handle. Call from unload handlers. */
+    close(): void;
+    private onMessage;
+}
+
+export { ALLOWED_ORIGIN_SCHEMES, type AppContext, type ApplicationBody, type ApplicationFilter, type ApplicationRecord, BROADCAST_CHANNEL_NAME, type BroadcastChannelMessage, type BroadcastSession, BroadcastSessionShare, type BroadcastSessionShareOptions, type CefSigner, type DelegationRequest, type DelegationResult, type DelegationScope, EmbedWallet, type EmbedWalletOptions, type HostMessageListener, type HostToPopup, type LoginResult, type PopupHandle, PopupHostBridge, type PopupHostBridgeOptions, type PopupMessageHandler, type PopupOpener, type PopupToHost, PopupTransport, type PopupTransportOptions, type SignIntent, type SignerSpec, type SignerType, type WalletEvent, type WalletEventListener, isMatchingOrigin };