Is this Excaliwow’s authentication architecture?

No. It is a deliberately generic OAuth authorization-code + PKCE review fixture. It does not describe Excaliwow authentication or any named identity provider.

What should an OAuth sequence diagram show?

At minimum, show the browser redirects, state creation and validation, PKCE challenge and server-held verifier, back-channel code exchange, session creation, and failure paths. Keep provider-specific behavior out unless your source proves it.

Why include the state-mismatch path?

Because the security decision is easy to hide in a happy-path diagram. A mismatch must stop before token exchange and create no session; making that branch visible gives reviewers something concrete to verify.

Can the agent update the diagram after a security review?

Yes. Ask it to update the same persistent diagram and name the human edit that must remain. Review the resulting canvas again; persistence enables the loop but does not replace verification.

OAuth PKCE sequence · worked example

An OAuth sequence diagram reviewers can challenge

Turn a bounded authorization-code and PKCE note into an editable sequence, then ask a human reviewer to challenge state handling, verifier custody, token exchange, and the failure path.

Input

Defined scope

Agent

First draft

Canvas

Stable URL

Human

Review + edit

Agent

Same-canvas update

Editable OAuth PKCE sequence showing initiation, provider authorization, callback state validation, server-side code exchange, secure session creation, and rejection — Faithful SVG render from the editable v2 spec. Human review emphasizes the state decision; the same-canvas follow-up preserves it while adding failure and cookie detail.Open full-size SVG

A sequence diagram earns trust when it exposes where the browser stops, where the server validates state, and why a mismatch creates no session—not when it merely draws a happy path.

Reproduce it

Copy setup

Bound the source and the claim

Use the supplied fixture or a flow your organization permits you to process. State whether it is illustrative or implementation-derived, and do not present a generic example as your production authentication design.

Connect the existing MCP client

Mint a read + write Personal Access Token and add @excaliwow/mcp. Keep publish and delete off for this review loop, and keep the token outside the repository.

MCP client config

{
  "mcpServers": {
    "excaliwow": {
      "command": "npx",
      "args": ["-y", "@excaliwow/mcp"],
      "env": {
        "EXCALIWOW_TOKEN": "excw_pat_…"
      }
    }
  }
}

Review security before layout polish

Send the exact prompt, open the returned editor URL, and ask a reviewer to find the state check and verifier use. Record corrections on the canvas before asking the agent for the same-diagram failure-path update.

Human review

Change what the agent misunderstood

Highlight state validation as the trust-boundary decision and change the failure node to a strong red treatment.
Add a reviewer note that the verifier stays server-side and tokens never appear in the browser URL.

Same-canvas follow-up

Send the correction back

Update the same diagram in place: add the explicit state-mismatch rejection and secure cookie flags without moving the human-highlighted trust boundary.

Review the critical path, not the pixels

A random state and S256 challenge are created before the provider redirect.
The original verifier stays server-side and is used only in the back-channel exchange.
Missing, expired, or mismatched state is rejected before the token endpoint is called.
Only an opaque HttpOnly, Secure, SameSite=Lax session cookie reaches the browser.

Common questions

Is this Excaliwow’s authentication architecture?: No. It is a deliberately generic OAuth authorization-code + PKCE review fixture. It does not describe Excaliwow authentication or any named identity provider.
What should an OAuth sequence diagram show?: At minimum, show the browser redirects, state creation and validation, PKCE challenge and server-held verifier, back-channel code exchange, session creation, and failure paths. Keep provider-specific behavior out unless your source proves it.
Why include the state-mismatch path?: Because the security decision is easy to hide in a happy-path diagram. A mismatch must stop before token exchange and create no session; making that branch visible gives reviewers something concrete to verify.
Can the agent update the diagram after a security review?: Yes. Ask it to update the same persistent diagram and name the human edit that must remain. Review the resulting canvas again; persistence enables the loop but does not replace verification.

Make the trust boundary reviewable

Start free—no credit card. First 10,000 verified accounts keep the core workspace free; 3 diagrams to start and earn more capacity.

Start free