docs: ODIS role-capability statement + executable walkthrough notebooks

[rsharath]

Summary

Docs-only. Adds ZeroID's ODIS (Open Delegation & Identity Standard, CoSAI/OASIS WS4) role-capability statement and two executable companion notebooks.

• docs/odis/role-capability-statement.md — maps every ODIS Layer 1–2 requirement (plus L3 and cross-cutting) to code paths and greppable test names, with an explicit Meets / Meets-via-configuration / Partial / Gap / N/A verdict per row. Gaps (software attestation, bridge-mode adapters, presenter isolation, benchmarks) are stated, not argued around. Pinned to commit 1676b4f.
• examples/odis/odis-walkthrough.ipynb — raw-HTTP walkthrough: registration record → attestation-gated trust → DPoP-bound runtime credential → delegation with monotonic attenuation → cascade revocation → audit lineage. Outputs committed from a real run against the hardened image.
• examples/odis/odis-walkthrough-sdk.ipynb — same flow via the Python SDK, adding the ODIS-aware target view (local JWKS verification, typed guards, revocation checking).
• examples/odis/README.md — run instructions, plus the stale-volume upgrade note (pre-CIBA default policies don't self-heal; docker compose down -v or add the CIBA grant).

Grading state

With token.require_dpop from #304, L1-09 Holder-of-Key flips to Meets (via configuration), taking L1 to 9 Meets / 0 Partial / 3 Gap.

Test plan

• Both notebooks re-executed end-to-end against a fresh deployment of the feat: token.require_dpop + attestation/CIBA issuance-integrity fixes #304 image; all committed outputs are real.
• Every evidence pointer in the statement verified against 1676b4f.
• CI (the notebook check only runs examples/zeroid_quickstart.ipynb; the ODIS notebooks are not wired into CI in this PR).

No code changes. Merges clean onto main.

[highflame-oracle]

🔮 Oracle Review

🎯 Start Here

examples/odis/odis-walkthrough-sdk.ipynb — Critical security risk detected in file

Why this first: Thoroughly review for security vulnerabilities

---

📋 PR Summary

What this PR does: Docs-only PR adding ZeroID's ODIS role-capability statement (CoSAI/OASIS WS4) plus two executable companion notebooks demonstrating the full identity lifecycle — registration, attestation-gated trust, DPoP-bound runtime credentials, delegation with monotonic attenuation, cascade revocation, and audit lineage.

Key changes:

• role-capability-statement.md mapping every ODIS L1–L2 requirement (plus L3 and cross-cutting) to code paths and greppable test names, with explicit Meets / Meets-via-configuration / Partial / Gap / N/A verdicts, pinned to commit 1676b4f
• examples/odis/odis-walkthrough.ipynb — raw-HTTP walkthrough with committed outputs from a real run against the hardened #304 image
• examples/odis/odis-walkthrough-sdk.ipynb — same flow via the Python SDK, adding the ODIS-aware target view (local JWKS verification, typed guards, revocation checking)
• examples/odis/README.md with run instructions and a stale-volume upgrade note (pre-CIBA default policies don't self-heal)

Areas affected: documentation, examples, ODIS conformance/compliance artifacts

Testing notes: Both notebooks were re-executed end-to-end against a fresh deployment of the #304 image; all committed outputs are real and contain no credential material. The ODIS notebooks are not wired into CI (the notebook check only covers examples/zeroid_quickstart.ipynb). No code changes; merges clean onto main.

---

🔍 Code Review

A genuinely strong docs-only contribution: the capability statement is honest about gaps rather than arguing around them, and both notebooks are executed artifacts that assert failure paths instead of only showing happy paths, with zero secrets leaking into committed outputs. The one substantive defect is the §10 inconsistency in the raw-HTTP walkthrough, where the prose claims credentials are cascade-revoked while the same cell's committed output shows credentials_revoked: 0 — worth fixing before this becomes canonical reference material, since the artifact's entire purpose is attesting security behavior. Remaining asks (documenting the demo's admin auth model, exercising the SDK audience check, explaining trust-claim/re-issuance semantics, pinning the SDK version) are all strengthening suggestions, not blockers.

What's good:

• ✨ Committed notebook outputs contain no credential material — clean hygiene for an executable doc published from a real run
• ✨ Failure paths are asserted in the walkthroughs rather than hidden, and gaps (software attestation, bridge-mode adapters, presenter isolation, benchmarks) are stated explicitly in the capability statement instead of being argued around — exactly the honesty a conformance artifact needs
• ✨ The SDK notebook deliberately demonstrates its own revocation-blindness and cross-references the load-bearing sdk#105 DPoP gap, turning a limitation into documented, actionable knowledge
• ✨ Per-row verdicts pinned to a specific commit (1676b4f) make the capability statement reproducible and auditable rather than a floating claim

Review Stats:

---

Generated by Oracle - Highflame's AI Code Reviewer

[highflame-oracle]

🔮 Oracle Review

🎯 Start Here

examples/odis/odis-walkthrough-sdk.ipynb — Critical security risk detected in file

Why this first: Thoroughly review for security vulnerabilities

---

📋 PR Summary

What this PR does: Documentation-only PR adding ZeroID's ODIS role-capability statement (mapping Layer 1–2 plus L3 and cross-cutting requirements to code paths, greppable test names, and per-row verdicts) along with two executable companion notebooks demonstrating the full identity/delegation flow via raw HTTP and via the Python SDK.

Key changes:

• Adds docs/odis/role-capability-statement.md with per-requirement verdicts (Meets / Meets-via-configuration / Partial / Gap / N/A), evidence pointers pinned to commit 1676b4f, and explicit disclosure of gaps (software attestation, bridge-mode adapters, presenter isolation, benchmarks)
• Adds examples/odis/odis-walkthrough.ipynb — raw-HTTP walkthrough covering registration record, attestation-gated trust, DPoP-bound runtime credential, delegation with monotonic attenuation, cascade revocation, and audit lineage, with committed outputs from a real run
• Adds examples/odis/odis-walkthrough-sdk.ipynb — same flow via the Python SDK, plus the ODIS-aware target view (local JWKS verification, typed guards, revocation checking)
• Adds examples/odis/README.md with run instructions and a stale-volume upgrade note for pre-CIBA default policies

Areas affected: ODIS compliance documentation, Developer onboarding / example notebooks, docs/odis and examples/odis

Testing notes: Both notebooks were re-executed end-to-end against a fresh deployment of the #304 image; committed outputs are from real runs. Two considerations: (1) the ODIS notebooks are not wired into CI (only examples/zeroid_quickstart.ipynb is checked), so committed outputs and evidence pointers can drift silently as the code evolves — acknowledged by the author as an open item; (2) since outputs come from a real run, it's worth a quick scan to confirm no access tokens or credentials are visible in committed cell outputs.

---

🔍 Code Review

This is an exemplary documentation contribution: the capability statement uses an evidence-based, per-row verdict format with honest Gap disclosures rather than optimistic framing, and every claim is verifiable against a pinned commit and real notebook outputs. The main durability risk is that the notebooks sit outside CI, so both the committed outputs and the statement's evidence pointers will rot as the code evolves — a follow-up to add an execution smoke-check would close that loop. Worth a quick pass over the committed notebook outputs to confirm no tokens from the real run are exposed.

What's good:

• ✨ Honest gap disclosure in the capability statement — software attestation, bridge-mode adapters, presenter isolation, and benchmarks are stated as Gaps rather than argued around, which is exactly how a compliance document should be written
• ✨ Committed notebook outputs from real runs against the hardened image make the walkthroughs verifiable evidence rather than aspirational documentation
• ✨ Cross-referencing the SDK's missing DPoP proof construction (sdk#105) as load-bearing under a require_dpop server keeps the L1-09 'Meets via configuration' verdict honest and actionable
• ✨ Documenting the stale-volume upgrade gotcha (pre-CIBA default policies don't self-heal) in the README will save real debugging time for anyone upgrading an existing deployment

---

Generated by Oracle - Highflame's AI Code Reviewer

[highflame-oracle]

🔮 Oracle Review

🎯 Start Here

examples/odis/odis-walkthrough-sdk.ipynb — Critical security risk detected in file

Why this first: Thoroughly review for security vulnerabilities

---

📋 PR Summary

What this PR does: Docs-only PR adding ZeroID's ODIS (CoSAI/OASIS WS4) role-capability statement, mapping every Layer 1-2 (plus L3 and cross-cutting) requirement to code paths and greppable test names with per-row verdicts, accompanied by two executable walkthrough notebooks (raw-HTTP and SDK flavors) and a README with run instructions.

Key changes:

• role-capability-statement.md: requirement-to-implementation matrix with Meets / Meets-via-configuration / Partial / Gap / N/A verdicts, pinned to commit 1676b4f, with gaps (software attestation, bridge-mode adapters, presenter isolation, benchmarks) explicitly stated
• odis-walkthrough.ipynb: raw-HTTP walkthrough of the full lifecycle (registration record, attestation-gated trust, DPoP-bound runtime credential, delegation with monotonic attenuation, cascade revocation, audit lineage) with outputs committed from a real run against the hardened #304 image
• odis-walkthrough-sdk.ipynb: same flow via the Python SDK, adding the ODIS-aware target view with local JWKS verification, typed guards, and revocation checking
• README.md: run instructions plus an operational note that pre-CIBA default policies on stale volumes don't self-heal (requires docker compose down -v or adding the CIBA grant)
• Documents the grading-state change from #304: token.require_dpop flips L1-09 Holder-of-Key to Meets (via configuration), bringing L1 to 9 Meets / 0 Partial / 3 Gap

Areas affected: documentation, examples, ODIS compliance/conformance reporting

Testing notes: Both notebooks were re-executed end-to-end against a fresh deployment of the #304 image, and every evidence pointer in the statement was verified against 1676b4f. However, the ODIS notebooks are not wired into CI — the notebook check only covers examples/zeroid_quickstart.ipynb — so they can silently rot as APIs evolve. This is the main follow-up worth tracking.

---

🔍 Code Review

This is exactly what a conformance document should be: every claim is pinned to a commit, backed by greppable test names, and gaps are stated plainly rather than argued around. The notebooks are genuinely executable with real committed outputs and exemplary secret hygiene, which makes them far more trustworthy than prose-only claims. The only substantive weakness is the absence of CI wiring for the new notebooks — the inline asks (credential-story clarity, audience enforcement in verify calls, admin/target plane separation) are polish, not blockers.

What's good:

• ✨ Honest gap reporting: stating software attestation, bridge-mode adapters, presenter isolation, and benchmark gaps as gaps rather than spinning them as partial wins — this is the single biggest credibility multiplier for a conformance statement
• ✨ Committing real, executed notebook outputs rather than fabricated ones, with secrets properly scrubbed — reviewers and auditors can trust what they read
• ✨ Pinning the statement to a specific commit (1676b4f) makes every evidence pointer verifiable rather than aspirational
• ✨ The verify-vs-introspect revocation lesson in the SDK notebook teaches the right architectural pattern (local verification with revocation checking over chatty introspection)
• ✨ The stale-volume upgrade note in the README preemptively addresses a support burden (pre-CIBA policies not self-healing) that would otherwise surface as confusing bug reports

Review Stats:

---

Generated by Oracle - Highflame's AI Code Reviewer

[rsharath]

Addressed the review findings in the two commits ending at 8ebd54f (branch also rebased onto current main). Both notebooks were re-executed against a fresh stack; committed outputs are real.

§10 credentials_revoked: 0 vs "cascade-revokes" (medium) — the confusion was legitimate but the theorized cause (introspection failing closed rather than actual revocation) is not what happens: the cascade runs inside each identity's deactivation, and credentials_revoked only counts stragglers caught by a final safety-net sweep, so 0 is the healthy value. §10 now explains the counter semantics and proves revocation on the wire — the new output shows the CIBA credential's audit edge with is_revoked: true, revoke_reason: "identity_deactivated", plus asserts on both. This also resolves the cross-file concern against the statement's cascade verdict.

Credential material in committed outputs (medium) — audited: clean. Cells print decoded claims and selected fields only; no raw JWTs, zid_sk_ keys, registration secrets, or private-key material appears in any committed output (the client_secret grep hits are variable names in source cells). CI now enforces this: a lint step fails the PR on eyJ…/zid_sk_/PEM-block patterns in any committed notebook.

Notebook rot / CI wiring — both ODIS notebooks are now executed in highflame-notebook-check on every PR, alongside the quickstart, against the same fresh compose stack.

L1-09 config coherence — README gained a per-notebook configuration matrix (raw walkthrough chooses the require_dpop: false default to show the Bearer fallback being closed; SDK walkthrough requires it until sdk#105), the SDK notebook states the requirement up front, and the statement's L1-09 note cross-references the matrix.

SDK version pin — pinned, with a twist discovered while addressing it: highflame==0.3.17 is load-bearing, not just reproducibility hygiene. From 0.3.23 the Python SDK targets the SaaS-shaped admin plane (admin routes at the server root, nhi:manage bearer auth), while stock OSS zeroid mounts admin under /api/v1 (server.admin_path_prefix) — newer SDKs 404 on every admin call against this compose deployment. Documented in the README, notebook prerequisites, and the SDK-gaps appendix.

Teaching-hygiene items, all applied — dev trust-model callouts in both notebooks (unauthenticated admin plane, client-supplied tenant headers, body-named CIBA approval subject — with the production contrast); claims_of() marked display-only with a pointer to verified decoding; revocation-blindness caution inline at §3 where tokens.verify is introduced; trust-minted-into-token explanation including the demotion corollary (demotion must travel with revocation, not just a record update); a live verify(audience=...) demo (pass + wrong-audience refusal); and a stale-volume hint at §7's exact point of failure.

[rsharath]

Rebased onto main and migrated for #318: the raw-HTTP walkthrough's admin calls now use the root-mounted admin API (no /api/v1 prefix), the SDK walkthrough and CI pin highflame==0.3.23 (which speaks the root-mounted admin plane natively — the pin-rationale caveat is obsolete and gone), and the statement re-pins its evidence commit to current main (d2531cd). The L1-09 configuration caveat stands: 0.3.23 still cannot construct DPoP proofs (sdk#105). Both notebooks re-executed against a fresh compose build of this branch; committed outputs are real and the credential-material lint is clean.