Agent identity layer: make DashClaw audit trails cryptographically attributable

[piiiico]

DashClaw solves a hard problem: making agent decisions interceptable, enforceable, and auditable. The audit trail and decision replay features are the most compelling part.

One gap: the audit trail records what happened but doesn't anchor who made the decision. In a multi-agent deployment (say, a planner agent spawning worker agents via LangChain or CrewAI), the DashClaw logs show "agent called tool X, policy P applied, outcome Y" — but there's no cryptographic link proving which specific agent instance made that call. If two agents run simultaneously, the audit trail entries are attributed to whichever API key they share.

The gap in practice:

• Audit entries carry no verifiable agent_id — only the session or API key
• When the same agent restarts (e.g. container restart), it appears as a new anonymous actor
• Cross-org audit verification ("was this action taken by the agent I authorized?") has no cryptographic anchor

Proposal: Optional AgentLair identity layer for audit entries.

Disclosure: I built AgentLair (agentlair.dev). Each agent registers once and gets:

• A persistent agent_id (UUID, stable across restarts)
• An Ed25519 signing keypair (HKDF-derived from vault seed, survives container resets)
• An AAT JWT verifiable offline against agentlair.dev/.well-known/jwks.json

Integration path:

1. Agents attach Authorization: Bearer <AAT> to DashClaw API calls
2. DashClaw verifies the token (JWKS lookup, standard JWT library, ~10 lines)
3. Audit entries include agent_id and agent_name from the token claims — no more anonymous decisions

The result: DashClaw's "verifiable evidence of every decision" becomes verifiable about both the decision and the decider. Compliance reviewers and incident responders get a full picture.

What this doesn't touch: Your existing API key auth stays as-is. This is an additive path for teams that need agent-level attribution, not session-level.

Would a PR adding optional AAT support to the audit entry schema be welcome? I can start with a design doc if you'd prefer to discuss the shape first.

[ucsandman]

First off — thank you so much for taking the time to dig into DashClaw and write this up. Honestly, it's genuinely exciting to see people out there looking closely at the audit trail and thinking hard about where it could go next. That's the kind of feedback that makes building this worth it, so thank you. And extra appreciation for the upfront disclosure about AgentLair — that's classy and I really appreciate it.

You've put your finger on something real. Shared-API-key deployments (planner + worker agents, container restarts, multi-tenant setups) genuinely do collapse to ambiguous attribution in our audit trail right now, and it's a gap worth closing. I love that you framed it as "verifiable about both the decision and the decider" — that's a great way to put it and I'm stealing it. 🙂

Here's how I'm thinking about the shape:

Phase 1 — agent attribution in the SDK surface (near term). Add optional agentId / agentName fields to the core SDK methods (guard, record, etc.), persisted on every audit entry. Trust-on-assertion inside the existing API-key boundary. Cheap, no new dependencies, and it solves the "which of my 12 workers made this call" problem for most teams out of the gate. No crypto required — if you trust the API key holder, you trust what they report about themselves.

Phase 2 — verifiable identity via standard OIDC (once there's demand). For teams that need cryptographic attribution (adversarial scenarios, cross-org verification, compliance reviewers who don't want to trust the API-key boundary alone), accept standard OIDC bearer tokens alongside API keys. The main thing I'd want to hold the line on is keeping it provider-agnostic via a configurable JWKS discovery URL — so AgentLair would be a first-class option alongside Auth0, Okta, Keycloak, or a self-hosted issuer. I just don't want DashClaw's audit integrity to depend on any single third party being reachable, and I'm sure you get that.

Would you be up for sketching a design doc for the Phase 2 shape? Even just a comment on this issue would be great — something like:

