SDK reference

@soropass/core is a minimal, headless, ES256-only passkey SDK for Stellar smart accounts. This page is the core reference: registration, public-key extraction, and passkey signing. Connect, recovery, multi-device signers, and the submission/indexer adapters live on Accounts, recovery & adapters.

SDK at a glance

• Tree-shakeable subpaths: import only /create, /sign, /connect, /recover, /types, or /testing; the heavy crypto (noble) is shared and pulled only when /create or /sign is imported.
• ~2 runtime deps: @noble/curves + @noble/hashes; the core barrel entry is ~3.9 KB gzip, individual subpath entries from ~0.15 KB (measured on the 0.3.1 dist).
• @stellar/stellar-sdk is a peer dependency, never bundled into the SDK output. Stated once here, it holds for every function on this page and the accounts page. Contract-specific work lives behind the AccountDeployer / adapters you supply.
• Invariants: ES256-only (alg −7), always low-S normalized, one frozen 10-code error taxonomy.

createPasskey

Register an ES256-only passkey, extract its SEC-1 public key (RS256 hard-fails), deploy a smart account through your factory, persist the credential id, and return the account.

import {
  createPasskey,
  assertES256,
  buildCreateOptions,
  browserWebAuthnClient,
  defaultCredentialStorage,
  coseKeyToSec1,
} from '@soropass/core/create';

createPasskey(options: CreatePasskeyOptions): Promise<PasskeyCredential>

CreatePasskeyOptions

Returns: PasskeyCredential

import { createPasskey } from '@soropass/core/create';

const account = await createPasskey({
  rpId: 'app.example.com',
  rpName: 'Example',
  userName: 'alice@example.com',
  deployer, // your AccountDeployer
  residentKey: 'required',
  userActivation: navigator.userActivation, // Safari gesture rule
});

console.log(account.contractId); // C... smart-account address
console.log(account.credentialId); // persisted for connect()
console.log(account.publicKey.length); // 65 (SEC-1)

AccountDeployer

The contract-specific seam. createPasskey hands your deployer the extracted SEC-1 public key and credential id and expects the deployed smart-account address back, keeping the SDK free of contract coupling. (For the ready-made passkey-kit v1 deployer, see smartWalletV1Deployer.)

interface AccountDeployer {
  deploy(input: {
    publicKey: Uint8Array;
    credentialId: string;
  }): Promise<{ contractId: string; txHash?: string }>;
}

Registration primitives

createPasskey composes these internally; each is exported for advanced flows and testing. Override the WebAuthn ceremony or credential persistence via CreatePasskeyOptions.webauthn / .storage.

Public-key extraction

The path from a WebAuthn attestation to the 65-byte SEC-1 point the contract verifies. Each step is exported so you can extract from whichever shape you hold.

import { extractPublicKeyFromAttestationObject } from '@soropass/core/create';

// 65-byte SEC-1 point: 0x04 ‖ X ‖ Y. Non-P-256 keys throw ES256_NOT_SUPPORTED
const publicKey = extractPublicKeyFromAttestationObject(attestationObject);

Address derivation

Derive the smart account's C-address offline, with no deploy and no indexer round-trip: the same createCustomContract preimage the network hashes, computed locally. This is what makes a returning user's getAddress instant and infra-free.

Binding the public key into the salt is a security property, not bookkeeping: credential ids are public (the factory emits them in events), so a salt over the credential id alone let anyone pre-deploy at a victim's derived address with their own key, capturing anything sent there. With the key bound, deploying at a derived address requires the exact public key, so a squatted deploy produces the victim's intended account.

Both functions are exported from @soropass/core/create and throw a typed KitError on an invalid deployer address, an empty credential id, or (for deriveAccountAddress) a public key that is not 65 bytes.

import { deriveAccountAddress } from '@soropass/core/create';

const address = deriveAccountAddress({
  factoryContractId: 'C...FACTORY',
  credentialId: new TextEncoder().encode(account.credentialId),
  publicKey: account.publicKey, // 65-byte SEC-1, part of the salt
  networkPassphrase,
});
// address === account.contractId, with no network call

signTransaction

Sign every address-credential Soroban auth entry carried by the InvokeHostFunction operations of a transaction (base64 XDR envelope, v1 or fee-bump). Obtains a WebAuthn assertion, low-S-normalizes it, and assembles the contract signature your __check_auth re-derives. Returns the signed envelope XDR. A transaction that carries no Soroban address-credential auth entry comes back unchanged; set signerAddress to sign only the connected account's entries and leave a co-authorizer's entries untouched.

