CREATE in-UI security explainers and spec references for all protocols

[ayomawdb]

What does this PR do?

This PR adds an in-UI security education layer to ProtocolSoup. When someone is exploring a flow, they should be able to find two things easily: the why behind every parameter (what attack it prevents, how that attack works, and how to mitigate it), and the authoritative specs that define the protocol and flow they're looking at.

There are three coordinated additions.

1. Per-parameter explainer panels. Click the (?) next to any parameter in any flow and a ParameterExplainer panel opens with four sections: Purpose, named real-world Attacks, Mitigations (with a many-to-many link back to attacks), and References. The content is grounded in canonical specs and real-world incidents, including Golden SAML, nOAuth (Descope 2023), XML Signature Wrapping, AS Mix-Up, Device-Code Phishing against M365 and Entra, CVE-2025-41115 (Grafana SCIM, CVSS 10.0), CVE-2024-45409 (Ruby-SAML), and CVE-2024-52806 (simplesamlphp XXE), among others. Coverage spans all 8 protocols: OAuth 2.0, OIDC, OID4VCI, OID4VP, SAML 2.0, SPIFFE/SPIRE, SCIM 2.0, and SSF/CAEP/RISC.

2. Specs & references panel on the protocol overview page (/protocol/[id]). Each protocol gets a curated reading list grouped into Core specs, Security & privacy, Companion specs, and Deployment profiles. The lists run from 5 to 14 references per protocol. For example, OAuth2 cites RFC 9700 (BCP 240) along with DPoP, JAR, PAR, and Issuer ID; SAML cites the OASIS Security and Privacy Considerations PDF; SSF cites RFC 8417 along with the push, poll, and subject-identifier RFCs.

3. Specs panel on the flow detail page, sitting at the bottom of every flow. These are deep-anchored references to the specific spec sections that normatively define that flow, plus the security considerations that apply to it. For instance, the authorization-code-pkce flow links to RFC 6749 §4.1, RFC 7636, and RFC 9700 §2.1.1; oid4vp-direct-post-jwt links to §8.3 and §11.2.

Architecture notes:

• A new Attack / Mitigation / ParameterExplainer schema in frontend/src/protocols/explainers/index.ts supports many-to-many threat-to-fix mapping.
• Per-protocol overrides use ${protocolId}:${name} keys, so the same parameter name can carry different stories per protocol. For example, oid4vp:nonce tells a different story from oidc:nonce.
• A context-aware lookup getParameterExplainer(protocolId, name, ctx?) leaves room for future per-flow-step augmentation.
• Reference data lives in protocol-catalog-data.ts as a typed ProtocolReference[] with core | security | companion | profile categories. A single reusable ProtocolReferences component renders both the protocol-overview and flow-detail surfaces.

Fixes #

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Enhancement (improvement to existing functionality)
• Documentation update
• Refactoring (no functional changes)
• New protocol implementation

How was this tested?

• Ran the affected flow in Looking Glass and verified real-time events (N/A since this doesn't touch the flow executions/ Looking Glass, but did a smoke test anyway with OAuth)
• Tested locally with go run ./cmd/server and npm run dev
• Other (describe below)

Static verification:

• npx tsc --noEmit is clean.
• npx eslint src/ is clean.

No backend changes in this PR, so backend behaviour is unaffected.

Checklist

• My commits are signed off (git commit -s) per the DCO
• I have read the CONTRIBUTING guide
• Backend compiles: cd backend && go build ./...
• Backend passes lint: cd backend && golangci-lint run ./...

As of now this returns the following error, which is unrelated to the current PR. No changes to backend was made in this PR.

internal/protocols/scim/patch.go:562:19: inline: Constant reflect.Ptr should be inlined (govet)
        if val.Kind() == reflect.Ptr {

• Frontend passes lint: cd frontend && npm run lint
• Frontend type-checks: cd frontend && npx tsc --noEmit
• I have updated documentation if needed
• I have not committed secrets, credentials, or .env files

Screenshots / Looking Glass output

Explainers:
Details expanded only when "?" icon is clicked:

Specs:

[ParleSec]

reference from spec
URL: 'https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/#spiffe-workload-api'

[ayomawdb]

Also shall we link to spec section at: https://spiffe.io/docs/latest/spiffe-specs/spiffe_workload_api/#521-fetchx509svid

[ParleSec]

@ayomawdb Firstly, thank you for the significant and generous contribution to ProtocolSoup. The direction of the educational content in this PR is high quality and strongly aligned with the mission of the project. It provides a solid foundation for further improvements and refinements to the educational content, which I recognise has been somewhat neglected.

This also marks the first external contribution to ProtocolSoup, and a substantial one at that.

[PASS] The technical components are sound. I do not think further refinement is needed for this initial feature foundation.

[REQUEST CHANGES] There are several cases, noted inline, where protocol reference material and links are partially inaccurate. This includes outdated spec references, broken or stale anchors, and reference heading / section mismatches. Because this PR introduces authoritative educational material, I would like these corrected before approval.

[PASS] I have proofread the explainer material for general accuracy. I am comfortable with the remaining educational content remaining as-is and being refined in further follow-up commits as required.

I’ll remain available for further discussion on this PR.

[ayomawdb]

@ParleSec Thank you for the feedback, and also for building such an awesome platform! It has been incredibly useful for me and my team as a quick reference point for various protocols. I’ll work through the requested changes over the weekend and update the PR accordingly. I’ll also take another pass through all the reference sections from my end to make sure everything is validated. Thanks again for creating such a valuable platform!

[ayomawdb]

Requested changes are done. I left some comments in areas where I had some inputs. Also I have added npm run verify-refs command, and made sure there are no other issues with references. The new script can be used in future to validate new references and labels used. I'll let you decide if this should be a PR check in future (maybe we can narrow it to do this check if protocol-catalog-data.ts is modified). I did not do it myself since a timeout from a spec page could affect PR checks. Hence, letting you make the call here.

[ParleSec]

Glad you and the team have found ProtocolSoup a useful tool! Appreciate the quick turnarounds on the corrections.
Reviewed the catalog and explainer fixes, happy to wrap this as the baseline reference layer now. Any further refinements can come as smaller PRs.

On the verify-reference.mjs - Will look at a CI gate with a path-filtered soft check on PRs and a scheduled hard-fail against main for ongoing maintenance (given some specs are still changing). This is out of scope for the current PR, but good to recognise this can form a larger initiative piggy-backing off the contribution.
Ready to merge.