@sigcore/sdk 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -5,6 +5,6 @@ All notable changes to `@sigcore/sdk` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.5] - 2026-04-15
+## [0.1.6] - 2026-04-15
 
 Initial public release.

package/README.md

@@ -1,7 +1,17 @@
 # @sigcore/sdk
 
-Sigcore Iframe SDK for secure, non-custodial wallet operations.
-Designed for SaaS clients to embed wallet management via an isolated iframe bridge.
+TypeScript SDK for embedding [Sigcore](https://sigcore.io) wallet operations into your web application via a secure iframe bridge. Handles wallet creation, HD wallets, message signing, and token lifecycle — without ever exposing private keys to your frontend.
+
+## How it works
+
+The SDK loads a hidden iframe from the Sigcore wallet origin. All cryptographic operations happen inside that iframe and are never accessible to your app's JavaScript. Communication uses a typed `postMessage` protocol over a strict origin allowlist.
+
+```
+Your App                    Sigcore Bridge (iframe)
+───────────────────         ──────────────────────────
+client.createWallet()  ───> validates token + origin
+                       <─── sends result via postMessage
+```
 
 ## Installation
 
@@ -11,15 +21,15 @@ npm install @sigcore/sdk
 
 ## Quick Start
 
-The recommended entry point is `loadSigcore()`, which creates a hidden iframe, waits for the bridge to become ready, and returns a connected client:
-
 ```ts
 import { loadSigcore } from "@sigcore/sdk";
-import type { OrgId, HexString } from "@sigcore/sdk";
+import type { OrgId } from "@sigcore/sdk";
 
-const { client, bridgeVersion, protocolVersion, supportedActions, destroy } = await loadSigcore({
+// 1. Load the bridge — creates a hidden iframe and waits for it to be ready
+const { client, destroy } = await loadSigcore({
   bridgeUrl: "https://wallet.sigcore.io/v1/bridge.html",
   onTokenExpiring: async () => {
+    // Called ~15s before expiry — refresh your token here
     const fresh = await yourBackend.mintSigcoreToken();
     await client.setSigcoreAccessToken({
       accessToken: fresh.access_token,
@@ -27,41 +37,159 @@ const { client, bridgeVersion, protocolVersion, supportedActions, destroy } = aw
     });
   },
   onTokenExpired: () => {
-    console.warn("Sigcore token expired — re-authenticate");
+    // Token deadline passed — re-authenticate the user
+    redirectToLogin();
   },
 });
 
-// Inject the initial token (minted by your backend)
+// 2. Inject the access token minted by your backend
 await client.setSigcoreAccessToken({
   accessToken: mintedToken.access_token,
-  tokenType: mintedToken.token_type,
-  audience: "urn:sigcore:sigcore:grpc",
-  scope: mintedToken.scope,
   expiresIn: mintedToken.expires_in,
 });
 
-// Create a wallet
+// 3. Use the client
 const { wallet } = await client.createWallet({
-  orgId: "org_YOUR_ORG_ID_HERE" as OrgId,
+  orgId: "org_YOUR_ORG_ID" as OrgId,
   name: "Treasury",
   algorithm: "SECP256K1_ECDSA",
 });
 
-// Sign a message
+// 4. Clean up when your component unmounts
+destroy();
+```
+
+## Token Lifecycle
+
+Sigcore access tokens are short-lived JWT bearer tokens minted by your backend. The SDK manages expiry automatically:
+
+| Callback | When it fires |
+|---|---|
+| `onTokenExpiring` | `tokenRefreshBufferMs` before expiry (default 15s) |
+| `onTokenExpired` | When the token deadline passes |
+
+Always call `setSigcoreAccessToken()` with the new token inside `onTokenExpiring`. If the token expires before refresh, the bridge will reject all operations with `TOKEN_EXPIRED`.
+
+## API Reference
+
+### Wallets
+
+```ts
+// Create a new wallet
+const { wallet } = await client.createWallet({
+  orgId: "org_..." as OrgId,
+  name: "My Wallet",
+  algorithm: "SECP256K1_ECDSA", // or "ED25519"
+});
+
+// Import an existing private key
+const { wallet } = await client.importWallet({
+  orgId: "org_...",
+  name: "Imported",
+  algorithm: "SECP256K1_ECDSA",
+  privateKeyHex: "...",
+});
+
+// Get wallet details
+const { wallet } = await client.getWallet({
+  orgId: "org_...",
+  walletId: "wal_...",
+});
+
+// Update wallet name
+const { wallet } = await client.updateWallet({
+  orgId: "org_...",
+  walletId: "wal_...",
+  name: "New Name",
+  walletType: "FLAT",
+});
+
+// Delete a wallet
+const result = await client.deleteWallet({
+  orgId: "org_...",
+  walletId: "wal_...",
+  walletType: "FLAT",
+});
+
+// List wallets
+const { wallets, nextCursor, totalCount } = await client.listWallets({
+  orgId: "org_...",
+});
+```
+
+### Signing
+
+```ts
+import type { HexString } from "@sigcore/sdk";
+
 const { intent, policyRuling } = await client.signMessage({
-  orgId: wallet.orgId,
-  walletId: "wal_YOUR_WALLET_ID_HERE",
+  orgId: "org_...",
+  walletId: "wal_...",
   messageHex: "deadbeef" as HexString,
   chain: "ethereum",
 });
 
-// Clean up when done
-destroy();
+// policyRuling.decision is "ALLOW" | "DENY" | "PENDING"
+```
+
+### HD Wallets
+
+```ts
+// Create (returns a BIP-39 mnemonic — store it securely)
+const { wallet, mnemonic } = await client.createHDWallet({
+  orgId: "org_...",
+  name: "HD Treasury",
+  algorithm: "SECP256K1_ECDSA",
+});
+
+// Import from mnemonic
+const { wallet } = await client.importHDWallet({
+  orgId: "org_...",
+  name: "Restored",
+  algorithm: "SECP256K1_ECDSA",
+  mnemonic: "word1 word2 ...",
+});
+
+// List HD wallets
+const { wallets } = await client.listHDWallets({ orgId: "org_..." });
+```
+
+### Signing Intents (multi-party approval)
+
+```ts
+// Request a signature (may be held for approval)
+const { intent } = await client.createSigningIntent({
+  orgId: "org_...",
+  walletId: "wal_...",
+  payloadHex: "...",
+  chain: "ethereum",
+});
+
+// Approve or reject
+await client.approveIntent(intent.id);
+await client.rejectIntent(intent.id);
+```
+
+### Auth
+
+```ts
+// Validate a public session token issued by your auth flow
+const { session, email, status } = await client.validatePublicSession(token);
+
+// Consume a DPoP action proof
+const { proof } = await client.consumeActionProof({
+  organizationId: "org_...",
+  sessionId: "...",
+  actionKind: "wallet.sign",
+  requiredAssurance: "aal2",
+  httpMethod: "POST",
+  route: "/wallets/:id/sign",
+});
 ```
 
 ## Error Handling
 
-All SDK errors are instances of `SigcoreError` with a machine-readable `code` and a categorized `type`:
+All errors are instances of `SigcoreError`:
 
 ```ts
 import { SigcoreError, SigcoreErrorCode } from "@sigcore/sdk";
@@ -70,19 +198,77 @@ try {
   await client.createWallet(input);
 } catch (err) {
   if (err instanceof SigcoreError) {
-    // Specific error code for fine-grained handling
-    if (err.code === SigcoreErrorCode.REQUEST_TIMEOUT) {
-      console.error("Request timed out");
+    switch (err.code) {
+      case SigcoreErrorCode.TOKEN_EXPIRED:
+        // prompt re-authentication
+        break;
+      case SigcoreErrorCode.REQUEST_TIMEOUT:
+        // retry
+        break;
+      case SigcoreErrorCode.INCOMPATIBLE_BRIDGE:
+        // bridge version mismatch — update the SDK
+        break;
     }
 
-    // User-safe message (if provided by the server)
-    if (err.displayMessage) {
-      showToast(err.displayMessage);
-    }
+    // Safe user-facing message when available
+    if (err.displayMessage) showToast(err.displayMessage);
   }
 }
 ```
 
+### Error types
+
+| `err.type` | Meaning |
+|---|---|
+| `"authentication"` | Token missing, expired, or invalid |
+| `"network"` | Could not reach the bridge backend |
+| `"configuration"` | Bad SDK options or incompatible bridge |
+| `"server"` | Backend returned an error |
+
+## Testing
+
+A mock client is available for unit and integration tests — no iframe, no network:
+
+```ts
+import { createMockClient } from "@sigcore/sdk/testing";
+
+const client = createMockClient({
+  latencyMs: 50,      // simulate network delay
+  failOnSign: false,  // set true to test POLICY_DENIED paths
+  failAll: false,     // set true to test full failure paths
+});
+
+const { wallet } = await client.createWallet({
+  orgId: "org_test" as OrgId,
+  name: "Test Wallet",
+  algorithm: "ED25519",
+});
+
+client.dispose();
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and ships full type declarations. All branded types (`OrgId`, `WalletId`, `HexString`, etc.) are exported and can be used in your own type signatures.
+
+```ts
+import type {
+  OrgId,
+  WalletId,
+  WalletMetadata,
+  HexString,
+  SigcoreErrorType,
+  LoadSigcoreOptions,
+} from "@sigcore/sdk";
+```
+
+## Security
+
+- Private keys never leave the bridge iframe
+- All `postMessage` messages are validated against a strict origin allowlist
+- Bearer tokens are held in iframe memory only — never in `localStorage`, cookies, or the URL
+- The bridge uses `credentials: "omit"` for all backend fetches
+
 ## License
 
 [MIT](./LICENSE) — Copyright (c) 2026 Sigcore

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigcore/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Iframe SDK for Sigcore wallet operations — secure key management for SaaS clients",
   "type": "module",
   "main": "./dist/index.js",
@@ -57,7 +57,13 @@
     "typescript": "^5.8.2",
     "vitest": "^2.1.8"
   },
-  "publishConfig": {
+  "author": {
+    "name": "Sigcore",
+    "email": "hello@sigcore.io",
+    "url": "https://sigcore.io"
+  },
+  "homepage": "https://sigcore.io",
+"publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
@@ -68,6 +74,9 @@
     "iframe",
     "sdk",
     "crypto",
-    "mpc"
+    "mpc",
+    "web3",
+    "signing",
+    "non-custodial"
   ]
 }