Vault Adapters

All vault adapters implement the VaultAdapter interface and are available from the main @roadsidelab/keyspot-sdk package.

import { InMemoryVaultAdapter, AWSSecretsAdapter } from '@roadsidelab/keyspot-sdk';

VaultAdapter Interface

interface VaultAdapter {
  write(secret: string, options?: VaultWriteOptions): Promise<string>;
  read(id: string, agentId?: string): Promise<string | null>;
  list(): Promise<string[]>;
  delete(id: string): Promise<boolean>;
  generateRef(id: string, secret: string, ttl?: number): string;
  verifyRef(ref: string): boolean;
}
 
interface VaultWriteOptions {
  visibleTo?: string[];         // ACL: agent IDs or wallet addresses
  ttl?: number;                  // Time-to-live in milliseconds
  tags?: Record<string, string>;
  rotationHook?: (id: string, secret: string) => Promise<string>;
}

BaseVaultAdapter

Shared HMAC signing infrastructure. generateRef() creates time-bound tokens in the format vault:v1:{id}:{hmac}:{expiry}. verifyRef() checks the HMAC signature and TTL in one call.

InMemoryVaultAdapter (default)

const vault = new InMemoryVaultAdapter();

Stores secrets in memory with TTL expiry and ACL enforcement. All data is lost on process exit — use for development and sandboxed environments.

AWSSecretsAdapter

const vault = new AWSSecretsAdapter({
  region: 'us-east-1',
});

Requires @aws-sdk/client-secrets-manager and valid AWS credentials. Secrets are stored with a keyspot/secret/ prefix.

Custom Adapter

Extend BaseVaultAdapter — generateRef() and verifyRef() are inherited.

import { BaseVaultAdapter, VaultWriteOptions } from '@roadsidelab/keyspot-sdk';
 
export class MyVaultAdapter extends BaseVaultAdapter {
  async write(secret: string, options?: VaultWriteOptions): Promise<string> {
    const id = `my_${Date.now()}`;
    await myBackend.set(id, secret, options);
    return id;
  }
  // implement read(), list(), delete()
}