agent-keyring

Long-lived agent credential authority with a supervised lifecycle socket and a separate framed keyring service socket.

Purpose

This repository is for keyring structure, metadata, templates, tooling, and operational documentation. It is not for committing raw secrets, private keys, tokens, or live credential material.

Intended layout

• docs/ for procedures and operating notes
• templates/ for non-secret example files
• scripts/ for safe helper tooling
• pkg/keyringclient for the public Go client used by applications that need the agent-keyring service boundary
• public/ for public material only
• local/ for ignored machine-local state

Public Go client

Applications must not import agent-keyring/internal/.... Use pkg/keyringclient for direct Go wiring.

pkg/keyringclient speaks the framed JSON-RPC service contract over the configured Unix socket and hides secure-file staging for credential enrollment. It keeps secret material out of argv, env, stdin, logs, and application databases.

Minimal shape:

client, err := keyringclient.NewFromEnv("financial-site")
resp, err := client.EnrollCredential(ctx, keyringclient.EnrollCredentialRequest{
    CredentialType:   "api_key",
    CredentialUsage:  "api_auth",
    ProviderService:  "schwab",
    AccountPrincipal: "financial-site/schwab/client_secret",
    AudienceHash:     "sha256:...",
    RedactionPolicy:  "redacted_label_only",
}, []byte(secret))

Client runtime environment (development compatibility path):

• AGENT_KEYRING_SOCKET=/path/to/agent-keyring.sock, or $XDG_RUNTIME_DIR/agent-keyring.sock
• AGENT_KEYRING_OPERATOR_TOKEN=..., preferred
• AGENT_KEYRING_ADMIN_TOKEN=..., fallback

NewFromEnv keeps the legacy environment-token client path for compatibility. Production callers should construct keyringclient.Client with auth material obtained from a supervisor-controlled secure source; live auth tokens in ambient environment variables are forbidden by the V1 deployment contract.

Executable configuration

The executable requires the normal rpc-plugin-system lifecycle variables plus:

• AGENT_KEYRING_SOCKET: framed keyring service socket; must differ from the substrate lifecycle socket.
• AGENT_KEYRING_DATA_DIR: private state root for metadata/metadata.sqlite and age-encrypted payloads/.
• AGENT_KEYRING_AGE_RECIPIENT: public age X25519 recipient.
• AGENT_KEYRING_UNLOCK_FILE: owner-only, non-symlink age X25519 identity file that must match the configured public recipient.
• AGENT_KEYRING_ADMIN_TOKEN_FILE with AGENT_KEYRING_ADMIN_CALLER_ID, and/or
• AGENT_KEYRING_OPERATOR_TOKEN_FILE with AGENT_KEYRING_OPERATOR_CALLER_ID.

Startup fails closed if storage, unlock, auth binding, recipient, socket, or restore verification is invalid. Auth token contents are read descriptor-bound from owner-only files; they are not accepted from executable environment values. The substrate socket remains lifecycle-only. Credential operations use the separate framed service socket.

Safety rules

• Never commit live secrets
• Never commit private keys
• Never commit .env files with real values
• Keep real credential material outside git and outside this repo's tracked history