@cfxdevkit/services

Scope: Stateless service primitives sitting just above @cfxdevkit/cdk.

Responsibilities

• AES-256-GCM encryption helpers
• Encrypted keystore format + read/write (file, memory, Ledger hardware wallet)
• DEX adapters (Swappi today; pluggable interface for future DEXs)
• Token metadata service
• Session token management and bearer token parsing
• Embedded wallet integration via keystore-backed managers
• Audit logging for keystore operations

Depends on: @cfxdevkit/cdk only.

Install

npm install @cfxdevkit/services

Sub-paths

| Sub-path | Exports | |----------|---------| | . | 30 symbols | | ./auth | 10 symbols | | ./keystore | 12 symbols | | ./keystore-audit | 2 symbols | | ./keystore-memory | 3 symbols | | ./keystore-file | 6 symbols | | ./keystore-ledger | 11 symbols | | ./crypto | 18 symbols | | ./embedded-wallet | 5 symbols |

.

export declare const __packageName: "@cfxdevkit/services";
export declare const noopAuditLogger: AuditLogger;

export { MemoryNonceStoreOptions } from "./auth";
export { NonceEntry } from "./auth";
export { createMemoryNonceStore } from "./auth";
export { MemoryNonceStore } from "./auth";
export { SessionToken } from "./auth";
export { SessionTokenOptions } from "./auth";
export { VerifySessionTokenOptions } from "./auth";
export { readBearerToken } from "./auth";
export { signSessionToken } from "./auth";
export { verifySessionToken } from "./auth";

export { SecretRef, Capability, StoredSecret, KeystoreCapabilities, KeystoreListOptions, KeystoreCallOptions, KeystorePutInput, KeystoreProvider } from "./keystore";
export { AuditEntry, AuditLogger, Timestamp } from "./keystore-audit";

export { MemoryNonceStoreOptions, NonceEntry, createMemoryNonceStore, MemoryNonceStore } from "./keystore-memory";

export { KeystoreFileProvider, KeystoreFileProviderOptions } from "./keystore-file";

export { KeystoreLedgerProvider, LedgerKeyPath, LedgerKeyPathOptions } from "./keystore-ledger";

export { encryptData, decryptData, generateKey, deriveKeyFromPassword } from "./crypto";

export { EmbeddedWallet, EmbeddedWalletManagerOptions, EmbeddedWalletManager, KeystoreEmbeddedWalletManager, createEmbeddedWalletManager } from "./embedded-wallet";

export { createAppendOnlyAuditLogger, AppendOnlyAuditLoggerOptions } from "./keystore-audit";

./auth

Session token and bearer token utilities for stateless authentication.

export { MemoryNonceStoreOptions, NonceEntry, createMemoryNonceStore, MemoryNonceStore } from "./auth";
export { SessionToken, SessionTokenOptions, VerifySessionTokenOptions } from "./auth";
export { readBearerToken, signSessionToken, verifySessionToken } from "./auth";

./keystore

Core keystore interfaces and types.

export interface SecretRef {
  id: string;
  path: string[];
}

export interface Capability {
  name: string;
  args?: Record<string, unknown>;
}

export interface StoredSecret {
  id: string;
  path: string[];
  encryptedValue: Uint8Array;
  nonce: Uint8Array;
  capabilities: Capability[];
  createdAt: Timestamp;
  updatedAt: Timestamp;
}

export interface KeystoreCapabilities {
  list: boolean;
  get: boolean;
  put: boolean;
  delete: boolean;
}

export interface KeystoreListOptions {
  prefix?: string[];
}

export interface KeystoreCallOptions {
  capability: Capability;
}

export interface KeystorePutInput {
  id: string;
  path: string[];
  value: Uint8Array;
  capabilities: Capability[];
}

export interface KeystoreProvider {
  list(options?: KeystoreListOptions): Promise<StoredSecret[]>;
  get(id: string): Promise<StoredSecret | null>;
  put(input: KeystorePutInput): Promise<void>;
  delete(id: string): Promise<void>;
}

./keystore-audit

Audit logging for keystore operations.

