@aura-labs.ai/sdk-common

Shared utilities for AURA SDKs — storage adapters for Ed25519 key persistence.

Storage Adapters

All adapters implement the same async interface:

interface StorageAdapter {
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
  remove(key: string): Promise<void>;
}

MemoryStorage

In-memory Map. Keys lost on process exit. Use for testing and short-lived processes.

import { MemoryStorage } from '@aura-labs.ai/sdk-common';
const storage = new MemoryStorage();

FileStorage

Persists to a JSON file on disk. Default path: ~/.aura/keys.json (configurable via AURA_KEY_PATH env var). File permissions: 0600 (owner read/write only). Directory permissions: 0700.

import { FileStorage } from '@aura-labs.ai/sdk-common';
const storage = new FileStorage();           // ~/.aura/keys.json
const storage = new FileStorage('/custom/path/keys.json');

KeychainStorage

macOS Keychain via the security CLI. Keys are encrypted at rest by the OS — hardware-backed on Apple Silicon via the Secure Enclave. Zero native Node.js dependencies.

macOS only — constructor throws on other platforms.

import { KeychainStorage } from '@aura-labs.ai/sdk-common';
const storage = new KeychainStorage();                                    // service: com.aura-labs.agent
const storage = new KeychainStorage({ serviceName: 'com.myapp.agent' }); // custom service

createStorage() Factory

Auto-detects the best adapter for the current platform:

• macOS → KeychainStorage (hardware-backed encryption)
• Linux / Windows → FileStorage (0600 permissions)

import { createStorage } from '@aura-labs.ai/sdk-common';

const storage = createStorage();                    // Auto-detect
const storage = createStorage({ type: 'memory' });  // Force MemoryStorage
const storage = createStorage({ type: 'file' });    // Force FileStorage
const storage = createStorage({ type: 'keychain' }); // Force KeychainStorage (macOS only)

Usage with Scout SDK

import { createScout, createStorage } from '@aura-labs.ai/scout';

const scout = createScout({
  storage: createStorage(),  // Keychain on macOS, File elsewhere
});
await scout.ready();

Usage with Beacon SDK

import { createBeacon, createStorage, KeyManager } from '@aura-labs.ai/beacon';

const keyManager = new KeyManager({ storage: createStorage() });
const beacon = createBeacon({ ... });
beacon.setKeyManager(keyManager, agentId);

Security

• KeychainStorage: Keys encrypted at rest by macOS. Login keychain unlocks with system login — no passphrase prompt for generic passwords created by the same user.
• FileStorage: Keys stored as plaintext JSON with 0600 permissions (owner-only). Same model as SSH keys.
• MemoryStorage: Keys exist only in process memory. Lost on exit.
• No shell injection: KeychainStorage uses execFile (array args), never exec (shell string).

License

Business Source License 1.1 — See LICENSE for details.