[AAASM-3569] 🔒 (aa-sdk-client): SDK↔runtime IPC authentication & anti-impersonation

[Chisanan232]

Description

Closes Story AAASM-3569 (under Epic AAASM-3567): authenticates the local SDK↔aa-runtime UDS channel and the gateway credential_token mint, closing the local-impersonation and forged-event vectors.

Three controls, layered:

• UDS peer-credential check (AAASM-3579): the runtime reads SO_PEERCRED/getpeereid via UnixStream::peer_cred in the accept loop and drops any connection whose process UID ≠ the runtime's euid, before any handler is spawned.
• Atomic 0600 socket + agent-scoped path (AAASM-3581): umask(0o077) around bind removes the bind→chmod TOCTOU window; the socket path is scoped to AA_AGENT_ID.
• Per-session Ed25519 handshake (AAASM-3583/3585/3587): a new assembly.ipc.v1 proto (HandshakeChallenge/HandshakeProof) + new wire tags (=5). On accept the runtime sends a fresh 32-byte nonce and requires the SDK's Ed25519 signature over it, verified against the key deterministically derived from AA_AGENT_ID (reusing AgentKeypair). The handshake runs in the per-connection task (never blocks the accept loop), is bounded by a 5s timeout, and the response router / active-conn counter are wired only after a valid proof. The SDK completes the handshake before any heartbeat/event, fail-closed.
• Credential_token possession gate (AAASM-3591): gateway Register now requires an Ed25519 possession_proof over the registering did:key, verified against public_key, before generate_credential_token(). Missing/forged/wrong-length → Unauthenticated. The SDK signs and sends it. Coordinates with AAASM-3416 (broad per-endpoint authn, still To Do) — this is the minimal credential_token possession gate that a future authn interceptor layers on top of, not a replacement.

Type of Change

• ✨ New feature
• 🔧 Configuration / CI change

Breaking Changes

• Yes (describe below)

RegisterRequest gains a required possession_proof field (proto field 14): a gRPC Register call without a valid proof now returns Unauthenticated instead of minting a token. aa-sdk-client::ipc::spawn_ipc_thread / ipc_loop now take an agent_id: String to derive the handshake signing key. The cross-repo FFI shims (python/node/go SDKs) consume aa-sdk-client by pinned SHA and will adopt these on their own cadence.

Related Issues

• Related Jira ticket: AAASM-3569 (subtasks AAASM-3579/3581/3583/3585/3587/3589/3591/3592)
• Coordinates with: AAASM-3416 (gateway per-endpoint authn — credential_token possession gate added here, interceptor deferred to that Story)

Testing

• Unit tests added / updated
• Integration tests added / updated

Local validation (CI verifies authoritatively):

• cargo nextest run -p aa-sdk-client -p aa-runtime -p aa-gateway -p conformance → 1575 passed, 2 skipped.
• New tests: peer-UID allow helper; 0600 + agent-scoped bind; handshake nonce/proof verify (valid/forged/wrong-nonce/wrong-key/bad-length); handshake codec round-trip; impersonation/forged-event rejection (no-handshake event not dispatched, forged-sig rejected, valid handshake dispatches); gateway possession-proof accept/missing/forged/wrong-challenge/wrong-length; SDK AgentKeypair::sign.
• cargo clippy --all-targets --all-features -- -D warnings clean on touched crates; cargo fmt --check clean; cargo build --workspace clean.

Platform note: SO_PEERCRED is Linux-specific; the peer-UID read uses tokio's portable peer_cred() (getpeereid on macOS/BSD), so the path compiles and runs on all Unix targets. Tests were authored and run on macOS; the exact UID-mismatch reject is best validated under Linux CI (a same-host different-UID peer is hard to stage in a unit test) — the helper that decides it is unit-tested directly.

Checklist

• Code follows project style guidelines (cargo fmt, cargo clippy)
• Self-review of the diff completed
• Documentation updated if behaviour changed (doc comments on all new public items)
• All CI checks passing (pending CI)
• Commits are small and follow the Gitmoji convention

🤖 Generated with Claude Code

[Chisanan232]

CI fix: e2e_runtime_gateway_deny broken by the new IPC handshake

The Test job (run 28027853201) failed on aa-integration-tests::e2e_runtime_gateway_deny::runtime_forwards_per_tool_deny_to_gateway at e2e_runtime_gateway_deny.rs:191 — assertion left == right failed: expected a PolicyResponse frame.

