Git Signing

Alien Agent ID SSH-signs every git commit with the agent’s Ed25519 key and appends provenance trailers that trace back to the agent and its human owner. A v3 bundle attached as a git note makes verification fully self-contained — anyone with the repo and notes can verify the chain without access to the agent’s machine.

Setup

Git signing is a separate step from bootstrap. After bootstrapping the core identity, run:

node plugins/agent-id-git/bin/cli.mjs setup

setup writes the agent keypair into SSH-format files under the state directory (ssh/agent-id, ssh/agent-id.pub, ssh/allowed_signers) and prints the SSH public key to paste into your git host. It does not modify your git config — the signing config (gpg.format=ssh, user.signingkey, …) is supplied inline per-commit by commit.

Making Signed Commits

Option A: commit (Recommended)

node plugins/agent-id-git/bin/cli.mjs commit --message "feat: implement auth flow"

This creates a commit that is:

1. SSH-signed with the agent’s Ed25519 key (applied inline via -c gpg.format=ssh -c user.signingkey=...)
2. Tagged with trailers linking to the agent’s identity and human owner
3. Logged in the audit trail with a hash-chained signed record
4. Attested with a v3 bundle attached as a git note (refs/notes/agent-id) for external verification

Before signing, commit requires a DPoP-bound owner session: an owner session whose id_token carries a cnf.jkt (RFC 7800 §3.1) equal to the agent key’s thumbprint. If the session predates the v3.0.0 DPoP cutover and cannot anchor a verifiable bundle, commit refuses to sign and tells you to run agent-id-core auth + agent-id-core bind to start a fresh DPoP-bound session.

Useful flags: --push, --remote <name> (defaults to origin), --allow-empty.

Push Commits and Provenance Notes

node plugins/agent-id-git/bin/cli.mjs commit --message "feat: implement auth flow" --push

The --push flag pushes both the commit and the refs/notes/agent-id provenance notes to the remote, handling note ref merging automatically (it fetches and merges any existing notes on the remote before pushing).

Option B: Normal git commit

Because commit supplies the SSH signing config inline, a plain git commit is not signed by the agent and will not include Alien Agent ID trailers or a v3 bundle note. Use commit whenever you want attributable, verifiable provenance.

Commit Trailers

Every commit made with commit includes these trailers:

The commit author is whatever your local git config (or GIT_AUTHOR_*) provides — the tool does not set or override it. The agent is added as Co-Authored-By.

Example commit message:

feat: implement auth flow

Agent-ID-JKT: wEf6o2ux8sBAUG4oQYhP284gfpZwUJMTxXDPH5XxthY
Agent-ID-Owner: 00000003010000000000539c741e0df8
Co-Authored-By: Alien Agent <alienagentid@eti.co>

GitHub Verified Badge

To get the “Verified” badge on GitHub commits:

1. After setup, copy the SSH public key from the command output
2. Go to GitHub → Settings → SSH and GPG keys → New SSH key
3. Set Key type to Signing Key
4. Paste the public key and save

Verifying Provenance

node plugins/agent-id-git/bin/cli.mjs verify --commit HEAD

Verification traces the full chain. Steps 1–3 are the universal v3-bundle checks (verifyBundle() in agent-id-core); step 4 is the git-specific layer:

1. id_token signature — the bundle’s id_token is RS256-verified against Alien SSO’s JWKS (issuer resolved via discovery; pass --sso-url <URL> to override)
2. cnf.jkt anchor — the id_token’s RFC 7800 §3.1 confirmation claim binds the SSO-attested owner (sub) to a specific Ed25519 key thumbprint
3. agent_jwk thumbprint — the bundle’s agent_jwk thumbprint (RFC 7638) must equal both cnf.jkt and the Agent-ID-JKT trailer (and the Agent-ID-Owner trailer must equal the id_token sub)
4. SSH commit signature — git’s native SSH signature must verify against agent_jwk

The same universal verifier can run against any future v3 bundle (signed tool calls, exported proofs, …) without a git dependency.

v3 Bundles in Git Notes

commit attaches a v3 bundle as a git note on refs/notes/agent-id. The bundle is:

{
  "version": 3,
  "id_token": "<SSO-signed id_token, base64url-encoded>",
  "agent_jwk": { "kty": "OKP", "crv": "Ed25519", "x": "..." }
}

• version — protocol version, always 3
• id_token — the SSO-signed OIDC id_token (RS256), base64url-encoded so it survives JSON transports
• agent_jwk — the agent’s Ed25519 public key as an OKP JWK

This makes verification self-contained — anyone who clones the repo and fetches the notes can verify the full chain without access to the agent’s machine. Auditors only need the agent-id-core and agent-id-git plugins installed; no bound identity of their own is required.

# Fetch provenance notes from the remote
git fetch origin refs/notes/agent-id:refs/notes/agent-id
 
# Verify any commit
node plugins/agent-id-git/bin/cli.mjs verify --commit abc123

If no git note is found, verification fails — the v3 bundle note is required, and there is no fallback to the agent’s local state.

Pre-v3 commits (bearing the legacy Agent-ID-Fingerprint / Agent-ID-Binding trailers) are intentionally not supported. Their id_tokens predate the RFC 7800 cnf.jkt binding and cannot anchor the chain — there is no --allow-legacy mode.

Signing Other Operations

Sign any significant action into the audit trail:

node plugins/agent-id-core/bin/cli.mjs sign --type TOOL_CALL --action "bash.exec" --payload '{"command":"deploy"}'
node plugins/agent-id-core/bin/cli.mjs sign --type API_CALL --action "github.create-pr" --payload '{"repo":"foo/bar"}'

All signed operations are appended to the hash-chained audit log at ~/.agent-id/audit/operations.jsonl.

Next Steps

• External Services Auth — Authenticate to services with DPoP
• CLI Reference — Full commit and verify command reference