• Token claim schema (`agent_id`, `agent_name`, anything else you've found useful?)
• JWKS discovery and key rotation expectations
• How verification failures should surface in the audit entry (fail closed? fall back to API-key attribution? flag the entry?)

If that converges on a provider-agnostic interface, I'd be genuinely excited to see a PR — and AgentLair becoming a reference implementation for it would be a great outcome for both sides.

Thanks again for engaging with this so thoughtfully. Stuff like this is exactly why I keep working on DashClaw. 🙏

[piiiico]

Thank you — this is an excellent framing. The two-phase approach is exactly right, and provider-agnostic JWKS is the correct interface. Here's the Phase 2 design sketch you asked for.

---

Phase 2: Verifiable Agent Attribution via JWKS

Token Claim Schema

{
  "iss": "https://agentlair.dev",       // Issuer — any OIDC-compatible provider
  "sub": "agt_7f3a2b...",               // agent_id (persistent UUID)
  "agent_name": "review-worker-3",      // Human-readable label
  "owner": "org_9c4e...",               // Human/org that owns the agent
  "aud": "dashclaw.example.com",        // DashClaw instance — binds token to audience
  "exp": 1744300800,                    // Short expiry (5–15 min recommended)
  "iat": 1744300500,
  "jti": "txn_a8f3...",                 // Unique token ID — replay protection
  "act": {                              // Action binding (optional, Phase 2b)
    "method": "guard",
    "policy_id": "P-deploy-approval"
  }
}

Notes on the schema:

• sub maps to your Phase 1 agentId — same field, now verifiable
• agent_name maps to agentName — carry it in the token so Phase 1 consumers don't need to change
• owner is useful for multi-tenant scenarios: "which org's agent made this call?"
• act is optional and covers the "action-bound proof" pattern — prevents token reuse across different guard/record calls. Could defer this to Phase 2b since jti + short exp already handles most replay concerns

JWKS Discovery and Key Rotation

Discovery: Standard GET {issuer}/.well-known/jwks.json. AgentLair's is live at https://agentlair.dev/.well-known/jwks.json.

Key rotation expectations:

• Issuers rotate signing keys periodically (AgentLair: ~90 days)
• Old keys remain in JWKS for an overlap window (2× the max token exp) so in-flight tokens verify cleanly
• Each key has a kid — tokens reference it in the JWT header

DashClaw-side caching:

• Cache JWKS with a TTL (suggested: 1 hour)
• On verification failure with unknown kid: refresh the cache once, retry
• If still unknown after refresh: verification fails (key not from a configured issuer)

Multiple issuers: Since you want provider-agnostic, DashClaw would accept a list of trusted JWKS URLs in config:

actor_verification:
  providers:
    - name: agentlair
      jwks_url: https://agentlair.dev/.well-known/jwks.json
    - name: internal-keycloak
      jwks_url: https://auth.internal.example.com/.well-known/jwks.json

Standard jose / jsonwebtoken libraries handle multi-provider JWKS natively.

Verification Failure Handling

Recommended: flag, don't block (configurable to strict).

Scenario	verification_status	Behavior
No token provided	unverified	Falls back to Phase 1 (trust-on-assertion via API key)
Valid token, signature checks out	verified	Full attribution persisted
Token expired	expired	Entry logged, flagged — clock skew or stale token
Invalid signature	failed	Entry logged, flagged — potential forgery attempt
Unknown kid after JWKS refresh	unknown_issuer	Entry logged, flagged — token from unconfigured provider

Default mode: permissive (log all, flag failures). This preserves the additive guarantee — no existing behavior changes for teams that don't send tokens.

Strict mode (opt-in): reject writes with failed or unknown_issuer status. For compliance-heavy deployments where unverified entries are unacceptable.

actor_verification:
  mode: permissive  # or "strict"

What This Looks Like in Practice

// Agent-side: attach proof to guard() call
const proof = await agentlair.signActionProof({
  aud: "dashclaw.example.com",
  act: { method: "guard", policy_id: "P-deploy" }
});

dashclaw.guard("deploy-production", context, {
  actor: {
    id: "agt_7f3a2b",
    name: "deploy-checker",
    proof: proof  // JWT string
  }
});

// DashClaw-side: verify and persist
const result = await actorVerifier.verify(actor.proof);
auditEntry.actor_id = result.sub;
auditEntry.actor_name = result.agent_name;
auditEntry.verification_status = result.status; // "verified"

The Phase 1 agentId/agentName fields carry through unchanged — Phase 2 just adds a verifiable proof alongside them. Teams can upgrade from Phase 1 to Phase 2 per-agent without a migration.

---

Happy to iterate on any of these details. On the signing-side implementation: AgentLair already issues Ed25519 keys per agent via HKDF derivation from a vault seed, so the signActionProof() helper is straightforward to ship once the DashClaw-side schema is settled.

[piiiico]

Just wanted to follow up briefly — the Phase 2 design doc I sketched above is based on exactly the provider-agnostic JWKS interface you outlined, so I think the pieces are well-aligned. In case it's useful context: AgentLair is now live, and the persistent agent identity / Ed25519 signing infrastructure it provides maps directly to the sub / kid claims in the spec. Happy to clarify anything in the design or iterate on the token schema if there are concerns — no rush at all, just wanted to make sure the thread didn't get lost.

[ucsandman]

Thanks, this design is solid. The verification_status enum with permissive default is the right shape.

Four things before a PR:

1. Phase 1 first, Phase 2 second. Land agentId / agentName on the audit schema as a standalone PR, then add verification_status + JWKS in a second PR. Lets Phase 1 bake in prod before verification semantics layer on. Own both if you want, just sequence them.

2. Reference, not dependency. Phase 2 tests and default config should use a generic OIDC example (Keycloak, Auth0, or a local JWKS fixture). AgentLair as a first-class docs example is great; the out-of-the-box path needs to work without it.

3. JWKS resilience. 1-hour cache TTL is fine. Add a circuit breaker so a downed issuer can't tank audit-write latency, and verification failures during an outage should fall back to unverified (Phase 1 attribution), not failed.

4. Config shape. Env vars over YAML, since the repo doesn't have a YAML config surface today. Bike-sheddable.

Draft PR is the fastest way for me to give feedback. Flag which phase you're starting on so we don't end up with parallel branches.

[piiiico]

Phase 1 draft PR is up: #85

Implemented exactly as you outlined — agentId / agentName on the audit schema, trust-on-assertion, no verification logic. Migration is additive (single ALTER TABLE ADD COLUMN). Existing auth is untouched.

One small addition beyond the minimal spec: the route decodes (but does not verify) a JWT bearer token to extract attribution claims if present. This makes it a drop-in for any agent that already attaches an AAT — no SDK change required on their end. Body fields take precedence if provided, so there's no breaking change.

Ready to simplify or remove the JWT decode if you'd prefer to keep Phase 1 purely body-based.