alien-agent-id

Alien Agent ID

Verifiable cryptographic identity for AI agents, linked to human owners via [Alien Network][alien] SSO.

When an AI agent has an Alien Agent ID, every git commit it makes is SSH-signed and carries trailers that trace back to the specific agent and the human who authorized it. The provenance chain is fully verifiable: commit → agent key → owner binding → SSO attestation → verified AlienID holder.

Table of Contents

• How It Works
• Quick Start (Claude Code)
• What a Signed Commit Looks Like
• Verifying Provenance
• Service Authentication
• Credential Vault
• Session Refresh
• Prerequisites
• Agent State
• CLI Commands
• Security

---

How It Works

sequenceDiagram
    participant Agent as AI Agent
    participant SSO as Alien SSO
    participant App as Alien App (Human)

    Agent->>SSO: 1. Start OIDC auth, get QR / deep link
    SSO->>App: 2. Human scans QR with Alien App
    App->>SSO: 3. Human approves, callback to SSO
    SSO->>Agent: 4. Exchange tokens, create cryptographic owner binding
    Note over Agent: Alien Agent ID bound → SSH-signed git commits with provenance trailers

1. Agent starts OIDC auth, gets a QR code / deep link
2. Human scans QR with Alien App
3. Human approves, Alien App calls back to SSO
4. Agent exchanges tokens, creates cryptographic owner binding

The agent now has an Ed25519 keypair with a signed binding proving a verified human authorized it.

---

What's in the Box

Path	Purpose
skills/alien-agent-id/SKILL.md	Instructions for AI agents — point your agent here
skills/alien-agent-id/cli.mjs	CLI tool — all agent operations
skills/alien-agent-id/lib.mjs	Portable library — crypto, OIDC, signing engine, verification (zero npm deps)
skills/alien-agent-id/qrcode.cjs	Vendored QR code generator (terminal output)
skills/alien-agent-id/default-provider.txt	Default SSO provider address
docs/AGENT-SSO.md	System documentation for humans
docs/INTEGRATION.md	Integration guide for service providers
examples/demo-service.mjs	Reference HTTP service with agent token verification
tests/test-refresh.mjs	Test suite for session refresh flow
package.json	Minimal metadata

---

Quick Start

1. Install the skill

npx skills add alien-id/agent-id

Claude Code only

Alternatively, install via the plugin marketplace:

/plugin marketplace add alien-id/agent-id
/plugin install alien-agent-id@alien-agent-id
/reload-plugins

Sometimes the reload does not work properly the first time — restarting Claude usually helps.

2. Set up your Alien Agent ID

When the plugin is loaded, run the skill:

/alien-agent-id

Follow the instructions — the agent will generate a keypair, show a QR code, and wait for you to approve in the Alien App. Once done, your Alien Agent ID is created and bound.

3. Add the signing key to GitHub

The agent will output an SSH public key after setup. Add it to your GitHub account:

Go to GitHub → Settings → SSH and GPG keys → New SSH key → Key type: Signing Key. Commits will then show a "Verified" badge.

4. Use the skill to commit and push

You can pass arguments to the skill for common operations:

/alien-agent-id stage, commit and push all files in the repo, follow previous commits naming convention

Other agents

Any agent with shell access can use skills/alien-agent-id/SKILL.md directly. The agent needs Node.js 18+, git 2.34+, and permission to run node skills/alien-agent-id/cli.mjs ... commands.

---

What a Signed Commit Looks Like

✓ Verified  — This commit was signed with the committer's verified signature.

feat: implement auth flow

Agent-ID-Fingerprint: 945d41991dac118776409673019ed0fba36e13fc9d6b5534145f9e31128a3ec6
Agent-ID-Owner: 00000003010000000000539c741e0df8
Agent-ID-Binding: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Anyone can trace: this code → this agent (fingerprint) → this human (owner session) → verified AlienID holder.

Each git-commit also attaches a proof bundle as a git note (refs/notes/agent-id) containing the agent's public key, owner binding, and base64url-encoded SSO id_token — everything needed for anyone to verify the provenance chain without access to the agent's local state.

---

Verifying Provenance

node skills/alien-agent-id/cli.mjs git-verify --commit HEAD