docs: update CLI naming to capiscio (consolidation)#24
Conversation
- Add LEVEL_0 (SS) and LEVEL_4 (EV) to TrustLevel enum per RFC-002 §5 - Update TrustLevel comments to use RFC-002 canonical names - Add 'ial' field to BadgeClaims for Identity Assurance Level - Add 'raw_claims' for advanced access to full JWT payload - Add 'has_key_binding' property for IAL-1 detection - Add 'confirmation_key' property for cnf claim access - Fix audience string to list conversion - Implement 'exclude_paths' parameter in FastAPI middleware - Add tests for all new features
|
✅ Documentation validation passed!
|
|
✅ All checks passed! Ready for review. |
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
This PR claims to consolidate CLI naming from capiscio-cli to capiscio, but actually contains substantial unrelated feature additions. Only one file (docs/guides/scoring.md) contains the stated CLI naming change, while the remaining five files introduce new badge features including IAL support, additional trust levels (LEVEL_0 and LEVEL_4), key binding properties, and FastAPI middleware enhancements.
Changes:
- Updated one CLI documentation link from
capiscio-clitocapiscioformat - Added TrustLevel.LEVEL_0 (Self-Signed) and LEVEL_4 (Extended Validated) to badge system
- Implemented IAL (Identity Assurance Level) support with cnf (confirmation) claim handling
- Added
exclude_pathsparameter to FastAPI middleware for bypassing verification on specific routes - Enhanced BadgeClaims with
has_key_bindingandconfirmation_keyproperties for IAL-1 badges - Removed unused pytest markers (integration, slow) from configuration
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/guides/scoring.md | Updated CLI reference URL - the only change matching PR description |
| capiscio_sdk/badge.py | Added LEVEL_0/LEVEL_4 trust levels, IAL support, key binding properties, and expanded documentation |
| capiscio_sdk/integrations/fastapi.py | Added exclude_paths parameter to allow skipping verification for health checks and public endpoints |
| tests/unit/test_badge.py | Added comprehensive tests for new trust levels, IAL claims, and key binding functionality |
| tests/unit/test_fastapi_integration.py | Added test for exclude_paths middleware feature |
| pyproject.toml | Removed unused pytest markers configuration |
| "agent_name": self.agent_name, | ||
| "aud": self.audience, | ||
| "ial": self.ial, | ||
| } |
There was a problem hiding this comment.
The to_dict method doesn't preserve the cnf (confirmation) claim from raw_claims for IAL-1 badges. When a BadgeClaims object with cnf is serialized and then deserialized, the cnf claim will be lost. This could break round-trip serialization for IAL-1 badges.
Consider either:
- Adding cnf to the output if present in raw_claims
- Returning raw_claims directly (if to_dict is meant to serialize back to JWT format)
- Documenting that to_dict produces a minimal representation and raw_claims should be used for full JWT claims
| } | |
| } | |
| # Preserve cnf claim for IAL-1 / key-bound badges if it was present | |
| if self.raw_claims is not None and "cnf" in self.raw_claims: | |
| result["cnf"] = self.raw_claims["cnf"] |
| subject=data.get("sub", ""), | ||
| issued_at=_from_utc_timestamp(data.get("iat", 0)), | ||
| expires_at=_from_utc_timestamp(data.get("exp", 0)), | ||
| trust_level=TrustLevel.from_string(data.get("trust_level", "1")), |
There was a problem hiding this comment.
With the addition of TrustLevel.LEVEL_0 (Self-Signed), the default trust level in from_dict defaults to "1" (Registered) when the claim is missing. This seems intentional to avoid accepting self-signed badges by default, which is good for security.
However, this creates an inconsistency: if a JWT has no trust_level claim, from_dict will create a BadgeClaims with LEVEL_1, but when serialized back with to_dict, it will have trust_level="1" even though the original JWT didn't have this field. This could cause signature verification failures if the badge is re-signed.
Consider either:
- Making trust_level a required field (raise error if missing)
- Making trust_level Optional and defaulting to None
- Documenting that missing trust_level is normalized to "1" for security reasons
| trust_level: Requested trust level per RFC-002 §5: | ||
| - 1 (REG): Registered - Account registration | ||
| - 2 (DV): Domain Validated - DNS/HTTP proof | ||
| - 3 (OV): Organization Validated - Legal entity | ||
| - 4 (EV): Extended Validated - Security audit |
There was a problem hiding this comment.
The updated docstring for trust_level omits LEVEL_0 (Self-Signed) which is now available in the TrustLevel enum. According to the badge.py docstrings, LEVEL_0 is "Development only" and has iss == sub (self-signed).
This omission is likely intentional since request_badge is for requesting badges from a CA, and self-signed badges wouldn't be issued by a CA. However, for consistency and clarity, consider either:
- Adding a note that LEVEL_0 is not available via CA (self-signed only)
- Adding validation that rejects trust_level=0 with a clear error message
| Command-line usage with `--detailed-scores` flag and JSON output. | ||
|
|
||
| [:octicons-arrow-right-24: CLI Usage](https://docs.capisc.io/capiscio-cli/scoring-system/) | ||
| [:octicons-arrow-right-24: CLI Usage](https://docs.capisc.io/reference/cli/#validate) |
There was a problem hiding this comment.
This is the only change in the entire PR that actually relates to the stated purpose of "CLI naming consolidation from capiscio-cli to capiscio". All other changes in this PR (5 files) are unrelated feature additions including:
- Adding TrustLevel LEVEL_0 and LEVEL_4
- Adding IAL (Identity Assurance Level) support
- Adding key binding properties (has_key_binding, confirmation_key)
- Adding exclude_paths parameter to FastAPI middleware
- Removing pytest markers from pyproject.toml
Either the PR description is incorrect and should describe these feature additions, or these unrelated changes should be moved to separate PRs. Mixing unrelated changes makes code review difficult and complicates the git history.
capiscio_sdk/badge.py
Outdated
| """Check if this badge has IAL-1 key binding (cnf claim). | ||
|
|
||
| Per RFC-002 §7.2.1, IAL-1 badges include a 'cnf' (confirmation) claim | ||
| that cryptographically binds the badge to the agent's private key. | ||
| """ | ||
| if self.raw_claims is None: | ||
| return self.ial == "1" | ||
| return "cnf" in self.raw_claims |
There was a problem hiding this comment.
The logic in has_key_binding is inconsistent. When raw_claims is None, it returns True if ial == "1", but when raw_claims exists, it only checks for the presence of "cnf". This means a badge could have ial="1" but no cnf claim in raw_claims, and has_key_binding would return True when raw_claims is None but False when raw_claims exists.
The logic should be consistent: either always check both ial == "1" AND presence of cnf, or trust the ial value alone. Based on RFC-002 §7.2.1, IAL-1 badges MUST have a cnf claim, so the check should verify both conditions together.
| """Check if this badge has IAL-1 key binding (cnf claim). | |
| Per RFC-002 §7.2.1, IAL-1 badges include a 'cnf' (confirmation) claim | |
| that cryptographically binds the badge to the agent's private key. | |
| """ | |
| if self.raw_claims is None: | |
| return self.ial == "1" | |
| return "cnf" in self.raw_claims | |
| """Check if this badge has IAL-1 key binding (ial='1' and cnf claim). | |
| Per RFC-002 §7.2.1, IAL-1 badges MUST include a 'cnf' (confirmation) claim | |
| that cryptographically binds the badge to the agent's private key. | |
| """ | |
| return ( | |
| self.ial == "1" | |
| and self.raw_claims is not None | |
| and "cnf" in self.raw_claims | |
| ) |
- Fix to_dict() to preserve cnf claim for IAL-1 round-trip serialization - Fix has_key_binding to consistently check both ial=='1' AND cnf presence - Document that LEVEL_0 not available via CA request
|
✅ Documentation validation passed!
|
|
✅ All checks passed! Ready for review. |
|
✅ Integration tests passed! Server validation, BadgeKeeper, and gRPC tests all working. |
1 participant
Updates CLI naming references and adds RFC-002 compliance improvements.
Changes
CLI Naming Consolidation
capiscio-clitocapiscioin docsRFC-002 Compliance (from previous commits)
cnfclaim handlingexclude_pathsparameter to FastAPI middlewarehas_key_bindingandconfirmation_keypropertiesBug Fixes (from Copilot Review)
to_dict()to preservecnfclaim for IAL-1 round-trip serializationhas_key_bindingto consistently check bothial=='1'ANDcnfpresenceCleanup