Skip to Content
GuideIntroduction
View .md

Introduction

Alien Agent ID gives an AI agent a verifiable cryptographic identity linked to a verified human owner through Alien Network  SSO. The agent holds an Ed25519 keypair, and the SSO-signed id_token it receives carries a cnf.jkt confirmation claim (RFC 7800 §3.1) that binds the human owner to that exact key. There is no separate self-signed binding — the SSO-issued id_token is the human ↔ agent binding.

Alien Agent ID ships as a Claude Code plugin marketplace with four focused plugins, each invoked as its own CLI under plugins/agent-id-<name>/bin/cli.mjs:

  • agent-id-core — bootstrap (init / auth / bind / bootstrap), session lifecycle (refresh, status, setup-owner-session), and universal operations (sign, verify, export-proof). Owns the shared library every other plugin imports.
  • agent-id-git — SSH-signed git commits with Agent-ID provenance trailers and a v3 bundle attached as a git note (setup, commit, verify).
  • agent-id-vault — AES-256-GCM credential vault for external-service secrets (store, get, list, remove).
  • agent-id-auth — RFC 9449 DPoP-signed calls to Alien-aware services (header, call, discover, capabilities, support).

agent-id-core is required by the other three. Each plugin has zero npm dependencies — Node.js built-ins only.

What Alien Agent ID Provides

  • Cryptographic identity — an Ed25519 keypair linked to a verified human owner via Alien Network SSO. The human scans a QR code once and approves in the Alien App; the agent receives a DPoP-bound owner session.
  • Service authentication — RFC 9449 DPoP. Each request carries a fresh Ed25519-signed DPoP proof bound to the method and URL, plus the SSO-issued DPoP-bound access_token. No API keys, no shared secrets.
  • Credential vault — encrypted storage (AES-256-GCM) for external-service credentials. The encryption key is derived via HKDF-SHA256 from the agent’s private key, so credentials are readable only where that key lives.
  • Signed git commits — every commit is SSH-signed and tagged with trailers tracing back to the agent and its human owner. A v3 bundle in a git note makes verification self-contained.

Architecture

The agent advertises its key’s RFC 7638 thumbprint as dpop_jkt on the authorize request, so the SSO can mint an id_token whose cnf.jkt equals that thumbprint. After bootstrap, the agent holds:

  • Ed25519 keypair — for signing operations, DPoP proofs, and git commits
  • Owner session — the on-disk record at owner-session.json carrying the SSO-issued id_token, access_token, and refresh_token
  • DPoP-bound session — an owner session whose id_token carries cnf.jkt = jwkThumbprint(agent_jwk); only such a session can anchor a verifiable v3 bundle

To enable signed git commits, run agent-id-git setup separately after bootstrap.

Trust Chain

Anyone can verify an agent’s identity by tracing the provenance chain on a signed commit:

Git commit (SSH signature)
  └► agent_jwk (the agent's public key)
       └► id_token cnf.jkt (RFC 7800 — binds the owner to the agent key)
            └► id_token RS256 signature by Alien SSO
                 └► Alien SSO JWKS (public keys)
                      └► Verified AlienID holder (human)

Each commit carries two provenance trailers — Agent-ID-JKT (the agent’s JWK thumbprint) and Agent-ID-Owner (the SSO sub) — and attaches a v3 bundle { version: 3, id_token, agent_jwk } as a git note (refs/notes/agent-id). Verification is self-contained: anyone who clones the repo and fetches the notes can verify the chain without access to the agent’s local state.

The first three steps — id_token signature, cnf.jkt anchor, and agent_jwk thumbprint match — are the universal verification (verifyBundle in agent-id-core). The SSH commit-signature check is the git-specific layer that agent-id-git adds on top. Pre-v3 commits are intentionally not supported: their id_tokens predate the cnf.jkt binding and cannot anchor the chain.

Agent State Directory

All state is stored in ~/.agent-id/ (configurable via --state-dir or AGENT_ID_STATE_DIR). Every plugin reads and writes through agent-id-core/lib/state.mjs, so the layout is the same regardless of which plugins are installed:

~/.agent-id/
├── keys/main.json             # Ed25519 keypair (mode 0600)
├── ssh/
│   ├── agent-id               # SSH private key (mode 0600)
│   ├── agent-id.pub           # SSH public key
│   └── allowed_signers        # For git signature verification
├── vault/                     # Encrypted credentials (dir 0700, files 0600)
│   ├── github.json
│   ├── aws.json
│   └── ...
├── owner-session.json         # SSO tokens — id_token IS the binding (mode 0600)
├── nonces.json                # Per-agent nonce tracking
├── sequence.json              # Operation sequence counter
└── audit/operations.jsonl     # Hash-chained signed operation log

A transient pending-auth.json also appears between auth and bind (PKCE verifier, OAuth state, OIDC nonce) and is removed once the session is bound.

Security

  • Private keys stored with 0600 permissions; state directories created with 0700.
  • PKCE (S256) prevents authorization-code interception (RFC 7636).
  • The SSO id_token (RS256) commits the agent key thumbprint via cnf.jkt — the human ↔ agent binding lives inside the SSO-signed claim, not a separate self-signed envelope (RFC 7800 §3.1).
  • DPoP proof-of-possession (RFC 9449) — every service request carries a fresh Ed25519-signed proof with a unique jti, bound to the method and URL (htm / htu); a leaked access_token is useless without the matching private key.
  • Hash-chained audit log — any tampering breaks the chain.
  • Vault encryption — AES-256-GCM with an HKDF-SHA256-derived key from the agent’s private key.
  • JWT alg: none rejected — unsigned tokens are refused at parse level.
  • Subject validation — token refresh verifies the subject claim still matches the bound owner.
  • owner-session.json contains tokens — never commit or share it.

Next Steps

Last updated on
Upgrade to v2Quick Start