Design
Status: v0.3.0. Steps 1 to 6 are implemented: caller authentication by WIT with WPT or HTTP signatures, mTLS, JWT-SVID and OAuth access tokens, bearer or DPoP-bound; AAT, asor-03 and RFC 8693 act chains (decoders and per-format checks; no separate invariant engine or authority algebra); audit events, OpenTelemetry spans and the chain view. Items marked Open need a decision before the code that depends on them.
Request pipeline
Section titled “Request pipeline”One ext_authz Check call runs these steps in order and stops at the first failure.
inbound request (via Envoy / Istio / agentgateway ext_authz) 1. sanitize strip Txn-Token, X-Forwarded-*, and WIMSE headers unless the previous hop is allow-listed over mTLS 2. authenticate CredentialVerifier plugins -> CallerIdentity (workload id, key binding, assurance) 3. chain ChainDecoder plugins -> NormalizedChain -> invariant engine -> authority algebra 4. authorize AuthZEN 1.0 evaluation request -> decision (fail closed) 5. mint Txn-Token (typ txntoken+jwt) -> ok_response header, Authorization removed 6. record audit record + OpenTelemetry span + reason code1. Sanitize
Section titled “1. Sanitize”- Deny requests for authorities outside
allowed_authorities, and paths with dot segments, encoded dots or slashes, or empty segments. - An inbound
Txn-Tokenis accepted only from a workload listed ininternal_callersthat proved possession of a key for the request (WIT with WPT or HTTP signature, or mTLS). It is verified and forwarded unchanged. From anyone else it is denied (txn.untrusted_hop). - Never forward the inbound access token downstream (MCP security best practices, Txn-Token draft §13).
2. Authenticate
Section titled “2. Authenticate”CredentialVerifier implementations, chosen by what the request carries:
| Verifier | Input | Built on |
|---|---|---|
wit-wpt |
Workload-Identity-Token + Authorization: WPT |
wimsey-wit, wimsey-wpt |
wit-httpsig |
WIT + RFC 9421 signature | wimsey-httpsig (needs with_request_body for digests) |
mtls |
peer certificate from CheckRequest.attributes.source |
wimsey-mtls, SPIFFE X.509-SVID, one CA per trust domain |
jwt-svid |
bearer JWT-SVID | jsonwebtoken, SPIFFE bundle file per trust domain |
oauth-at |
bearer or DPoP-bound access token | jsonwebtoken (RS256 needed for Dex and Keycloak), configured JWKS |
Trust rules:
- Trust anchors and JWKS locations are configured per trust domain. Keys are never fetched from URLs found inside a token.
- Audience is an exact string match.
- Clock leeway is configurable with a 60 s ceiling.
- WPT
jtiand HTTP signaturenoncereplay are checked against a bounded cache.
Method selection, the Envoy settings each method needs, and their limits are in bindings.md.
3. Delegation chain
Section titled “3. Delegation chain”Three layers, so a new draft is a new plugin:
ChainDecoderper format parses, canonicalizes, checks signatures and links (par_hash,sd_hash, receipts, or nesting only), and produces aNormalizedChain.- A format-neutral invariant engine checks:
- the principal never changes
expis monotone- depth limits hold (
DepthSemantics::{AsorStrict, AatHolderCap}) - audiences only narrow
- no actor repeats
- status and proof of possession hold
- the action is allowed
- An
AuthorityAlgebraper RAR detail type implementssubsumes(parent, child)andpermits(leaf, action). Unknown types are denied.
struct NormalizedChain { profile: Profile, principal: Principal, root: TrustRef, hops: Vec<Hop>, holder_proof: bool }struct Hop { depth: u32, max_depth: Option<u32>, actor: ActorId, delegator: Option<ActorId>, signer: KeyThumbprint, signer_binding: SignerBinding, // RootAnchor | ParentCnf | AuthServer | Unverified link: Link, // ParHash | SdHash | Receipt | NestedOnly authority: Authority, validity: Validity, cnf: Option<Cnf>, status: Option<StatusRef>, assurance: Assurance, // Verified | Declared}Only Verified hops are used for authorization, and only when holder_proof is true: the presenter proved possession of the leaf key for this request. ChainDecoder::decode checks the chain only and sets it to false. Declared hops, such as prior actors in a nested RFC 8693 act claim, go to the audit record and Txn-Token context only.
Order of formats:
- AAT (draft-niyikiza-oauth-attenuating-agent-tokens-02): 229 published vectors, and each hop is signed by the parent’s
cnfkey. - asor (draft-asor-wimse-agent-delegation-chain-03): 36 published vectors; every hop is signed by a trust anchor, and the leaf key is proven with DPoP.
- RFC 8693
actadapter: the actors of a verified access token’sactclaim, signed by its issuer. The current actor isVerifiedonce it is bound to the authenticated caller; prior actors stayDeclaredand never reach the PDP, as RFC 8693 §4.1 requires. Its actors have no key; the gate reads the chain only from a user token bound to a WIT caller, which proved possession of its WIT key for the request, soholder_proofis true there. - Delegate SD-JWT once it has vectors.
4. Authorize
Section titled “4. Authorize”AuthZEN 1.0 POST /access/v1/evaluation, PDP endpoint discovered from /.well-known/authzen-configuration or configured.
Open: the agent-and-principal profile. AuthZEN does not say how to carry an agent acting for a user. Proposal:
subjectis the leaf agent (type: agent,id: workload identifier).context.principalis the original subject.context.chaincarries the hop list and a chain digest.context.assurancerecords which hops were verified.
To be proposed to the AuthZEN WG once it works end to end.
X-Request-IDis set to thetxnvalue and checked in the echo.- Timeouts, transport errors, non-200 responses or a non-boolean
decisionall deny.
5. Mint the Transaction Token
Section titled “5. Mint the Transaction Token”Per draft-ietf-oauth-transaction-tokens-11:
- Header
typ: txntoken+jwt, signed with the trust domain’s key. JWKS is published at/.well-known/jwks.json. - Claims:
aud: trust domaintxn: UUID, also the correlation id everywheresub: principalscope: never wider than the authorized scopereq_wl: caller workload idiat,exp: short, default 60 stctx: chain digest, leaf actor, verified depthrctx: request metadata
- Injected with
ok_response.headers(Txn-Token, overwrite), withAuthorizationinheaders_to_remove. The txn id and chain digest also go intodynamic_metadatafor later filters and access logs. - A token endpoint (RFC 8693 profile) serves services that want a Txn-Token without the gateway, and handles replacement:
txn,subandaudstay the same, scope never widens, and expired tokens are refused. - Open: there is no
subject_token_typeURN for a WIT. Use a private URN and propose one to the WIMSE and OAuth WGs.
6. Record
Section titled “6. Record”- Audit record with the AIMS §11 minimum:
- agent id
- delegating subject
- resource or tool
- action and decision
- timestamp and correlation id (
txn) - posture or risk input
- remediation and its cause
- Records are hash-chained and never contain whole tokens.
- OpenTelemetry: one
visado.authorize {target}span with these attributes, plus onevisado.hopspan event per hop:visado.chain.subjectsvisado.chain.depthvisado.decisionvisado.deny.hopvisado.txn
- GenAI and MCP semantic-convention attributes are added where they apply.
- Deny reasons are stable, language-neutral codes shared with the conformance vectors, for example:
credential.audience_mismatchwpt.replaychain.link_mismatchchain.scope_escalationpdp.unavailable
Chain view
Section titled “Chain view”Off by default. With [chain_view] enabled = true the gate keeps a summary of each recent decision in a bounded in-memory ring buffer (capacity, default 256, at most 10000; 0 keeps none; the oldest entry is dropped first, and everything is lost on restart). Denials of unauthenticated requests are recorded too, so anyone who can reach the proxy can push real entries out: the view is a debugging aid, not an audit trail, which is the visado::audit log. The HTTP listener serves:
| Route | Returns |
|---|---|
GET /api/requests?limit=N |
{"capacity": n, "requests": [...]}, newest first; limit defaults to 100 and is capped by the capacity |
GET /api/requests/{id} |
one summary, or 404 {"error": "not_found"} |
GET /chain |
a single page (plain HTML, CSS and JS in crates/server/ui/, embedded with include_str!; no build step, no CDN) that polls the list every 2 s and draws principal → hops → caller → PDP → decision, with verified hops solid, declared hops dashed and the deny reason on the decision |
A summary holds:
id: the check’s own identifier (thetxnthe gate would mint with), unique per checktxn: the transaction, which a forwarded Transaction Token keeps across hopstime,method,resource(scheme://authority/path, no query)caller,auth_method,principal, each once knowndecision,status,codepdp:{"result": "allow" | "deny"}or{"result": "error", "code": ...}, ornullwhen the PDP was not askedchain:profile,issuer,principal,holder_proof, and per hopdepth,actor_kind(key,nameorsubject),actor,actor_issuer,assurance(verifiedordeclared),link(root,par_hashornested) and the holder key thumbprint; only for a chain that verified
It never holds a token, proof, signature, digest, header value, body or the hop’s authority. The request path is shown as received, without the query: an upstream that puts a secret in the path (/hooks/<secret>) exposes it here, as it does in access logs. Strings are cut to 256 characters and chains to 32 hops (hops_omitted counts the rest).
Deployment modes
Section titled “Deployment modes”- ext_authz server (v0):
tonic+envoy-typesgRPC. One server covers Envoy, Istio (CUSTOMaction) and agentgateway, which vendors the same proto. - Token endpoint and UI (v0):
axumfor the RFC 8693 endpoint, JWKS, health, and the chain view (/api/requests,/chain; see Chain view). The token endpoint is not built yet. - agentgateway ExtMcp (later): tool-aware AuthZEN requests at the MCP method layer.
- Standalone PEP (later, only if asked):
hyper1.x +tower+rustls. Notpingora, which brings its own lifecycle and OpenSSL by default.
Workspace layout
Section titled “Workspace layout”crates/ txn-token mint, verify, replace (published on its own) chain ChainDecoder trait, NormalizedChain, invariants, algebra chain-aat AAT decoder chain-asor asor decoder chain-act RFC 8693 act adapter authzen AuthZEN 1.0 client and the agent profile credentials CredentialVerifier trait and verifiers (wraps wimsey) extauthz Envoy ext_authz server server binary: config, token endpoint, JWKS, UI, telemetry conformance vectors, generator and runner (format as in wimsey)deploy/aims-lab compose file for the end-to-end lab and the attack demoscrates/server/ui/ chain view (plain HTML, CSS and JS), embedded with include_str!Reference lab (aims-lab)
Section titled “Reference lab (aims-lab)”user --login--> Dex (ID-JAG issuance, master build)agent A --ID-JAG--> Keycloak 26.7+ (Resource AS, experimental feature) --> access tokenagent A (SPIRE WIT-SVID) --WIT+WPT, delegation token--> [Envoy + visado] --Txn-Token--> agent Bagent B --> [Envoy + visado] --> MCP servervisado --AuthZEN--> OPA with the AuthZEN pluginKnown setup constraints, from reading the code (not yet run):
- the Dex client id must equal the Keycloak clientId
- the ID-JAG audience must be the Keycloak realm issuer
- Keycloak users must be pre-linked by Dex’s opaque
sub
The lab also hosts the attack demos in research/05-threats.md:
- agent-to-agent escalation
- token passthrough and replay
- chain splicing across tenants
- one malicious-server case that visado does not stop
Open questions
Section titled “Open questions”- Which ID-JAG revision to accept: the MCP extension cites -04 and the latest is -06. Proposal: accept both and record which one passed.
del_max_depthsemantics differ between AAT and asor. Proposal: per-profile setting, reported in the audit record.- The Txn-Token draft does not define a representation of the call chain across replacement. Proposal: carry the chain digest in
tctxand note it as a divergence. - Key storage beyond files (KMS/HSM) and per-trust-domain key separation.
- Name of the WIT
subject_token_typeURN to propose.
© 2026 The visado Authors. Licensed under Apache-2.0.
Third-party logos are trademarks of their respective owners and are used to show compatibility; their use does not imply endorsement.