From cc8f15167f997efe484a7e49b18eb2ecdd6dd743 Mon Sep 17 00:00:00 2001 From: Dasith Wijes Date: Thu, 1 Oct 2026 14:18:04 +0000 Subject: [PATCH] docs: fix Mermaid sequence diagrams broken by semicolons Mermaid treats ';' as a statement separator in sequence diagrams, so message text containing a semicolon was truncated and the remainder failed to parse (e.g. the Three-Party Flow diagram in README.md). Replace prose semicolons with commas, and use Mermaid entity codes (#lt; #gt; #59;) where the characters are meaningful syntax in bootstrap-enrollment.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- docs/getting-started.md | 6 +++--- docs/workflows/bootstrap-enrollment.md | 4 ++-- docs/workflows/federated-access.md | 2 +- docs/workflows/ps-asserted-access.md | 2 +- docs/workflows/resource-managed-access.md | 2 +- docs/workflows/wallet-protocol.md | 4 ++-- samples/Concierge/README.md | 2 +- 8 files changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 82e54797..693f9088 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ sequenceDiagram Agent->>PS: POST /person (signed, resource) PS-->>Agent: person_token Agent->>Resource: GET /data (signed, person_token) - Resource-->>Agent: 401 + requirement=auth-token; resource_token + Resource-->>Agent: 401 + requirement=auth-token, resource_token Agent->>PS: POST /token (signed, resource_token + presented_token) PS->>User: Consent prompt (scope, justification) User-->>PS: Grant consent diff --git a/docs/getting-started.md b/docs/getting-started.md index ff8c70e9..210e84cc 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -173,15 +173,15 @@ sequenceDiagram Resource->>Resource: Verify agent token and key proof Resource-->>Agent: 401 + requirement=person-token - Agent->>PS: POST /person (signed; resource=https://resource.example) + Agent->>PS: POST /person (signed, resource=https://resource.example) PS->>PS: Validate agent token, mission/context and person selection PS-->>Agent: person_token (aa-person+jwt) Agent->>Resource: GET /data (Signature-Key: sig=jwt, person token) Resource->>Resource: Verify person token, copy ps/sub and set presented_jti - Resource-->>Agent: 401 + requirement=auth-token; resource-token=... + Resource-->>Agent: 401 + requirement=auth-token, resource-token=... - Agent->>PS: POST /token (signed; resource_token + presented_token) + Agent->>PS: POST /token (signed, resource_token + presented_token) PS->>PS: Verify resource token and the named presented token PS->>User: Consent prompt (scope, justification) User-->>PS: Grant consent diff --git a/docs/workflows/bootstrap-enrollment.md b/docs/workflows/bootstrap-enrollment.md index 8ce95bd2..c8ea703b 100644 --- a/docs/workflows/bootstrap-enrollment.md +++ b/docs/workflows/bootstrap-enrollment.md @@ -213,8 +213,8 @@ sequenceDiagram participant AP as Agent Provider Note over Agent: Token nearing expiry Agent->>Agent: Generate ephemeral Ed25519 key - Agent->>Agent: Build naming JWT (jkt-s256+jwt, signed by durable key,
durable jwk in header, iss=urn:jkt:sha-256:<thumbprint>,
ephemeral key as cnf.jwk) - Agent->>AP: POST /refresh {} (signed with ephemeral key,
Signature-Key: sig=jkt-jwt;jwt="<naming-jwt>") + Agent->>Agent: Build naming JWT (jkt-s256+jwt, signed by durable key,
durable jwk in header, iss=urn:jkt:sha-256:#lt;thumbprint#gt;,
ephemeral key as cnf.jwk) + Agent->>AP: POST /refresh {} (signed with ephemeral key,
Signature-Key: sig=jkt-jwt#59;jwt="#lt;naming-jwt#gt;") AP->>AP: Self-anchor — thumbprint(header jwk) == iss, verify naming JWT signature AP->>AP: Look up enrolment by the durable key thumbprint (bind to record) AP->>AP: Verify HTTP signature against ephemeral cnf.jwk diff --git a/docs/workflows/federated-access.md b/docs/workflows/federated-access.md index 50549b6b..2b4f242d 100644 --- a/docs/workflows/federated-access.md +++ b/docs/workflows/federated-access.md @@ -17,7 +17,7 @@ sequenceDiagram Agent->>Resource: GET /data (signed, person token) Resource-->>Agent: 401 + resource token (aud=AS URL) Agent->>PS: POST /token (resource_token, presented_token) - PS->>AS: POST /token (signed; resource_token, agent_token, presented_token) + PS->>AS: POST /token (signed, resource_token, agent_token, presented_token) AS-->>PS: auth token (iss=AS) PS-->>Agent: auth token Agent->>Resource: GET /data (signed, auth token) diff --git a/docs/workflows/ps-asserted-access.md b/docs/workflows/ps-asserted-access.md index 89d13df7..5d4c9bf9 100644 --- a/docs/workflows/ps-asserted-access.md +++ b/docs/workflows/ps-asserted-access.md @@ -23,7 +23,7 @@ sequenceDiagram Agent->>PS: POST /person (signed, resource in body) PS-->>Agent: 200 + person token (aa-person+jwt) Agent->>Resource: GET /data (signed, sig=jwt with person token) - Resource-->>Agent: 401 requirement=auth-token + resource token (aud=PS; presented_jti) + Resource-->>Agent: 401 requirement=auth-token + resource token (aud=PS, presented_jti) Agent->>PS: POST /token (signed, resource_token + presented_token) PS-->>Agent: 200 + auth token (aa-auth+jwt) Agent->>Resource: GET /data (signed, sig=jwt with auth token) diff --git a/docs/workflows/resource-managed-access.md b/docs/workflows/resource-managed-access.md index cebd5b0d..8b0b15a1 100644 --- a/docs/workflows/resource-managed-access.md +++ b/docs/workflows/resource-managed-access.md @@ -38,7 +38,7 @@ sequenceDiagram participant User Note over Agent: Setup complete: self-issued or AP-enrolled agent JWT Agent->>Resource: GET /data (jwt + HTTP proof) - Resource-->>Agent: 202 + Location + requirement=interaction; url; code + Resource-->>Agent: 202 + Location + requirement=interaction, url, code Note over Agent: Start signed polling immediately User->>Resource: Completes interaction at resource's page Agent->>Resource: GET /pending/ (poll) diff --git a/docs/workflows/wallet-protocol.md b/docs/workflows/wallet-protocol.md index f8f87bd4..5e218fd6 100644 --- a/docs/workflows/wallet-protocol.md +++ b/docs/workflows/wallet-protocol.md @@ -59,7 +59,7 @@ sequenceDiagram Agent->>PS: Signed pending GET PS-->>Agent: AS-issued auth_token Agent->>Wallet: Review with auth_token - Wallet-->>Agent: 200; charge with same scope is rejected + Wallet-->>Agent: 200, charge with same scope is rejected ``` ## Chaining an AS-Issued Grant @@ -96,7 +96,7 @@ sequenceDiagram Concierge->>PS: resource_token, presented_token, upstream_token PS->>AS: Signed federation, agent_token (Concierge), presented_token, upstream_token AS->>AS: Validate upstream audience and PS, presented token, scope - AS-->>PS: Downstream auth_token (ps, sub; no agent or act claim) + AS-->>PS: Downstream auth_token (ps, sub, no agent or act claim) PS-->>Concierge: Downstream auth_token Concierge->>Wallet: Retry with downstream auth_token Wallet-->>Concierge: 200 diff --git a/samples/Concierge/README.md b/samples/Concierge/README.md index 8311d72c..53e7d236 100644 --- a/samples/Concierge/README.md +++ b/samples/Concierge/README.md @@ -36,7 +36,7 @@ sequenceDiagram C->>Cal: GET /events (signed, person token) Cal-->>C: 401 + resource_token C->>PS: exchange resource_token + presented_token + upstream_token - PS-->>C: downstream auth token (ps + sub name the person; no agent or act) + PS-->>C: downstream auth token (ps + sub name the person, no agent or act) C->>Cal: GET /events (signed, downstream auth token) Cal-->>C: 200 OK C-->>A: 200 OK (combined chain result)