Root cause (test-harness gap, not a runtime bug). This PR's AAASM-3585 change makes the runtime require a signed per-session Ed25519 handshake before serving any application frame: on connect the runtime sends a HandshakeChallenge{nonce} (tag 5) and expects a HandshakeProof signed with the agent's deterministic key. The e2e test connected to the runtime UDS and immediately sent a PolicyQuery without handshaking, so the runtime's first frame was the challenge (tag 5), which the test misread as the response tag and asserted 5 == 1. Reproduced locally exactly: left: 5, right: 1.

The runtime is correct — verified the slipped test was the only one in aa-integration-tests that drives the IPC directly (the other tests that touch aa-runtime use the AuditPublisher, the gRPC path, or just probe UDS connectivity, none of which the handshake breaks). It slipped because the implementing pass validated -p aa-sdk-client -p aa-runtime -p aa-gateway -p conformance only, not aa-integration-tests.

Fix. Made the test harness perform the handshake before sending the query, mirroring the real SDK — read the challenge, sign the nonce with the production aa_sdk_client::AgentKeypair (seed = SHA-256(agent_id), the exact key the runtime expects), send the proof. Reuses the real signer rather than duplicating crypto, so no security behaviour is weakened.

• 5cc6a431 🔧 add aa-sdk-client dev-dep
• 95e71937 🐛 perform the IPC Ed25519 handshake in check_tool

Local proof (macOS, stable toolchain):

• target test: FAIL without the fix (left: 5, right: 1), PASS with the fix
• cargo build --workspace green; cargo clippy -p aa-integration-tests --all-targets -- -D warnings clean; cargo fmt --check clean

— Claude Code

[Chisanan232]

Review — AAASM-3569 SDK↔runtime IPC authentication & anti-impersonation

Verdict: READY to merge (pending the required Pioneer approval — no code/CI blocker).

CI

Authoritative ci.yml run is completed / success at PR head 95e71937; the CI Success gate is green. All Rust/security jobs pass: Test, Clippy, Format, Rustdoc, Rust conformance, TimescaleDB, Integration tests (macOS), Analyze (rust/python/go/js-ts), no_std targets, Standalone build, Proto breaking check.

The four red checks are not code failures / not gating:

• Docker + Docker image smoke (aa-runtime sidecar, multi-arch build, node image) — all three images build successfully (every layer DONE); they fail only at the exporting to GitHub Actions Cache step with a transient 503 upstream connect error from GitHub's cache backend. Pure infra flake, unrelated to this PR — these same workflows are green on master.
• CodeQL — 3s default-setup/QUALITY-mode feed artifact; the real Analyze (*) jobs all passed.

No fix pushed (would be wrong to "fix" an infra flake with code).

Scope coverage — all 8 subtasks verified

• 3579 SO_PEERCRED peer-UID reject — ipc/peercred.rs + accept-loop peer_cred() gate (rejects mismatched UID and unreadable creds before any work). ✅
• 3581 atomic 0600 socket scoped to AA_AGENT_ID — umask(0o077) around bind closes the prior bind→chmod TOCTOU window; agent-id path scoping asserted; covered by bind_creates_socket_with_0600_and_agent_scoped_path. ✅
• 3583 per-session handshake frame + nonce — ipc.proto HandshakeChallenge{nonce} / HandshakeProof, fresh random nonce per session (documented replay protection). ✅
• 3585 runtime Ed25519 verify gating, fail-closed — perform_handshake runs inside the spawned task (never stalls accept loop), 5s timeout, response-router + active-conn counter wired only after a valid proof. ✅
• 3587 SDK signed proof on connect — aa-sdk-client::ipc::perform_handshake signs the nonce before any traffic and aborts the loop on failure (fail-closed); AgentKeypair::sign added. ✅
• 3591 / coord. 3416 credential_token possession gate — verify_possession_proof in lifecycle_service::Register; missing/malformed/forged proof → Unauthenticated, no token minted. ✅
• 3589 impersonation/forged-event tests — fail-closed proven: event_without_handshake_is_not_dispatched, forged_handshake_signature_is_rejected (both assert no inbound dispatch), plus valid_handshake_then_event_is_dispatched happy path; e2e in e2e_runtime_gateway_deny.rs. ✅
• 3592 verify — gateway lifecycle tests + conformance round-trip set possession_proof. ✅

Commit history is granular and bisectable (23 commits, one logical unit each).