export interface AuditEntry {
  timestamp: Timestamp;
  operation: string;
  keystoreId?: string;
  secretId?: string;
  caller?: string;
  success: boolean;
  error?: string;
}

export interface AuditLogger {
  log(entry: AuditEntry): void;
}

export function createAppendOnlyAuditLogger(opts: AppendOnlyAuditLoggerOptions): AuditLogger;

export interface AppendOnlyAuditLoggerOptions {
  onLog?: (entry: AuditEntry) => void;
}

./keystore-memory

In-memory keystore provider.

export { MemoryNonceStoreOptions, NonceEntry, createMemoryNonceStore, MemoryNonceStore } from "./keystore-memory";

./keystore-file

File-backed encrypted keystore provider.

export interface KeystoreFileProviderOptions {
  path: string;
  password: string | (() => string | Promise<string>);
}

export class KeystoreFileProvider implements KeystoreProvider {
  constructor(opts: KeystoreFileProviderOptions);
  list(options?: KeystoreListOptions): Promise<StoredSecret[]>;
  get(id: string): Promise<StoredSecret | null>;
  put(input: KeystorePutInput): Promise<void>;
  delete(id: string): Promise<void>;
}

./keystore-ledger

Ledger hardware wallet-backed keystore provider.

export interface LedgerKeyPath {
  purpose: number;
  coinType: number;
  account: number;
  change: number;
  index: number;
}

export interface LedgerKeyPathOptions {
  path: LedgerKeyPath;
}

export class KeystoreLedgerProvider implements KeystoreProvider {
  constructor(opts: LedgerKeyPathOptions);
  list(options?: KeystoreListOptions): Promise<StoredSecret[]>;
  get(id: string): Promise<StoredSecret | null>;
  put(input: KeystorePutInput): Promise<void>;
  delete(id: string): Promise<void>;
}

./crypto

AES-256-GCM encryption helpers.

export function encryptData(plaintext: Uint8Array, key: Uint8Array, nonce?: Uint8Array): { ciphertext: Uint8Array; nonce: Uint8Array };
export function decryptData(ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array): Uint8Array;
export function generateKey(): Uint8Array;
export function deriveKeyFromPassword(password: string, salt: Uint8Array): Uint8Array;

./embedded-wallet

Embedded wallet integration using keystore-backed secret storage.

export interface EmbeddedWallet {
  id: string;
  address: string;
  createdAt: Timestamp;
}

export interface EmbeddedWalletManagerOptions {
  keystore: KeystoreProvider;
}

export interface EmbeddedWalletManager {
  createWallet(): Promise<EmbeddedWallet>;
  listWallets(): Promise<EmbeddedWallet[]>;
  getWallet(id: string): Promise<EmbeddedWallet | null>;
  deleteWallet(id: string): Promise<void>;
}

export class KeystoreEmbeddedWalletManager implements EmbeddedWalletManager {
  constructor(options: EmbeddedWalletManagerOptions);
  createWallet(): Promise<EmbeddedWallet>;
  listWallets(): Promise<EmbeddedWallet[]>;
  getWallet(id: string): Promise<EmbeddedWallet | null>;
  deleteWallet(id: string): Promise<void>;
}

export function createEmbeddedWalletManager(options: EmbeddedWalletManagerOptions): KeystoreEmbeddedWalletManager;

Usage

import { KeystoreFileProvider, encryptData, generateKey } from '@cfxdevkit/services';

// Derive encryption key from password
const salt = new Uint8Array(16);
const key = deriveKeyFromPassword('my-password', salt);

// Encrypt data
const plaintext = new TextEncoder().encode('secret data');
const { ciphertext, nonce } = encryptData(plaintext, key);

// Initialize file-backed keystore
const keystore = new KeystoreFileProvider({
  path: './keystore.json',
  password: () => 'my-password'
});

// Store encrypted secret
await keystore.put({
  id: 'my-secret',
  path: ['wallets', 'main'],
  value: ciphertext,
  capabilities: [{ name: 'sign' }]
});

API Reference

See API.md for the full public surface.

Tier

Tier 0 — framework — Must not runtime-import from any higher tier.