How to configure Ed25519 key management for ABS Core -- filesystem, environment variables, AWS KMS, HashiCorp Vault, and hardware security modules.

KeyProvider API

Every ABS Core agent proves its identity with an Ed25519 cryptographic keypair. The KeyProvider API abstracts where and how those keys are stored.

Architecture

              KeyProvider Interface
              |                   |
    +---------+--------+  +------+-------+
    | FileSystemProvider|  | EnvProvider   |
    | (default)         |  | (CI/CD)      |
    +------------------+  +--------------+
              |                   |
    +---------+--------+  +------+-------+
    | VaultProvider    |  | KMSProvider   |
    | (HashiCorp)      |  | (AWS/GCP)    |
    +------------------+  +--------------+
              |
    +---------+--------+
    | HSMProvider       |
    | (PKCS#11)         |
    +------------------+

Auto-Detection

By default, ABS Core auto-detects the best available provider:

import { resolveKeyProvider } from '@abscore/identity';

const provider = await resolveKeyProvider();
// 1. Checks ABS_PRIVATE_KEY env var -> EnvProvider
// 2. Checks ~/.abs/keys/ directory  -> FileSystemProvider
// 3. Generates new keypair          -> FileSystemProvider (auto-create)

The resolution order ensures zero-configuration startup while allowing explicit overrides for production.

FileSystem Provider (Default)

Keys are stored as DER-encoded files on the local filesystem.

# Default location
~/.abs/keys/
  private.key    # Ed25519 private key (DER)
  public.key     # Ed25519 public key (DER)

Configuration:

import { FileSystemKeyProvider } from '@abscore/identity';

const provider = new FileSystemKeyProvider({
  directory: '/secure/path/to/keys',
});

const { publicKey, privateKey, fingerprint } = await provider.loadOrGenerate();

Security note: The private key file should have 0600 permissions. The provider logs a warning if permissions are too open.

Environment Provider (CI/CD)

For containerized environments where filesystem persistence is unavailable.

# Set in your container environment
export ABS_PRIVATE_KEY="base64-encoded-ed25519-private-key"
export ABS_PUBLIC_KEY="base64-encoded-ed25519-public-key"

import { EnvKeyProvider } from '@abscore/identity';

const provider = new EnvKeyProvider();
const { publicKey, privateKey, fingerprint } = await provider.load();

Vault Provider (Enterprise -- Planned)

Integration with HashiCorp Vault for centralized secret management.

import { VaultKeyProvider } from '@abscore/identity';

const provider = new VaultKeyProvider({
  address: 'https://vault.internal:8200',
  token: process.env.VAULT_TOKEN,
  secretPath: 'secret/data/abs-core/agent-keys',
});

Status: Interface defined. Implementation planned for v4.2.0.

KMS Provider (Enterprise -- Planned)

Integration with AWS KMS or GCP Cloud KMS for hardware-backed key operations.

import { KMSKeyProvider } from '@abscore/identity';

const provider = new KMSKeyProvider({
  region: 'us-east-1',
  keyId: 'arn:aws:kms:us-east-1:123456789:key/abc-def',
});

With KMS, the private key never leaves the HSM. Signing operations are delegated to the KMS service.

Status: Interface defined. Implementation planned for v4.2.0.

Key Fingerprint

Every key pair has a SHA-256 fingerprint used for identification without exposing the key material:

const { fingerprint } = await provider.loadOrGenerate();
console.log(fingerprint);
// "4f39798e0f30a1c0..."

The fingerprint appears in:

Gateway startup logs
SovereignAuditRecord agent_oid_pubkey field
Compliance reports

Key Rotation

To rotate keys:

Generate a new keypair
Register the new public key with the OID registry
Revoke the old public key
Update the KeyProvider configuration

The hash chain records both the old and new key fingerprints, creating an auditable rotation trail.

WASM Behavioral Kernel -- How the engine uses keys for signing
Sovereign Checklist -- Checkpoint: "Keys generated locally?"
Air-Gapped Operations -- Key management without internet

KeyProvider API

On this page