auth

When to use

Reach for this whenever an agent (or a child MCP it mounts) must present a credential to a remote service and you don't want that secret sprayed into the daemon's global env or hardcoded in a config file. The hallmark: "how do I give this agent access to <service> without leaking the key to every other agent?"

• A tool/agent calls a Bearer API (agentpush, Stripe, an internal API).
• A hosted/remote MCP server needs an Authorization header.
• You want ONE place to store a key, scoped per service, resolved fresh (with refresh) at use-time instead of a long-lived env var.

Do NOT use for the daemon's own tunnel login (that's agentproto auth login, a device-code flow already wired) — though it uses the same substrate underneath.

The model — one source of truth, resolved on demand

auth provider (declares WHERE/HOW)  ──┐
CredentialStore (holds the secret)  ──┤─▶ CredentialBroker.resolveHeaders({ path, audience })
                                       │        → { Authorization: "Bearer …" }  (fresh, per call)

• Provider — a manifest declaring a service's id, apiBase, and auth flow. Config only, never the secret. Registered once (registerAuthProvider).
• CredentialStore — where the secret lives: KeychainStore (macOS CLI), FileStore (AES-256-GCM, headless — key from AGENTPROTO_STORE_KEY), MemoryStore (tests). Swap the backend, same interface.
• Broker — resolveHeaders({ path, audience?, signal? }) turns a provider path into ready-to-use headers: serves a fresh stored bearer, else runs the flow. audience (api / mcp / tunnel) scopes the credential so it can't be reused cross-plane.
• Flows — pick one per service: pat (static token you store/paste), service-auth (auth.md claim ceremony → short oat + durable assertion), device-code (RFC 8628 → durable daemon token + refresh).

Recipe

1. Declare + register the provider

TS literal (builtin/tests):

import { defineAuthProvider, registerAuthProvider } from "@agentproto/auth"

registerAuthProvider(defineAuthProvider({
  id: "agentpush",
  description: "AgentPush API — paste a personal API key.",
  apiBase: "https://api.agentpush.example",
  audience: "mcp",                       // or "api"
  auth: { flow: "pat", tokenStore: { keychain: "agentpush", account: "{server}" } },
}))

Or ship a vendor *.auth.md and parseAuthProviderManifest(...) → registerAuthProvider(...) — a host adds providers without editing this package.