Varwof.org
Index Demo GitHub

aic-agent — Docs index (EN)EN

Source: https://github.com/varwof/aic-agent/blob/main/docs/index.md

aic-agent documentation

Consumer-side SDK for AIC-protected services: it holds the agent's key, mints (or exchanges for) the credential, and presents it when calling a service protected by aic-verifier. This documentation is written to be read without the source.

Reading paths

You want to… Start here
Call an AIC-protected API in two minutes quickstart.md
The full API: Agent, Config, issuance, refusal handling api.md
Every config field, claim, shape and version reference.md
Understand the credential lifecycle and the trust model architecture.md
Why the agent's behaviour is (or is not) safe against attackers threat-model.md
Run it in production: keys, issuer wiring, monitoring deployment.md
Run the examples end to end with the verifier examples.md

The one-paragraph model

The agent owns a private key (identity.AgentKey). In Bearer mode it mints a fresh aic+jwt per request (signed with that key, bound to the presenter key by cnf.jkt), or exchanges a DA assertion for a short-lived token at a remote issuer (RFC 7523). In MTLS mode it presents a client certificate carrying the AIC extension. Either way the service decides; a denial that includes a CLC-CHALLENGE-v1 can be closed by the agent after the deployment confirms the required evidence facts exist — with every retry bounded and byte-identical.

What you always get

  • Per-request minting in local Bearer mode (the verifier treats jti as single-use), so a cached token is never reused where the protocol says not to.
  • Refusals parsed into a matchable *RefusalError (plain and RFC 9457 shapes, Challenge + RetryAfterSec, ChallengeUnavailable when a challenge was announced but unusable).
  • Refresh-on-401 only for idempotent requests or replayable bodies.
  • No evidence ever transmitted on the wire — the protocol has no evidence channel; EvidenceProvider only asks the deployment a question.

Repository layout

aicagent.go     Agent client aggregating identity + transports
aicrequest.go   user-signer submission → approval → core AIC issuance
clc.go          CLC-v1 client-side decision pre-check
identity/       agent key material and fingerprints (SPKI, RFC7638 thumb)
bearer/         local minting (Sign) and DA exchange (SignDA, IssuerClient)
transport/      Bearer and mTLS http.RoundTrippers
llm.go          OpenAI-compatible chat client (Agent.Chat)
examples/       call-bearer, call-mtls, smoke-call
smoke/          CLC corpus + issuance-flow smoke (build tag smoke)

Other entry pages