@openkey/sdk 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -1,3 +1,54 @@
+/** NIP-01 unsigned event template. */
+interface UnsignedNostrEvent {
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+}
+/** A fully signed NIP-01 event, as returned by OpenKey custody signing. */
+interface SignedNostrEvent extends UnsignedNostrEvent {
+    id: string;
+    sig: string;
+}
+/** Public descriptor for the user's OpenKey-custodied Nostr identity. Never includes the secret key. */
+interface NostrIdentity {
+    keyId: string;
+    pubkey: string;
+    npub: string;
+}
+interface NostrError {
+    code: 'USER_CANCELLED' | 'TIMEOUT' | 'INTERACTION_REQUIRED' | 'UNAUTHORIZED' | 'UNKNOWN';
+    message: string;
+}
+/**
+ * Browser client for the OpenKey Nostr custody + signing flow. Get an
+ * instance from `OpenKey#nostr` rather than constructing this directly.
+ */
+declare class OpenKeyNostr {
+    private host;
+    constructor(host: string);
+    /**
+     * Get-or-create the user's OpenKey-custodied Nostr identity. Always shows
+     * a visible consent card (identity creation, or - when `relayUrl` is
+     * given - a relay-scoped kind:22242/NIP-42 grant for that exact relay).
+     * Never resolves with the secret key; only `keyId`/`pubkey`/`npub`.
+     */
+    connect(opts?: {
+        relayUrl?: string;
+    }): Promise<NostrIdentity>;
+    /**
+     * Sign a NIP-01 event template with the user's OpenKey Nostr key. Silent
+     * (no visible UI) when an active grant already covers this client origin
+     * + key + kind (+ exact relay, for kind 22242). Otherwise shows a visible
+     * consent card before signing - required for every first kind:9 message to
+     * a new origin, per NIP-29 channel-message policy.
+     */
+    signEvent(keyId: string, event: UnsignedNostrEvent): Promise<SignedNostrEvent>;
+    private widgetUrl;
+    private run;
+}
+
 interface EIP1193Provider {
     request(args: {
         method: string;
@@ -45,6 +96,20 @@ interface AuthResult {
     keyId: string;
     keyType: 'MANAGED' | 'EXTERNAL';
 }
+/**
+ * Confirmation returned by {@link OpenKey.signOut}. `requestId` is generated
+ * by the SDK and echoed by the OpenKey-owned widget, so callers can associate
+ * the acknowledgement with the sign-out they initiated.
+ */
+interface SignOutAcknowledgement {
+    requestId: string;
+    /**
+     * Whether the widget confirmed that the previous bearer no longer
+     * authenticates. `false` means the SDK is locally signed out, but remote
+     * revocation could not be verified.
+     */
+    revoked: boolean;
+}
 interface OpenKeyError {
     code: 'USER_CANCELLED' | 'POPUP_BLOCKED' | 'TIMEOUT' | 'NO_KEY' | 'UNAUTHORIZED' | 'UNKNOWN' | 'STATE_MISMATCH';
     message: string;
@@ -74,6 +139,176 @@ interface OAuthTokenResponse {
     scope: string;
     refresh_token?: string;
 }
+interface TinyCloudAuthorizationRequestV1 {
+    protocolVersion: 1;
+    /** Suggested SIWE (may be edited server-side before signing). */
+    siwe: string;
+    /** The keyId the user picked, if the caller has one in mind. */
+    keyId?: string;
+    /**
+     * The session-key JWK bound to `siwe`. Required so the server can
+     * regenerate a narrowed SIWE tied to the SAME session key when the
+     * user removes capabilities. Passing a mismatched jwk (or omitting it
+     * when the widget attempts to narrow) causes the /authorize-sign call
+     * to fail — never a silent fallback to the caller's exact bytes.
+     */
+    jwk?: Record<string, unknown>;
+    /**
+     * The TinyCloud host the resulting session will activate against.
+     * Bound into the /authorize-sign-prepare context so /authorize-sign
+     * cannot swap hosts server-side. Optional for callers that do not
+     * plan to activate a delegation (they should still forward it when
+     * known; the empty string is treated as "unknown").
+     */
+    host?: string;
+    /** Optional presentation envelope (name, reason, manifest). */
+    presentation?: CapabilityPresentationEnvelopeV1;
+}
+interface TinyCloudAuthorizationResultV1 {
+    protocolVersion: 1;
+    /** EIP-55 signer address. */
+    address: string;
+    /** Signature over `signedMessage`. */
+    signature: string;
+    /** The EXACT bytes the signature verifies against. Never the caller's original. */
+    signedMessage: string;
+    /** The action IDs the user (or default consent) selected. */
+    selectedActionKeys: string[];
+    /** Effective grant set after any narrowing. */
+    permissions: Array<{
+        service: string;
+        space: string;
+        path: string;
+        actions: string[];
+    }>;
+}
+interface CapabilityPresentationEnvelopeV1 {
+    protocolVersion: 1;
+    /** Human-readable requester name shown in the review. */
+    displayName?: string;
+    /**
+     * Reason string the requester supplied for the delegation. Rendered as
+     * caller-supplied (never as verified) unless a signed manifest carries
+     * the same reason string.
+     */
+    reason?: string;
+    /** Manifest ID + digest, when the app publishes a signed manifest. */
+    manifestId?: string;
+    manifestDigest?: string;
+    /**
+     * Full manifest payload(s) the caller wants surfaced in the review. The
+     * receiving route validates and size-bounds this before it is used. This
+     * is display-only: no metadata may expand authority beyond what the
+     * ReCap already grants. Bounded to a reasonable size at the transport
+     * boundary — oversized envelopes are dropped.
+     */
+    manifests?: Array<{
+        name?: string;
+        appId?: string;
+        payload?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Sol final continuation contract requirement 5: pure validation of an
+ * incoming iframe resize message envelope. Exported so unit tests can
+ * exercise every rejection branch — wrong requestId, wrong version, no
+ * active request, malformed height — without booting the browser
+ * runtime that `IframeModal` requires.
+ *
+ * Returns the sanitized height when acceptable, or `null` when the
+ * message must be dropped.
+ */
+declare function validateIframeResize(incoming: unknown, expected: {
+    requestId: string | null;
+    protocolVersion: number | null;
+    viewportHeight: number;
+}): number | null;
+/**
+ * Sol MAJOR-4 (final): pure routing helper — decides whether an
+ * `authorizeTinyCloud` call should route through the external-wallet
+ * preview→sign→finalize flow or the managed-key widget-signs-server-side
+ * flow. Exported so unit tests can exercise every branch
+ * (explicit-external + external-session, explicit-external + external-
+ * session with different keyId, no-explicit + external-session,
+ * explicit-managed + managed-session, no-session) without booting the
+ * browser runtime.
+ *
+ * The decision is authoritative from the ACTIVE session's keyType when
+ * no explicit `requestKeyId` was supplied.
+ *
+ * Kept as a thin wrapper for backwards compatibility. New callers should
+ * prefer `resolveAuthorizeTinyCloudRouting` which also considers the
+ * request's explicit `keyId`.
+ */
+declare function shouldRouteAuthorizeTinyCloudExternal(state: {
+    lastAuth: {
+        keyType?: 'MANAGED' | 'EXTERNAL' | null;
+    } | null;
+}): boolean;
+/**
+ * Sol MAJOR-4 (final continuation): resolve the target key's identity and
+ * route by that key's type — NOT by `lastAuth.keyType` alone.
+ *
+ * Sol's rejection: when the caller supplies an explicit `requestKeyId`
+ * that identifies a DIFFERENT key than `lastAuth.keyId` (address vs
+ * internal id, or a genuinely different key), the SDK must
+ *   - resolve THAT key's type,
+ *   - route by that resolved type (external ⇒ wallet path, managed ⇒
+ *     server-signing path), and
+ *   - reject an inconsistent explicit pin whose resolved type contradicts
+ *     the caller's other implicit assumptions (e.g. `lastAuth` is
+ *     external but the caller pinned a managed key).
+ *
+ * Inputs:
+ *   - `lastAuth`: the connected-session key metadata (may be null on
+ *     boot; the widget renders a connect flow first in that case).
+ *   - `requestKeyId`: the caller's explicit pin (may be absent).
+ *   - `knownKeys`: any keys we have metadata for; the SDK's higher-level
+ *     `authorizeTinyCloud` populates this from the server before calling
+ *     the resolver so the pure helper is fully synchronous and testable.
+ *
+ * Return shape:
+ *   { route: 'external' | 'managed', resolvedKeyId: string | null,
+ *     resolvedKeyType: 'EXTERNAL' | 'MANAGED' | null }
+ *
+ * `resolvedKeyId` is null only when neither `requestKeyId` nor
+ * `lastAuth.keyId` exists. When both exist and identify the same key
+ * (matching id OR matching known-key type), the resolver returns that
+ * shared identity. When both exist and identify different keys AND we
+ * know both types AND those types disagree, the resolver throws
+ * `KEY_ID_TYPE_MISMATCH` so no silent route coercion occurs.
+ */
+interface AuthorizeTinyCloudRouting {
+    route: 'external' | 'managed';
+    resolvedKeyId: string | null;
+    resolvedKeyType: 'EXTERNAL' | 'MANAGED' | null;
+}
+declare class KeyIdTypeMismatchError extends Error {
+    code: 'KEY_ID_TYPE_MISMATCH';
+    requestKeyId: string;
+    lastAuthKeyId: string | null;
+    requestKeyType: 'EXTERNAL' | 'MANAGED' | null;
+    lastAuthKeyType: 'EXTERNAL' | 'MANAGED' | null;
+    constructor(fields: {
+        message: string;
+        requestKeyId: string;
+        lastAuthKeyId: string | null;
+        requestKeyType: 'EXTERNAL' | 'MANAGED' | null;
+        lastAuthKeyType: 'EXTERNAL' | 'MANAGED' | null;
+    });
+}
+declare function resolveAuthorizeTinyCloudRouting(state: {
+    lastAuth: {
+        keyId?: string | null;
+        keyType?: 'MANAGED' | 'EXTERNAL' | null;
+    } | null;
+    requestKeyId?: string | null;
+    knownKeys?: ReadonlyArray<{
+        id: string;
+        address?: string;
+        keyType: 'MANAGED' | 'EXTERNAL';
+    }>;
+}): AuthorizeTinyCloudRouting;
 declare class OpenKey {
     private host;
     private oauthHost;
@@ -84,6 +319,16 @@ declare class OpenKey {
     private lastAuth;
     private discoveredProviders;
     private sessionToken;
+    /** Cancels widget flows that could outlive a sign-out on this instance. */
+    private activeFlowCancellations;
+    /**
+     * Nostr identity custody + signing (secp256k1 Schnorr / BIP-340). Kept
+     * fully separate from the Ethereum flows above: it never reuses
+     * `lastAuth`/`sessionToken`, and its widget messages never carry a
+     * sessionToken - the OpenKey session and any signing grants stay inside
+     * the OpenKey-origin iframe for the whole lifetime of this client.
+     */
+    readonly nostr: OpenKeyNostr;
     constructor(config?: OpenKeyConfig);
     /**
      * Derive the OAuth API host from the main host by prefixing 'api.'
@@ -91,6 +336,20 @@ declare class OpenKey {
      * @returns The derived OAuth API host URL
      */
     private deriveOAuthHost;
+    /**
+     * Sol MAJOR-4 (final continuation): fetch the caller's registered keys
+     * so `resolveAuthorizeTinyCloudRouting` can resolve an explicit pin
+     * whose keyId does not match the active session key. Called only when
+     * the caller passes a `requestKeyId` we do not already recognise; the
+     * common no-pin path skips the network round-trip.
+     *
+     * Failures do NOT block routing — we fall through with `knownKeys=[]`
+     * so the resolver's lastAuth-based fallback still runs. If the caller
+     * pinned a genuinely unknown key that turns out to be external, the
+     * widget rejects the server-signing path and the SDK surfaces that
+     * error from the finalize call rather than silently routing wrong.
+     */
+    private fetchKnownKeysIfNeeded;
     /**
      * Connect to OpenKey and get user's wallet address
      * Opens auth flow for user to select/create a key
@@ -98,6 +357,17 @@ declare class OpenKey {
     connect(opts?: {
         mode?: OpenKeyMode;
     }): Promise<AuthResult>;
+    /**
+     * Signs the active OpenKey account out through the OpenKey-owned widget.
+     *
+     * The SDK passes its Better Auth bearer through the OpenKey-owned widget
+     * protocol so applications do not have to implement revocation themselves.
+     * Local SDK session state is cleared before opening the widget, including
+     * when remote revocation is unavailable.
+     */
+    signOut(opts?: {
+        mode?: OpenKeyMode;
+    }): Promise<SignOutAcknowledgement>;
     /**
      * Better-auth session token relayed during connect(), or null if the
      * flow did not provide one. Use as a bearer token for API calls made
@@ -130,6 +400,47 @@ declare class OpenKey {
     signMessage(request: SignMessageRequest, opts?: {
         mode?: OpenKeyMode;
     }): Promise<SignResult>;
+    /**
+     * Versioned TinyCloud authorization protocol (v1).
+     *
+     * Unlike `signMessage()` (which is contractually byte-exact — the returned
+     * signature always verifies against the caller's exact bytes), this method
+     * permits the user to narrow the requested capabilities before signing.
+     * OpenKey may therefore regenerate the SIWE. The response carries
+     * `signedMessage` — the exact bytes the signature actually verifies against.
+     *
+     * TinyCloud completes the session with `signedMessage`, not the original
+     * `siwe` passed in. Consumers MUST use the returned bytes and MUST NOT
+     * assume the returned grants are a superset of what they requested — the
+     * user is allowed to remove any grant that is not required.
+     *
+     * Legacy `signMessage()` callers are unaffected: their exact-byte contract
+     * remains preserved and OpenKey never rewrites their bytes.
+     */
+    authorizeTinyCloud(request: TinyCloudAuthorizationRequestV1, opts?: {
+        mode?: OpenKeyMode;
+    }): Promise<TinyCloudAuthorizationResultV1>;
+    /**
+     * Sol MAJOR-3 (continuation): authorizeTinyCloud path for external keys.
+     * The wallet lives outside OpenKey, so the SDK opens the shared widget
+     * for review + preview, then invokes the user's wallet to sign the
+     * preview bytes, then finalizes server-side via /authorize-sign.
+     *
+     * Flow:
+     *   1. Open the widget with `externalSign: true` — the widget renders
+     *      the shared SigningApproval UI, calls /authorize-sign-prepare,
+     *      calls /authorize-sign-preview after the user approves a
+     *      selection, and hands back `{ previewApprovalToken,
+     *      signedMessage, selectedActionIds, address, authorizationContextToken }`.
+     *   2. SDK invokes the user's wallet on the returned signedMessage.
+     *   3. SDK POSTs /authorize-sign with `externalSignature`.
+     *
+     * Legacy exact-byte signMessage callers are unaffected — this path is
+     * only taken via authorizeTinyCloud (protocolVersion:1) when the target
+     * key is EXTERNAL. Sol's rejection required this path to go through
+     * the same review UI as managed keys.
+     */
+    private authorizeTinyCloudExternal;
     /**
      * Sign typed data (EIP-712) with the user's OpenKey wallet
      * For external keys, routes directly to the user's wallet provider
@@ -199,9 +510,11 @@ declare class OpenKey {
     private hasDetectedEoa;
     private openFlow;
     private openIframeModal;
+    private isResponseForAction;
     private handleWalletLinkDelegation;
     private handleExternalWalletConnect;
     private openPopup;
+    private cancelActiveFlows;
     /**
      * Disconnect and close any open flows
      */
@@ -227,4 +540,4 @@ declare class OpenKeyProvider implements EIP1193Provider {
 
 declare function getOpenKey(config?: OpenKeyConfig): OpenKey;
 
-export { type AuthResult, type EIP1193Provider, type OAuthConfig, type OAuthResult, type OAuthTokenResponse, OpenKey, type OpenKeyConfig, type OpenKeyError, type OpenKeyMode, OpenKeyProvider, type SignMessageRequest, type SignResult, type SignTypedDataRequest, OpenKey as default, getOpenKey };
+export { type AuthResult, type AuthorizeTinyCloudRouting, type CapabilityPresentationEnvelopeV1, type EIP1193Provider, KeyIdTypeMismatchError, type NostrError, type NostrIdentity, type OAuthConfig, type OAuthResult, type OAuthTokenResponse, OpenKey, type OpenKeyConfig, type OpenKeyError, type OpenKeyMode, OpenKeyNostr, OpenKeyProvider, type SignMessageRequest, type SignOutAcknowledgement, type SignResult, type SignTypedDataRequest, type SignedNostrEvent, type TinyCloudAuthorizationRequestV1, type TinyCloudAuthorizationResultV1, type UnsignedNostrEvent, OpenKey as default, getOpenKey, resolveAuthorizeTinyCloudRouting, shouldRouteAuthorizeTinyCloudExternal, validateIframeResize };