⚠️ Breaking change (coordination note, not a blocker)

RegisterRequest.possession_proof (field 14) is now required: an unauthenticated Register (empty proof) returns Unauthenticated. The python / node / go FFI shims will fail to register on their next aa-sdk-client SHA-pin bump unless they send the proof. The SDK-side change is included here (aa-sdk-client signs did:key for Register and signs the nonce for the IPC handshake), so the contract is consistent within this repo — but the downstream SDK repos must pick it up in lockstep with the pin bump.

Design note (non-blocking)

The handshake keypair is derived deterministically from SHA-256(agent_id), and agent_id is not secret — so a local process that knows the agent_id can reconstruct the signing key and produce a valid proof. The handshake is therefore defence-in-depth (makes the trust boundary explicit + testable), not an independent secret; the real local-impersonation boundary is the SO_PEERCRED UID check + 0600 socket. The code documents this honestly. Future hardening (a real per-agent secret) can layer on without changing the wire shape.

— Claude Code

[Chisanan232]

Cleared the CodeQL hard-coded-nonce alert

The CodeQL "critical" finding ("This hard-coded value is used as a nonce", ×6) was not in production. Production nonce generation is already correct and was left untouched:

• aa-runtime/src/ipc/handshake.rs::generate_nonce() uses getrandom (CSPRNG).
• aa-runtime/src/ipc/server.rs:318 issues the live challenge via handshake::generate_nonce().

The 6 flagged flows all originated from hard-coded literal nonces in test/codec code added by this PR. Fixed at the 3 literal sources (which CodeQL expands into ~6 sink flows via clone + sign + verify):

File	Was	Now
aa-runtime/src/ipc/codec.rs:439	nonce: vec![3u8; 32] (+ matching assert)	fresh handshake::generate_nonce(), asserted round-trip
aa-sdk-client/src/ipc.rs:257	let nonce = vec![42u8; 32]	getrandom-filled 32-byte nonce
aa-sdk-client/tests/lifecycle_e2e.rs:41	let nonce = vec![9u8; 32]	getrandom-filled 32-byte nonce

Each nonce is still signed and verified against the same (now random) value, so no assertion was weakened. aa-sdk-client gained a getrandom dev-dependency (0.2, already resolved in the lockfile, mirrors the runtime's production source).

Local validation (touched crates): aa-runtime + aa-sdk-client 367/367 pass; the runtime↔gateway handshake e2e (runtime_forwards_per_tool_deny_to_gateway) passes; cargo build, clippy -D warnings, and cargo fmt --check all clean.

CodeQL should report 0 new alerts on re-analysis.

— Claude Code

[Chisanan232]

CodeQL "Hard-coded cryptographic value" (Critical) — real source fixed

The previous attempt randomized the test nonces, but the Critical alert's source is production code: aa-runtime/src/ipc/handshake.rs:36, the let mut nonce = [0u8; NONCE_LEN]; buffer literal inside generate_nonce().

CodeQL's taint model does not recognize getrandom's in-place &mut fill as a sanitizer, so the zero-init literal remained in the data-flow and was reported (×6 sink flows from this one source) as a hard-coded value used as a nonce. The nonce was random at runtime, but the constant literal sat in the taint path.

Fix (commit 1ef5dc50): produce the 32 bytes directly from a value-returning CSPRNG so no constant literal enters the nonce data-flow:

pub fn generate_nonce() -> [u8; NONCE_LEN] {
    rand::random::<[u8; NONCE_LEN]>()
}

rand::random draws from a ChaCha-based, OS-seeded thread CSPRNG and returns the value. Production randomness is unchanged/strengthened — NONCE_LEN is preserved and the source remains a CSPRNG. The now-unused direct getrandom dependency was dropped; rand 0.8 was already a transitive dependency (via async-nats → nkeys), so the dependency graph is unchanged and cargo deny check stays clean (advisories/bans/licenses/sources all ok).

Local validation: cargo nextest run -p aa-runtime → 317 passed (incl. nonce_is_32_bytes_and_varies and all handshake/server tests); cargo build -p aa-runtime ✓; cargo clippy -p aa-runtime --all-targets -- -D warnings clean; cargo fmt --check clean; cargo deny check ok. Pre-commit and pre-push (cargo doc) hooks passed.

I'm not asserting the CodeQL check is green — leaving the CI re-analysis on the new head to confirm.

— Claude Code