feat: authenticate tool gate deployments - #35
Merged
Conversation
Summary by CodeRabbit
WalkthroughThe change adds freshness-aware HMAC authentication for complete tool-gate deployments. It introduces fingerprints, envelopes, verification, bounded persistence, CLI workflows, authenticated gate and dispatcher binding, schemas, tests, CI smoke coverage, and documentation. ChangesAuthenticated deployment support
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/API.md`:
- Around line 438-443: Update the `authenticate_tool_gate_deployment`
documentation to state that the HMAC-SHA-256 covers the envelope’s
`unsigned_dict()` or all non-MAC fields, rather than every envelope field. Keep
the description consistent with the later `unsigned_dict()` definition.
In `@docs/AUTHENTICATED_DEPLOYMENTS.md`:
- Around line 58-73: Make both documented authentication verification examples
deterministic by adding --at 2026-08-02T12:00:00Z to the verify-authentication
commands in docs/AUTHENTICATED_DEPLOYMENTS.md lines 58-73 and docs/QUICKSTART.md
lines 197-212, matching the envelope’s validity window.
In `@docs/QUICKSTART.md`:
- Line 238: Add the missing `samsarix-ethics schema
tool-gate-deployment-envelope` command to the schema list under “Start a policy
of your own” in the Quickstart, matching the ordering and formatting used by
README.md and docs/POLICY_FORMAT.md.
In `@ROADMAP.md`:
- Around line 86-88: Update the roadmap sentence describing the HMAC envelope to
explicitly identify its authenticated artifact as a complete tool-gate
deployment or ToolGateDeployment, replacing the ambiguous “Single-file
deployments” wording while preserving the remaining caller-owned
responsibilities.
In `@src/samsarix_ethics/authenticated_deployment.py`:
- Line 43: Update the MAC generation and validation pattern around _mac and _MAC
to derive the version and algorithm prefix from
TOOL_GATE_DEPLOYMENT_AUTH_VERSION and _ALGORITHM instead of hardcoding
v1:hmac-sha256. Ensure both emitted MACs and the accepted regular expression
remain synchronized when either constant changes.
- Around line 424-438: Update the authentication flow around the trusted_keys
loop to select envelope.key_id from the raw keyring before validating key
material, so unused malformed entries do not affect verification. Preserve the
key-count bound, validate the selected key ID with _identifier, validate only
its key bytes with _key, and use that validated key for _mac and existing trust
errors.
In `@src/samsarix_ethics/dispatch.py`:
- Around line 164-193: The authenticated identity is discarded after
verification, so bound dispatchers and gates cannot report which envelope
authorized them. Update bind_authenticated_deployment in dispatch.py and
ToolGate.bind_authenticated_deployment in gate.py to retain the complete
VerifiedToolGateDeployment, pass or store it on the resulting object, and expose
it through a read-only property containing key_id, sequence, verified_at, and
deployment_fingerprint while preserving verification before registered_tools
access.
In `@src/samsarix_ethics/provenance.py`:
- Around line 105-112: Update fingerprint_tool_gate_deployment to annotate
deployment as ToolGateDeployment, adding a TYPE_CHECKING-only import while
preserving the existing local runtime import and isinstance validation. Ensure
deferred annotations are enabled as indicated before using the type-only
reference.
In `@src/samsarix_ethics/schema.py`:
- Around line 141-153: The schema definitions for key_id, audience, mac, and
sequence duplicate runtime constraints from authenticated_deployment. Update
schema.py to derive these limits from _IDENTIFIER, _AUDIENCE, _MAC, and
MAX_DEPLOYMENT_AUTH_SEQUENCE, avoiding an import cycle; if direct reuse is not
possible, add a test asserting the schema patterns match the runtime regex
source strings.
In `@tests/test_authenticated_deployment.py`:
- Around line 290-295: Update the isolation assertion in the test around
get_tool_gate_deployment_envelope_schema by mutating the initially returned
schema object directly, then obtain a second schema from the function and assert
its title remains unchanged. Remove the copy import if no other tests in the
file use it.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: a8c1806c-9f62-42b2-8586-02b4e5da29ba
📒 Files selected for processing (25)
.github/workflows/ci.ymlCHANGELOG.mdREADME.mdROADMAP.mdSECURITY.mddocs/ADOPTION.mddocs/API.mddocs/ARCHITECTURE.mddocs/AUTHENTICATED_DEPLOYMENTS.mddocs/POLICY_FORMAT.mddocs/PRODUCTIZATION.mddocs/QUICKSTART.mdexamples/authenticated_deployment_demo.pysrc/samsarix_ethics/__init__.pysrc/samsarix_ethics/authenticated_deployment.pysrc/samsarix_ethics/cli.pysrc/samsarix_ethics/dispatch.pysrc/samsarix_ethics/errors.pysrc/samsarix_ethics/gate.pysrc/samsarix_ethics/io.pysrc/samsarix_ethics/provenance.pysrc/samsarix_ethics/schema.pytests/test_authenticated_deployment.pytests/test_cli.pytests/test_public_api.py
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Why
Tool-gate artifacts already had strict parsing and coherent deployment binding, but operators still needed a dependency-free way to detect tampering and reject stale or incorrectly targeted deployments before executable callbacks are inspected or bound.
Impact
This gives embedded and self-hosted deployments a production-oriented symmetric authentication path while preserving the zero-runtime-dependency package. It is intentionally not a replacement for Sigstore/TUF or other asymmetric public-identity and distribution systems.
Verification