@miyaocat/sdk-server

Server-side TypeScript client for the Miyao API. Typed against the versioned /v1 control-plane and test-only /v3 regional signing contracts, ESM and CJS, Node 20+. For backends only: never ship an API key or a stamp private key to a browser.

Install

npm install @miyaocat/sdk-server

Usage

import { MiyaoClient } from "@miyaocat/sdk-server";

const client = new MiyaoClient({
  baseUrl: "https://api.miyao.io",
  apiKey: process.env.MIYAO_API_KEY!,             // sf_live_… or sf_test_…
  stampPrivateKeyHex: process.env.MIYAO_STAMP_KEY, // required for high-value routes
});

const { wallet } = await client.wallets.create({ chain: "solana" });
const request = await client.signingRequests.create({
  wallet_id: wallet.id,
  transaction_base64: txBase64,
  intent: { version: 1, summary: "Send 1 SOL", kind: { type: "transfer", detail: { chain: "solana", to_address: "…", asset: "SOL", amount_atoms: 1_000_000_000 } } },
  expires_in_secs: 3600,
});

Errors are typed (MiyaoApiError and subclasses; the Fabric* names remain as deprecated aliases) and carry the stable error.code from the API. Requests that change state require an idempotency key, which the client sets for you.

For wallet device management, WalletDeviceClient accepts live or test server credentials. listDevices(walletId, scope, capability) returns the current device binding and structural backup metadata. Supply a wallet-scoped device-share-restore-v1 capability separately; the SDK sends it only in the x-sf-end-user-capability header. scope contains user_id, policy_id, and policy_revision.

revokeDevice(walletId, deviceGeneration, { ...scope, reason }, capability, idempotencyKey) requires a registered stamp signer and a wallet-scoped device-replacement-relay-v1 capability. reason is lost, compromised, or user_requested. Its result reports revoked only after runtime acknowledgment; revocation_pending means the durable control-plane tombstone exists while cell enforcement remains incomplete. Inventory and revocation responses reject unknown fields and malformed wallet, device, epoch, and backup metadata. These methods manage access records; their availability does not establish EVM same-address resharing or recovery readiness.

No-funds one-round server signing prerelease

For a customer BFF preparing a test browser, BrowserBootstrapClient exposes typed issueCapability(walletId, scope, idempotencyKey) and registerDevice(walletId, encryptedBackup, capability, idempotencyKey) calls. It requires a sf_test_ API key and a registered Ed25519 key or external ES256 stampSigner. The returned capability is wallet-bound, expires in 60 seconds, and is spent once on enrollment, encrypted device registration, or v3 session creation. See BROWSER-BOOTSTRAP-SERVER.md.

Use SigningPermitsV3Client with a sf_test_ API key and registered stamp key to call POST /v3/signing-permits before the gateway call. Supply the wallet, canonical unsigned Solana message in base64, its SHA-256, per-asset smallest-unit debits, and one idempotency key. Copy the returned wallet, home cell, key epoch, signer identity and authorization into OneRoundSignRequestV3; use the same idempotency key for signing. The permit expires after 30 seconds and cannot be reused.

For a non-exportable Azure Key Vault HSM P-256 key, register the API key with stamp_algorithm: "p256" and its lowercase uncompressed SEC1 public key. Construct the permit client with stampSigner: { algorithm: "p256", publicKeyHex, signDigest } instead of stampPrivateKeyHex. signDigest receives SHA-256 of the canonical request bytes and returns the HSM's 64-byte raw ES256 r||s signature. The SDK normalizes low-S. The same option works for all stamped FabricClient routes. See docs/api/REQUEST-STAMPS.md in the source repository for the pinned wire contract and journal link rule.

The issuance route requires explicit no-funds asset caps and an armed test epoch. A missing cap or any committed policy rule refuses issuance until a transaction-aware policy verdict is available. The server independently decodes the message and refuses declared debits that differ from its derived amounts. Unresolved lookup tables and unsupported programs are refused. Exact-input swap venue rules must be deployment reviewed and configured by the operator; none are enabled by default.

OneRoundV3Client targets the regional gateway's separate POST /v3/sign/one-round contract. It requires a short-lived, region-bound tx-execution bearer and an explicit one-use idempotency key. It sends exact message bytes as canonical base64, returns the aggregate signature and signer set, and throws OneRoundV3Error with a stable code. It never automatically retries an uncertain signing request. Verify the returned Ed25519 signature against the exact message and wallet public key before using it. This prerelease is limited to no-funds qualification; see docs/api/ONE-ROUND-V3.md in the source repository.

Versioning

/v1 is additive-only; the previous minor is supported for 90 days after the next minor ships. Pin an exact version.

Security

This package contains no key material and never assembles a private key. Report security issues to [email protected].

License

Apache-2.0. See LICENSE.

Documentation

https://miyao.io