title auth51 — Agent Identity: Registration & Runtime Recognition\n(reference impl of draft-goswami-agentic-jwt)

actor "Developer / CI" as Dev
participant "Console\n(manual UI)" as Console
participant "Agent\n(framework-agnostic)" as Agent
participant "auth51 Client\n(embed / interceptor)" as Client
participant "auth51-checksum\n(canonicalize · template · regex)" as Cksum
participant "LLM Provider\n(OpenAI / Anthropic)" as LLM
database "Authority\n(registry + mint)" as Auth

note over Dev,Auth: LOCKED DEFAULTS (baked into this spec — veto any):\n1) Slot markers canonicalized to POSITIONAL tokens before hashing → checksum is name-independent\n2) Observed inference needs >=2 diverse runs; 1 run = assume clean + WARN\n3) Template→regex is ANCHORED + non-greedy; greedy/oversized slots are linted\n4) Authority list-agents returns VERBATIM prompt_template per tenant (client needs the text, not just the checksum)

== Phase 1A · Registration — Manual (console / Postman / wizard / discovery review) ==
autonumber 1
Dev->Console: author agent: prompt_template (clean OR with {{slots}}), tools, config
Console->Cksum: canonicalize(prompt_template)\n(slot markers → positional tokens)
Cksum-->Console: canonical identity string
Console->Cksum: compute v3 / v4 / v5 over {agent_id, canonical, config, tools}
Cksum-->Console: registered_v3 / v4 (/ v5)
Console->Auth: POST /v1/intent/register/agent\n{agent_id, prompt_template (verbatim), config, tools, checksums}
Auth-->Console: 200 registered
note over Auth: stores VERBATIM prompt_template + checksums,\nscoped to tenant (app_id)

== Phase 1B · Registration — Observed CI/CD (inference, zero declared template) ==
autonumber 1
Dev->Agent: exercise run #1 (input A)
Agent->LLM: provider request (system = filled prompt_1, tools)
Client->Client: intercept egress → observe system_prompt_1, tools
Dev->Agent: exercise run #2 (input B)   [>=2 DIVERSE inputs required]
Agent->LLM: provider request (system = filled prompt_2, tools)
Client->Client: intercept egress → observe system_prompt_2, tools
loop each additional diverse run
Client->Client: observe system_prompt_i
end
alt prompts identical across all runs
note over Client: CLEAN agent → template = observed verbatim (no slots)
else prompts differ
Client->Client: diff(observed prompts) → stable skeleton + varying spans\n→ inferred template with {{slot_0..n}} (auto-named)
note over Client: slots = OBSERVED variance (a fact, not a\ndeveloper assertion) → harder to game
end
opt only 1 run supplied
note over Client: cannot verify stability → assume clean + WARN\n("exercise every dynamic path in CI")
end
Client->Cksum: canonicalize(template) + compute v3 / v4 / v5
Cksum-->Client: checksums
Client->Auth: POST /v1/intent/register/agent\n{agent_id, template (verbatim), config, tools, checksums}
Auth-->Client: 200 registered

== Phase 2 · Client startup — load registry ==
autonumber 1
Client->Auth: GET registered agents for app_id   (scope: read:agents)
Auth-->Client: [ {agent_id, prompt_template (verbatim), config, registered_v3/v4, tools} ]
Client->Client: partition candidates →\nCLEAN set (no slots) | SLOTTED set (has {{ }})
note over Client: templates held VERBATIM in memory.\nThe checksum is NEVER reversed — the text is loaded alongside it.

== Phase 3 · Runtime recognition — per provider egress ==
autonumber 1
Agent->LLM: provider request (via patched httpx)
Client->Client: intercept → observed = first system message (fully filled), observed_tools
note over Client: observed has NO visible {{ }} — placeholders already replaced

group Exact path — recognizes CLEAN agents (cryptographic)
loop candidate in CLEAN set
Client->Cksum: recompute v3/v4(observed, cand.config, observed_tools)
Cksum-->Client: checksum
opt checksum == cand.registered_v3/v4
note over Client: MATCH → identity = cand\n(mint cand's recomputed checksum)
end
end
end

alt no exact match
group Fallback fit path — recognizes BLENDED agents (structural)
loop candidate in SLOTTED set
Client->Cksum: compile cand.template → anchored regex\n(fixed spans exact, slots = bounded non-greedy groups)
Cksum-->Client: regex
Client->Client: does observed FIT this template?
end
alt exactly 1 template fits
note over Client: MATCH → identity = cand.\nMint cand.registered checksum (stored at registration —\nnot re-hashed; a filled instance can't hash to a slotted template).\nTamper-evidence = fixed skeleton must match exactly.
else more than 1 fits
note over Client: AMBIGUOUS → fail-CLOSED, log
else 0 fits
note over Client: UNREGISTERED → discovery signal
end
end
end

== Phase 4 · Governed egress — mint on match ==
autonumber 1
Agent->Client: tool → RS egress (in-process tool OR MCP call)
alt identity matched (Phase 3)
Client->Auth: POST /v1/intent/token\n{grant_type=agent_checksum, checksum, scope, aud=rs_id}
Auth-->Client: intent token (scoped, verifiable)
Client->Client: stamp Authorization header / MCP _meta
Client->Agent: proceed with governed call
else no match
note over Client,Auth: fail-CLOSED — no mint (unless OAuth mode explicitly enabled)
end