signTransaction(txXdr: string, options: SorobanSignOptions): Promise<string>

import { signTransaction, browserPasskeySigner } from '@soropass/core/sign';

const sign = browserPasskeySigner({ rpId, allowCredentials: [credentialId], publicKey });
const signedXdr = await signTransaction(txXdr, { networkPassphrase, sign });

signAuthEntry

Obtain a WebAuthn assertion, low-S-normalize, and assemble the contract signature for a single entry. Returns the signed entry as base64 XDR.

signAuthEntry(entryXdr: string, options: SorobanSignOptions): Promise<string>

SorobanSignOptions

Shared by signTransaction and signAuthEntry.

The default single-signer target assembles the four-field Secp256r1Signature struct the v0.2 webauthn-account consumes, a canonically sorted ScMap: { authenticator_data, client_data_json, public_key, signature }. The inline public_key names which enrolled signer the multi-signer account verifies against; the contract rejects a key it does not hold before any crypto runs. The smart-wallet target assembles the three-field passkey-kit v1 shape instead, which resolves the key on-chain by credential id.

For target: 'smart-wallet' and the full sign-and-submit path, see Accounts, recovery & adapters.

SignVerifyOptions

On-chain __check_auth is the real gate; the opt-in verify pre-flight catches a bad assertion client-side, turning an opaque on-chain failure into a typed KitError at the call site. Providing the object (even empty) always enforces the webauthn.get ceremony type, the challenge binding, and the User-Present (UP) flag; each field below adds its check. Omit the object entirely to skip pre-flight (the default).

browserPasskeySigner

Adapt navigator.credentials.get into the WebAuthnSigner that the sign functions expect. It receives a base64url challenge (the Soroban auth preimage), decodes it, runs the assertion, and returns the fields the auth assembler needs; the DER signature is low-S normalized downstream.

browserPasskeySigner(options: BrowserPasskeySignerOptions): WebAuthnSigner

BrowserPasskeySignerOptions

import { browserPasskeySigner, signTransaction } from '@soropass/core/sign';

const sign = browserPasskeySigner({
  rpId: 'app.example.com',
  allowCredentials: [credentialId], // omit for a discoverable (resident-key) prompt
  publicKey: account.publicKey, // travels inline in the single-signer struct
});

const signedXdr = await signTransaction(txXdr, { networkPassphrase, sign });

Low-S normalization

Invariant #2. Roughly 50% of Apple Touch ID / Face ID assertions come back high-S, and Soroban's secp256r1_verify does not enforce low-S, so the SDK must emit low-S before any contract sees the signature.

Assertion verification primitives

The parse and verify steps behind the verify pre-flight, each exported on its own from @soropass/core/sign so you can validate whichever piece you hold. The verify functions throw a typed KitError; the parse functions return structured data.

Soroban auth primitives

The primitives that derive the challenge the authenticator signs and reassemble the assertion into a verifiable SorobanAuthorizationEntry. For how the challenge is bound to the auth preimage, see Security.

Error taxonomy

Every throw in the SDK is a typed KitError, never a bare string. KitError extends Error with an exhaustive code from the frozen KIT_ERROR_CODES tuple; isKitError is the type guard. The v0.2 account contract additionally defines its own numeric contract errors, returned on-chain from __check_auth and the signer methods (for example UnknownSigner, UserVerifiedFlagMissing, LastSignerRemoval); those are Soroban contract errors carried in the transaction result, not KitError codes. All three come from @soropass/core/types (~182 B gzipped), which also exports BATTLE_TESTED_ANCHORS: the stable ids of the three behaviors that silently break real users (low-s-normalization, rs256-hard-fail, apple-user-gesture), referenced by name across the test suite, the threat model, and the compatibility matrix.

import { KitError, KIT_ERROR_CODES, isKitError } from '@soropass/core/types';
import type { KitErrorCode } from '@soropass/core/types';

class KitError extends Error {
  readonly code: KitErrorCode; // one of KIT_ERROR_CODES
  readonly name = 'KitError';
  // `cause` is inherited from Error, set when the original error is wrapped
}

// exhaustive over KIT_ERROR_CODES; the compiler flags a missing case
if (isKitError(err) && err.code === 'USER_CANCELLED') return retry();