diff --git a/.agents/skills/release-guardian-sdk-packages/SKILL.md b/.agents/skills/release-guardian-sdk-packages/SKILL.md index 2d60cc44c..02b9ffcb1 100644 --- a/.agents/skills/release-guardian-sdk-packages/SKILL.md +++ b/.agents/skills/release-guardian-sdk-packages/SKILL.md @@ -76,6 +76,7 @@ Rust crates: - `guardian-client` - `miden-confidential-contracts` - `miden-multisig-client` +- `guardian-module-sdk` TypeScript packages: @@ -116,6 +117,7 @@ cargo test -p guardian-shared cargo test -p guardian-client cargo test -p miden-confidential-contracts cargo test -p miden-multisig-client +cargo test -p guardian-module-sdk ``` ```bash @@ -151,7 +153,8 @@ cargo publish --dry-run --locked \ -p guardian-shared \ -p guardian-client \ -p miden-confidential-contracts \ - -p miden-multisig-client + -p miden-multisig-client \ + -p guardian-module-sdk ``` ```bash @@ -196,7 +199,7 @@ Workflow: publish-crates.yml Environment: release ``` -Published releases force-select all four crates and use OIDC trusted +Published releases force-select all five crates and use OIDC trusted publishing. Manual runs expose `dry-run` and one boolean per crate. Pull requests changing the workflow force an all-crate credential-free dry run. @@ -207,6 +210,7 @@ publishes dependency-safe topological batches: 2. `guardian-client` 3. `miden-confidential-contracts` 4. `miden-multisig-client` +5. `guardian-module-sdk` (no internal dependencies) Exact versions already on crates.io are skipped. The selected packages are passed to one native multi-package Cargo command, which owns dependency @@ -216,6 +220,13 @@ its unselected prerequisites are already available at the coordinated version. Trusted-publishing failure must fail closed. The workflow has no long-lived registry-token fallback. +`guardian-module-sdk` is new in the M2a release (0.19). crates.io accepts a +trusted publisher only for a crate that already exists, so before the first +release that includes it, a crate owner publishes it once by hand +(`cargo publish -p guardian-module-sdk` with a personal token) and then adds the +trusted-publisher entry above. Until then a release run fails when it reaches +`guardian-module-sdk`; ask the user to do this step before cutting the release. + ## TypeScript Publish Order TypeScript packages must be published in dependency order: @@ -236,7 +247,7 @@ The user should usually only need to handle: - cutting the GitHub Release (`gh release create`), which also triggers the server image build For a normal Rust release, do not request `cargo login` or a local crates.io -token. Verify the four external trusted-publisher entries and use: +token. Verify the five external trusted-publisher entries and use: ```bash gh workflow run publish-crates.yml \ @@ -245,7 +256,8 @@ gh workflow run publish-crates.yml \ -f guardian-shared=true \ -f guardian-client=true \ -f miden-confidential-contracts=true \ - -f miden-multisig-client=true + -f miden-multisig-client=true \ + -f guardian-module-sdk=true ``` Continue TypeScript authentication checks with `npm whoami || npm login`. diff --git a/.agents/skills/release-guardian-sdk-packages/references/release-surface.md b/.agents/skills/release-guardian-sdk-packages/references/release-surface.md index 853ed60f3..b34093439 100644 --- a/.agents/skills/release-guardian-sdk-packages/references/release-surface.md +++ b/.agents/skills/release-guardian-sdk-packages/references/release-surface.md @@ -16,6 +16,9 @@ Current coordinated SDK release line: `0.16.x` 4. `miden-multisig-client` - manifest: `crates/miden-multisig-client/Cargo.toml` - internal release dependencies: `guardian-client`, `guardian-shared`, `miden-confidential-contracts` +5. `guardian-module-sdk` + - manifest: `crates/guardian-module-sdk/Cargo.toml` + - no internal release dependencies; first publish is manual (see SKILL.md, "Rust Publication Workflow") ## Publishable TypeScript Packages @@ -57,7 +60,7 @@ Stable workflow: .github/workflows/publish-crates.yml ``` -Published releases select all four Rust crates. Manual runs provide `dry-run`, +Published releases select all five Rust crates. Manual runs provide `dry-run`, and one boolean per crate. Pull requests changing the workflow run an all-crate dry run without credentials. @@ -67,6 +70,7 @@ The fixed selection and summary order is: 2. `guardian-client` 3. `miden-confidential-contracts` 4. `miden-multisig-client` +5. `guardian-module-sdk` Cargo receives selected crates in one multi-package command and owns dependency ordering. Actual runs skip exact versions already visible on crates.io. diff --git a/.agents/skills/smoke-test-operator-dashboard/SKILL.md b/.agents/skills/smoke-test-operator-dashboard/SKILL.md index b1283e5f2..b8efc0b36 100644 --- a/.agents/skills/smoke-test-operator-dashboard/SKILL.md +++ b/.agents/skills/smoke-test-operator-dashboard/SKILL.md @@ -1,6 +1,6 @@ --- name: smoke-test-operator-dashboard -description: Run or guide manual smoke testing of Guardian operator dashboard auth and account APIs through `examples/operator-smoke-web` and `@openzeppelin/guardian-operator-client`. Use when Codex needs to verify operator challenge signing, session login, logout, account listing, account detail, local signer behavior, local or remote Guardian targets, or workspace versus published operator client package behavior. +description: Run or guide manual smoke testing of Guardian operator dashboard auth and account APIs through `examples/operator-smoke-web` and `@openzeppelin/guardian-operator-client`. Use when Codex needs to verify operator challenge signing, session login, logout, account listing, account detail, local signer behavior, policy module catalog, params history and writes, local or remote Guardian targets, or workspace versus published operator client package behavior. --- # Smoke Test Operator Dashboard @@ -118,6 +118,10 @@ Set `HEADLESS=false` to watch the browser. Set `CHROME_EXECUTABLE` if Chrome is Use `GUARDIAN_URL=http://127.0.0.1:3000` for local runs. For deployed runs, use the deployed Guardian URL. +## Policy Modules Panel + +The `Policy modules` panel covers the module operator endpoints: the catalog (instances, `catalogHash`, `paramsVersion`, enable and disable), the params history paged with `before`, an account's modules with `accountParamsVersion`, and the writes (global params, account layer set or clear, assignment replace). Start Guardian with a catalog and the allowlist permissions as described in `examples/operator-smoke-web/README.md` ("Policy modules panel"). Check that each write shows up in the params history and that a write without its permission surfaces `HTTP 403 [insufficient_operator_permission]`. The automated script does not drive this panel. + ## Assertions - The configured operator public key derives to the active local signer commitment in the UI. diff --git a/.agents/skills/verify-auth-replay/fingerprints.txt b/.agents/skills/verify-auth-replay/fingerprints.txt index 8a218b436..1c5bd6a3d 100644 --- a/.agents/skills/verify-auth-replay/fingerprints.txt +++ b/.agents/skills/verify-auth-replay/fingerprints.txt @@ -6,7 +6,7 @@ crates/server/src/services/mod.rs resolve_account_with_head 92e4ff1e6a5c227a crates/server/src/services/mod.rs verify_session_request a4caa18e7b49c424 crates/server/src/services/mod.rs validate_request_timestamp 56ff32640a697109 crates/server/src/services/mod.rs consume_auth_timestamp 3dd46e9a0fddb6f0 -crates/server/src/services/configure_account.rs configure_account abe544c0e5c82187 +crates/server/src/services/configure_account.rs configure_account e73a3f93d6de6602 crates/server/src/session.rs stale_floor_age_ms 83c6a11eea648b32 crates/server/src/session.rs replay_floor_key e6371be262401f43 crates/server/src/session.rs find 34aa53044b39192d diff --git a/.agents/skills/verify-candidate-queue/fingerprints.txt b/.agents/skills/verify-candidate-queue/fingerprints.txt index 7d5236972..0048617f5 100644 --- a/.agents/skills/verify-candidate-queue/fingerprints.txt +++ b/.agents/skills/verify-candidate-queue/fingerprints.txt @@ -41,7 +41,7 @@ crates/server/src/jobs/canonicalization/reconciliation.rs select_recoverable_pat crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_recoverable_path 29ec5c6d03466450 crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_account 7bcb69472529ff03 crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_chain_advance a9652aaef66374ce -crates/server/src/services/push_delta.rs push_delta fa1ae5be30b44406 +crates/server/src/services/push_delta.rs push_delta 2235a925f1f0ec48 crates/server/src/jobs/canonicalization/processor.rs process_full_pass d5bf1e79a30da8da crates/server/src/jobs/canonicalization/processor.rs process_recent_pass 596742f4f9ea8593 crates/server/src/storage/postgres.rs lease_fence_is_current 951aa94931bd4c54 diff --git a/.agents/skills/verify-client-sync/SKILL.md b/.agents/skills/verify-client-sync/SKILL.md index 85b6e0efb..f9075b60e 100644 --- a/.agents/skills/verify-client-sync/SKILL.md +++ b/.agents/skills/verify-client-sync/SKILL.md @@ -114,7 +114,7 @@ enough, because the undo of a dropped transaction leaves the cache on the dropped config. Fix: every proposal creator (`createProposal` and each `create*Proposal` -method), `signProposal`, `signProposalOffline`, `importProposal`, +method, in the `draft*` step that `checkTransaction` shares), `signProposal`, `signProposalOffline`, `importProposal`, `syncProposals` (`reconcileProposals`), `submitTransaction` and `registerOnGuardian` re-read the store (`refreshConfigFromStore`), and `prepareProposalExecution` and `prepareCustomExecution` refresh the config diff --git a/.agents/skills/verify-client-sync/fingerprints.txt b/.agents/skills/verify-client-sync/fingerprints.txt index 9f38ceff1..06c5069b7 100644 --- a/.agents/skills/verify-client-sync/fingerprints.txt +++ b/.agents/skills/verify-client-sync/fingerprints.txt @@ -14,7 +14,7 @@ crates/miden-multisig-client/src/client/account.rs refresh_cached_account_from_s crates/miden-multisig-client/src/client/helpers.rs finalize_transaction dcd71a15af86617f crates/miden-multisig-client/src/client/helpers.rs rebuilds_local_state_from_delta e505dcca5111be28 crates/miden-multisig-client/src/client/helpers.rs submit_transaction_at_tip 868a7b51b15f9fa7 -crates/miden-multisig-client/src/client/helpers.rs get_guardian_ack_signature c95d133cba082b6a +crates/miden-multisig-client/src/client/helpers.rs get_guardian_ack_signature 6724b8a80e8bcc59 crates/miden-multisig-client/src/client/proposals.rs execute_proposal 0ae7632c3d6f2cd7 crates/miden-multisig-client/src/client/proposals.rs propose_transaction_with_options 076e1703b567767d crates/miden-multisig-client/src/client/offline.rs execute_imported_proposal 371832148205f50f @@ -24,20 +24,20 @@ packages/miden-multisig-client/src/multisig.ts refreshConfigFromAccount 960b5894 packages/miden-multisig-client/src/multisig.ts refreshConfigFromStore 514a0e803597e19b packages/miden-multisig-client/src/multisig.ts adoptConfigFromAccount 7ce5bc7d73495198 packages/miden-multisig-client/src/multisig.ts assertExecutesOnPinnedBase 097642d2f57cf0d6 -packages/miden-multisig-client/src/multisig.ts createAddSignerProposal 2fba4bc0d2ef8dd3 -packages/miden-multisig-client/src/multisig.ts createRemoveSignerProposal bdcf2852adee2d9a +packages/miden-multisig-client/src/multisig.ts draftAddSigner 9e48a458129fd09a +packages/miden-multisig-client/src/multisig.ts draftRemoveSigner db1fdf0aeb4db964 packages/miden-multisig-client/src/multisig.ts registerOnGuardian 4f1ed89a94dabbac packages/miden-multisig-client/src/multisig.ts executeProposal 63330ec3cb16bd47 packages/miden-multisig-client/src/multisig.ts prepareProposalExecution 244406c248b93c2e packages/miden-multisig-client/src/multisig.ts prepareCustomExecution 17c6ba0b0cb35230 -packages/miden-multisig-client/src/multisig.ts createSwitchGuardianProposal 65aa2a689bc46575 +packages/miden-multisig-client/src/multisig.ts createSwitchGuardianProposal 7d2db7da11fbd4ca packages/miden-multisig-client/src/multisig.ts signProposalOffline dc7f1cad8efed3a9 packages/miden-multisig-client/src/multisig.ts signProposal 008039ab6b8a856a packages/miden-multisig-client/src/multisig.ts importProposal e720dac9240c2c33 packages/miden-multisig-client/src/multisig.ts reconcileProposals aa7962d87eff3c9d packages/miden-multisig-client/src/multisig.ts resolveProposalNonce 7c25a02c067fe164 -packages/miden-multisig-client/src/multisig.ts createProposal 37ded4b3a399c755 -packages/miden-multisig-client/src/multisig.ts pushProposal aee5cf33cb4d0bb9 +packages/miden-multisig-client/src/multisig.ts createProposal 026497a52ca78e34 +packages/miden-multisig-client/src/multisig.ts pushDraft d422be3e5043e0f6 packages/miden-multisig-client/src/multisig.ts submitTransaction 9e4761cb3a1172b1 packages/miden-multisig-client/src/state/adopt.ts isSafeToAdoptGuardianState d30804918814dff2 packages/miden-multisig-client/src/prover/workflow.ts submit 34c1dded2dedbc5c diff --git a/.agents/skills/verify-client-sync/mirrored.txt b/.agents/skills/verify-client-sync/mirrored.txt index bdc66dbbc..53f320ad1 100644 --- a/.agents/skills/verify-client-sync/mirrored.txt +++ b/.agents/skills/verify-client-sync/mirrored.txt @@ -25,8 +25,8 @@ packages/miden-multisig-client/src/multisig.ts refreshConfigFromAccount packages/miden-multisig-client/src/multisig.ts refreshConfigFromStore packages/miden-multisig-client/src/multisig.ts adoptConfigFromAccount packages/miden-multisig-client/src/multisig.ts assertExecutesOnPinnedBase -packages/miden-multisig-client/src/multisig.ts createAddSignerProposal -packages/miden-multisig-client/src/multisig.ts createRemoveSignerProposal +packages/miden-multisig-client/src/multisig.ts draftAddSigner +packages/miden-multisig-client/src/multisig.ts draftRemoveSigner packages/miden-multisig-client/src/multisig.ts registerOnGuardian packages/miden-multisig-client/src/multisig.ts executeProposal packages/miden-multisig-client/src/multisig.ts prepareProposalExecution @@ -38,7 +38,7 @@ packages/miden-multisig-client/src/multisig.ts importProposal packages/miden-multisig-client/src/multisig.ts reconcileProposals packages/miden-multisig-client/src/multisig.ts resolveProposalNonce packages/miden-multisig-client/src/multisig.ts createProposal -packages/miden-multisig-client/src/multisig.ts pushProposal +packages/miden-multisig-client/src/multisig.ts pushDraft packages/miden-multisig-client/src/multisig.ts submitTransaction packages/miden-multisig-client/src/state/adopt.ts isSafeToAdoptGuardianState packages/miden-multisig-client/src/prover/workflow.ts submit diff --git a/.agents/skills/verify-guardian-execution/fingerprints.txt b/.agents/skills/verify-guardian-execution/fingerprints.txt index ba48745d3..36d8011f9 100644 --- a/.agents/skills/verify-guardian-execution/fingerprints.txt +++ b/.agents/skills/verify-guardian-execution/fingerprints.txt @@ -1,4 +1,4 @@ -crates/server/src/services/execute_proposal/service.rs request_execution b88bdbd142020ba3 +crates/server/src/services/execute_proposal/service.rs request_execution 7c91c303b38232b0 crates/server/src/services/execute_proposal/worker.rs run_execution e7c8bb2181f51ea7 crates/server/src/services/execute_proposal/worker.rs run_to_boundary 8bef28647e656733 crates/server/src/services/execute_proposal/worker.rs approach_boundary a248e9dcb6395278 @@ -8,9 +8,9 @@ crates/server/src/services/execute_proposal/worker.rs advance bc3e2bddd7da680a crates/server/src/services/execute_proposal/worker.rs cross_boundary b58bff42ad1c5ea8 crates/server/src/services/execute_proposal/worker.rs claim_send d18c0a5a097fad39 crates/server/src/services/execute_proposal/worker.rs submit 616fae8fe329d651 -crates/server/src/services/execute_proposal/worker.rs fail 401af65c37945fa8 +crates/server/src/services/execute_proposal/worker.rs fail 36ad82b5368c5b1d crates/server/src/network/miden/execution/attempt.rs classify_submission_error 79c4779dd0bda7d6 -crates/shared/src/execution.rs ends_proposal eda192d5bc234edd +crates/shared/src/execution.rs ends_proposal b2abc6ad39edf8e6 crates/server/src/coordination/execution_leases.rs attempt 7c6506df2503b815 crates/server/src/coordination/execution_leases.rs release_quietly 44f6e42959e727ba crates/server/src/coordination/postgres/lease.rs try_acquire acd5be995d0ebf4f @@ -58,7 +58,7 @@ crates/server/src/storage/postgres.rs restore_superseded 5ae2a5e38baf32e6 crates/server/src/storage/postgres.rs pull_superseded_deltas 8f6ec1bf593e02e2 crates/server/src/builder/canonicalization.rs archives_superseded f304c6a39fa148b0 crates/server/src/jobs/execution_reconcile/mod.rs pass 56d789d1e89af925 -crates/server/src/jobs/execution_reconcile/mod.rs reconcile af57fca9f7d1e5e1 +crates/server/src/jobs/execution_reconcile/mod.rs reconcile c4c903cf181b721b crates/server/src/jobs/execution_reconcile/mod.rs take_ownership 5bebe04bb18a13b9 crates/server/src/jobs/execution_reconcile/mod.rs observe 4673e188710dde56 crates/server/src/jobs/execution_reconcile/mod.rs moved_on e7f1420c943edaf0 diff --git a/.agents/skills/verify-guardian-switch/fingerprints.txt b/.agents/skills/verify-guardian-switch/fingerprints.txt index 5c7cd05cf..312985cfa 100644 --- a/.agents/skills/verify-guardian-switch/fingerprints.txt +++ b/.agents/skills/verify-guardian-switch/fingerprints.txt @@ -1,10 +1,11 @@ crates/server/src/services/release_on_switch.rs release_if_guardian_switched 58154d671cc4879b crates/server/src/services/release_on_switch.rs release_switched_account 0a8d56a29871f92b crates/server/src/services/account_status.rs ensure_account_active_metadata b7303e5276ca4f67 -crates/server/src/services/push_delta.rs push_delta fa1ae5be30b44406 -crates/server/src/services/push_delta.rs run 17815b0a4b4255f3 -crates/server/src/services/push_delta_proposal.rs push_delta_proposal be040d9f4d82f318 -crates/server/src/services/configure_account.rs configure_account abe544c0e5c82187 +crates/server/src/services/push_delta.rs push_delta 2235a925f1f0ec48 +crates/server/src/services/push_delta.rs run 2e2b1383e17e1567 +crates/server/src/services/push_delta_proposal.rs push_delta_proposal f3273779e9d7758f +crates/server/src/services/push_delta_proposal.rs propose 14df5417579e6b57 +crates/server/src/services/configure_account.rs configure_account e73a3f93d6de6602 crates/server/src/services/configure_account.rs stored_state_landed f1082399d583be3f crates/server/src/services/configure_account.rs stored_head 641128d1cfa79677 crates/server/src/services/pause_account.rs pause 7a8b3686c25b35b2 diff --git a/.agents/skills/verify-guardian-switch/mirrored.txt b/.agents/skills/verify-guardian-switch/mirrored.txt index a0a4174cb..d6dc551a5 100644 --- a/.agents/skills/verify-guardian-switch/mirrored.txt +++ b/.agents/skills/verify-guardian-switch/mirrored.txt @@ -5,6 +5,7 @@ crates/server/src/services/account_status.rs ensure_account_active_metadata crates/server/src/services/push_delta.rs push_delta crates/server/src/services/push_delta.rs run crates/server/src/services/push_delta_proposal.rs push_delta_proposal +crates/server/src/services/push_delta_proposal.rs propose crates/server/src/services/configure_account.rs configure_account crates/server/src/services/configure_account.rs stored_state_landed crates/server/src/services/configure_account.rs stored_head diff --git a/.agents/skills/verify-multisig-push-gate/fingerprints.txt b/.agents/skills/verify-multisig-push-gate/fingerprints.txt index a714f6cec..f350c7b67 100644 --- a/.agents/skills/verify-multisig-push-gate/fingerprints.txt +++ b/.agents/skills/verify-multisig-push-gate/fingerprints.txt @@ -3,8 +3,8 @@ crates/server/src/services/multisig_admission.rs signature_floor 17e83d08e3b9b2b crates/server/src/services/multisig_admission.rs pending_signatures aaf000190ef8e292 crates/server/src/services/multisig_admission.rs verified_approver_count bdab3f16b0e99ab6 Cargo.lock @pin miden-standards 0.17.1 -crates/server/src/services/push_delta.rs push_delta fa1ae5be30b44406 -crates/server/src/services/push_delta.rs run 17815b0a4b4255f3 +crates/server/src/services/push_delta.rs push_delta 2235a925f1f0ec48 +crates/server/src/services/push_delta.rs run 2e2b1383e17e1567 crates/server/src/services/ack_delta_internal.rs lookup_matching_proposal 9b5ac8501f9abe75 crates/server/src/services/candidate_chain.rs ensure_tail_keeps_auth cba3037b83a609b8 crates/server/src/services/sign_delta_proposal.rs sign_delta_proposal 7f42c80cb717ed45 diff --git a/.agents/skills/verify-proposal-lifecycle/fingerprints.txt b/.agents/skills/verify-proposal-lifecycle/fingerprints.txt index 72e78d2b8..93ad36633 100644 --- a/.agents/skills/verify-proposal-lifecycle/fingerprints.txt +++ b/.agents/skills/verify-proposal-lifecycle/fingerprints.txt @@ -1,6 +1,7 @@ -crates/server/src/services/push_delta_proposal.rs push_delta_proposal be040d9f4d82f318 -crates/server/src/services/push_delta.rs push_delta fa1ae5be30b44406 -crates/server/src/services/ack_delta_internal.rs lookup_matching_proposal 9b5ac8501f9abe75 +crates/server/src/services/push_delta_proposal.rs push_delta_proposal f3273779e9d7758f +crates/server/src/services/push_delta_proposal.rs propose 14df5417579e6b57 +crates/server/src/services/push_delta.rs push_delta 2235a925f1f0ec48 +crates/server/src/services/ack_delta_internal.rs lookup_matching_proposal 67134b6f856c4c3f crates/server/src/services/candidate_chain.rs load_for_admission ed7abd9edcc81e9f crates/server/src/services/candidate_chain.rs tail_commitment 5c8c7de27c6e876e crates/server/src/storage/mod.rs gate_candidate_submission 99785be2d52ca367 @@ -19,7 +20,7 @@ crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_chain_advanc crates/miden-multisig-client/src/client/proposals.rs execute_proposal 0ae7632c3d6f2cd7 crates/miden-multisig-client/src/client/proposals.rs get_proposal 76e303a6b0a9430d crates/miden-multisig-client/src/client/proposals.rs propose_transaction_with_options 076e1703b567767d -crates/miden-multisig-client/src/client/helpers.rs get_guardian_ack_signature c95d133cba082b6a +crates/miden-multisig-client/src/client/helpers.rs get_guardian_ack_signature 6724b8a80e8bcc59 crates/miden-multisig-client/src/client/account.rs sync d1377d59279df94d packages/miden-multisig-client/src/multisig.ts resolveProposalNonce 7c25a02c067fe164 packages/miden-multisig-client/src/multisig.ts assertExecutesOnPinnedBase c7fa8b8f1b53cacb diff --git a/.agents/skills/verify-proposal-lifecycle/mirrored.txt b/.agents/skills/verify-proposal-lifecycle/mirrored.txt index 54d4a22ab..2d76ca25f 100644 --- a/.agents/skills/verify-proposal-lifecycle/mirrored.txt +++ b/.agents/skills/verify-proposal-lifecycle/mirrored.txt @@ -1,5 +1,6 @@ # Rust and TypeScript functions modeled in model/ProposalLifecycle.tla: " ". crates/server/src/services/push_delta_proposal.rs push_delta_proposal +crates/server/src/services/push_delta_proposal.rs propose crates/server/src/services/push_delta.rs push_delta crates/server/src/services/ack_delta_internal.rs lookup_matching_proposal crates/server/src/services/candidate_chain.rs load_for_admission diff --git a/.github/workflows/custom-guardian-template.yml b/.github/workflows/custom-guardian-template.yml new file mode 100644 index 000000000..a209bc6f2 --- /dev/null +++ b/.github/workflows/custom-guardian-template.yml @@ -0,0 +1,76 @@ +--- +# Attaches the custom-guardian template to a release: examples/custom-guardian as a standalone +# project that depends on the Guardian crates at the release tag and carries the release's +# Cargo.lock (RFC 0002, section 2.5). The template's Docker image is built with --locked before +# the archive is uploaded, so a template that does not build is never published. + +name: Custom Guardian Template + +on: + release: + types: [published] + workflow_dispatch: + inputs: + tag: + description: "Release tag to build the template for, e.g. v0.19.0" + type: string + required: true + +permissions: + contents: read + +concurrency: + group: custom-guardian-template-${{ github.event.release.tag_name || inputs.tag }} + cancel-in-progress: false + +jobs: + template: + name: Build and attach the template + runs-on: ubuntu-latest + if: github.repository_owner == 'OpenZeppelin' + timeout-minutes: 90 + permissions: + contents: write + env: + TAG: ${{ github.event.release.tag_name || inputs.tag }} + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4 + with: + egress-policy: audit + + - name: Check the release tag + env: + GH_TOKEN: ${{ github.token }} + run: | + [[ "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || { + echo "::error::${TAG} is not a release tag (vMAJOR.MINOR.PATCH[-PRERELEASE])" + exit 1 + } + gh release view "${TAG}" --repo "${GITHUB_REPOSITORY}" > /dev/null + + - name: Check out the release + uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0 + with: + ref: ${{ env.TAG }} + persist-credentials: false + + - name: Set up Rust + uses: dtolnay/rust-toolchain@351f82a4dc29e4159746a068ed925da17341219f # 1.89.0 + with: + toolchain: 1.98.1 + + - name: Build the template + run: scripts/custom-guardian-template.sh --tag "${TAG}" --out "${RUNNER_TEMP}/custom-guardian" + + - name: Build the template image + working-directory: ${{ runner.temp }}/custom-guardian + run: docker build -t custom-guardian-template-check . + + - name: Attach the template to the release + env: + GH_TOKEN: ${{ github.token }} + run: | + archive="${RUNNER_TEMP}/custom-guardian-${TAG}.tar.gz" + tar -C "${RUNNER_TEMP}" -czf "${archive}" custom-guardian + gh release upload "${TAG}" "${archive}" --clobber --repo "${GITHUB_REPOSITORY}" diff --git a/.github/workflows/publish-crates.yml b/.github/workflows/publish-crates.yml index 1ef1e02b8..c7e30ff59 100644 --- a/.github/workflows/publish-crates.yml +++ b/.github/workflows/publish-crates.yml @@ -30,6 +30,11 @@ on: type: boolean required: false default: false + guardian-module-sdk: + description: "Select guardian-module-sdk" + type: boolean + required: false + default: false pull_request: paths: - ".github/workflows/publish-crates.yml" @@ -61,6 +66,7 @@ jobs: INPUT_GUARDIAN_SHARED: ${{ inputs['guardian-shared'] }} INPUT_CONTRACTS: ${{ inputs['miden-confidential-contracts'] }} INPUT_MULTISIG: ${{ inputs['miden-multisig-client'] }} + INPUT_MODULE_SDK: ${{ inputs['guardian-module-sdk'] }} RELEASE_TAG: ${{ github.event.release.tag_name }} SOURCE_REF: ${{ github.ref }} SOURCE_SHA: ${{ github.sha }} @@ -71,6 +77,7 @@ jobs: guardian-client miden-confidential-contracts miden-multisig-client + guardian-module-sdk ) selected=() @@ -94,6 +101,7 @@ jobs: [[ "${INPUT_GUARDIAN_CLIENT}" == "true" ]] && selected+=(guardian-client) [[ "${INPUT_CONTRACTS}" == "true" ]] && selected+=(miden-confidential-contracts) [[ "${INPUT_MULTISIG}" == "true" ]] && selected+=(miden-multisig-client) + [[ "${INPUT_MODULE_SDK}" == "true" ]] && selected+=(guardian-module-sdk) if [[ "${INPUT_DRY_RUN}" == "true" ]]; then mode=dry_run else @@ -176,6 +184,7 @@ jobs: guardian-client miden-confidential-contracts miden-multisig-client + guardian-module-sdk ) version= for crate in "${crates[@]}"; do diff --git a/AGENTS.md b/AGENTS.md index df75f5581..b75b27f86 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,6 +34,7 @@ If a behavior changes in a lower layer, verify and propagate impact upward acros - `crates/miden-multisig-client`: Rust multisig SDK on top of Miden + GUARDIAN - `packages/miden-multisig-client`: TS multisig SDK on top of Miden + GUARDIAN - `crates/shared`: shared Rust primitives/utilities +- `crates/guardian-module-sdk`: policy module SDK (published): the `guardian.module.v1` protocol, the `Module` trait, the `serve` gRPC harness, the conformance kit and the first-party policy kinds - `crates/qualification-driver`: Rust driver for the black-box qualification suite (not published; also the scenario-manifest validator both drivers read) - `qualification/`: scenario manifest, Compose stack and shell harness for the qualification suite (see `docs/QUALIFICATION.md`) - `spec/`: system and protocol-level behavior docs @@ -226,8 +227,9 @@ Common mappings: - Server or API behavior -> `spec/`, `docs/CONCEPTS.md`, SDK docs - Multisig SDK behavior -> `docs/MULTISIG_SDK.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md`, `examples/demo`, `examples/web`, `examples/smoke-web` - Miden version support, cross-line breaking changes, data resets -> `docs/MIDEN_COMPATIBILITY.md` (facts live there; `docs/PRODUCTION.md` keeps operator steps and `docs/TROUBLESHOOTING.md` keeps symptoms) -- New or changed public API, builder option, or config field on a published crate or package -> that crate's or package's own `README.md`, in the same PR. These READMEs are the crates.io and npm landing pages, so a field documented only in `docs/` is invisible to every consumer who never opens the repo. Published surfaces: `crates/shared`, `crates/client`, `crates/contracts`, `crates/miden-multisig-client`, `packages/guardian-client`, `packages/guardian-evm-client`, `packages/guardian-operator-client`, `packages/miden-multisig-client`. Keep relative links out of npm READMEs; they resolve only on GitHub. +- New or changed public API, builder option, or config field on a published crate or package -> that crate's or package's own `README.md`, in the same PR. These READMEs are the crates.io and npm landing pages, so a field documented only in `docs/` is invisible to every consumer who never opens the repo. Published surfaces: `crates/shared`, `crates/client`, `crates/contracts`, `crates/guardian-module-sdk`, `crates/miden-multisig-client`, `packages/guardian-client`, `packages/guardian-evm-client`, `packages/guardian-operator-client`, `packages/miden-multisig-client`. Keep relative links out of npm READMEs; they resolve only on GitHub. - Operator/dashboard behavior -> `docs/DASHBOARD.md`, `docs/PRODUCTION.md`, `examples/operator-smoke-web` +- Policy modules (catalog, pipeline, operator module routes, module protocol) -> `docs/guides/policy-modules/`, `docs/runbooks/policy-modules.md`, `docs/rfcs/0002-guardian-modules.md`, `crates/guardian-module-sdk/README.md`, `docs/DASHBOARD.md` - EVM proposal behavior -> `speckit/features/001-evm-proposal-support/`, `packages/guardian-evm-client`, `examples/evm-smoke-web` - Deployment, config, infrastructure, or secrets -> `docs/PRODUCTION.md`, `docs/architecture/infra.md`, `docs/runbooks/secrets.md`, `docs/SERVER_AWS_DEPLOY.md`, `infra/README.md` - Local dev or test startup -> `README.md`, `CONTRIBUTING.md`, relevant example README or quickstart diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34fe581bc..6d34b3ca8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,6 +180,7 @@ If your change is user- or operator-visible, update the matching doc: | Published Docker image / publish workflow | [`docs/SERVER_AWS_DEPLOY.md`](./docs/SERVER_AWS_DEPLOY.md) ("Published Docker images"); image at `ghcr.io/openzeppelin/guardian` | | Wire contract changes | [`spec/api.md`](./spec/api.md), [`spec/processes.md`](./spec/processes.md) | | New SDK feature | [`docs/MULTISIG_SDK.md`](./docs/MULTISIG_SDK.md) where relevant | +| Policy modules (catalog, pipeline, operator module routes, module protocol) | [`docs/guides/policy-modules/`](./docs/guides/policy-modules/README.md), [`docs/runbooks/policy-modules.md`](./docs/runbooks/policy-modules.md), [RFC 0002](./docs/rfcs/0002-guardian-modules.md), [`crates/guardian-module-sdk/README.md`](./crates/guardian-module-sdk/README.md) | | Miden version bump, cross-line breaking change, or data reset | [`docs/MIDEN_COMPATIBILITY.md`](./docs/MIDEN_COMPATIBILITY.md), plus the package READMEs' compatibility tables | | New public API, builder option, or config field on a published crate or package | That crate's or package's own `README.md`, in the same PR. It is the crates.io / npm landing page, so `docs/` alone leaves it invisible to consumers. | | Qualification scenarios, the coverage matrix, or the treasury runbook | [`docs/QUALIFICATION.md`](./docs/QUALIFICATION.md); scenario sources live in `qualification/manifest/` and `manifest.json` must be regenerated | diff --git a/Cargo.lock b/Cargo.lock index ac8e2b618..6ad11fa35 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2483,6 +2483,19 @@ dependencies = [ "syn 2.0.119", ] +[[package]] +name = "custom-guardian" +version = "0.1.0" +dependencies = [ + "async-trait", + "dotenvy", + "guardian-module-sdk", + "guardian-server", + "serde", + "serde_json", + "tokio", +] + [[package]] name = "darling" version = "0.20.11" @@ -3496,6 +3509,17 @@ dependencies = [ "tonic-prost-build", ] +[[package]] +name = "guardian-compliance-module" +version = "0.1.0" +dependencies = [ + "guardian-module-sdk", + "serde", + "serde_json", + "tokio", + "tonic", +] + [[package]] name = "guardian-demo" version = "0.1.0" @@ -3510,6 +3534,34 @@ dependencies = [ "tokio", ] +[[package]] +name = "guardian-module-sdk" +version = "0.19.0-rc.2" +dependencies = [ + "async-trait", + "bech32", + "guardian-module-sdk", + "prost", + "prost-types", + "secrecy", + "serde", + "serde_json", + "thiserror 2.0.19", + "tokio", + "tonic", + "tonic-prost", + "tonic-prost-build", +] + +[[package]] +name = "guardian-policy-module" +version = "0.1.0" +dependencies = [ + "guardian-module-sdk", + "tokio", + "tonic", +] + [[package]] name = "guardian-prod-benchmarks" version = "0.1.0" @@ -3540,6 +3592,7 @@ dependencies = [ "chrono", "clap", "guardian-client", + "guardian-module-sdk", "guardian-shared", "hex", "libc", @@ -3556,6 +3609,7 @@ dependencies = [ "thiserror 2.0.19", "tokio", "toml 0.8.23", + "tonic", ] [[package]] @@ -3601,6 +3655,7 @@ dependencies = [ "dotenvy", "futures", "futures-util", + "guardian-module-sdk", "guardian-shared", "hex", "hmac 0.12.1", @@ -3626,6 +3681,7 @@ dependencies = [ "rand 0.10.2", "rand_chacha 0.10.0", "rcgen", + "reqwest 0.12.28", "rustls 0.23.46", "rustls-pemfile", "secrecy", @@ -3641,6 +3697,7 @@ dependencies = [ "tokio-postgres", "tokio-postgres-rustls", "tokio-util", + "toml 0.8.23", "tonic", "tonic-prost", "tonic-prost-build", diff --git a/Cargo.toml b/Cargo.toml index 48a877d6c..609b3070e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,10 +8,14 @@ members = [ "crates/miden-rpc-client", "crates/miden-keystore", "crates/contracts", + "crates/guardian-module-sdk", "crates/miden-multisig-client", "crates/qualification-driver", "examples/rust", "examples/demo", + "examples/policy-module", + "examples/compliance-module", + "examples/custom-guardian", ] default-members = [ "crates/shared", @@ -20,6 +24,7 @@ default-members = [ "crates/miden-rpc-client", "crates/miden-keystore", "crates/contracts", + "crates/guardian-module-sdk", "crates/miden-multisig-client", ] resolver = "2" diff --git a/crates/client/README.md b/crates/client/README.md index dee7f0f44..f2cc1951d 100644 --- a/crates/client/README.md +++ b/crates/client/README.md @@ -169,6 +169,30 @@ A refusal is a `ClientError` whose `guardian_code()` is the wire code (for examp `wait_for_guardian_execution` with backoff, retries and a deadline; see [`docs/MULTISIG_SDK.md`](../../docs/MULTISIG_SDK.md#guardian-execution). +### Policy Modules + +`get_policies` lists the rules the Guardian discloses for an account, and +`check_delta_proposal` runs the policy modules on a proposal without storing +it. A request a module refuses fails with a `ClientError` whose +`module_refusal()` returns `ModuleRefusal::Denied { module, reason_code, layer, +client_message }` (final; a generic denial carries only `policy_denied`) or +`ModuleRefusal::Unavailable { module }` (retryable; `module` is `None` for an +instance with generic denials). A Guardian execution a +module refuses ends failed with `ExecutionFailureCode::ModuleDenied(ModuleDenial)` +or `ExecutionFailureCode::ModuleUnavailable { module }`, and its proposal is +kept: + +```rust +match client.push_delta_proposal(&account_id, nonce, payload).await { + Err(error) => match error.module_refusal() { + Some(ModuleRefusal::Denied { reason_code, .. }) => { /* final */ } + Some(ModuleRefusal::Unavailable { .. }) => { /* retry later */ } + None => { /* any other error */ } + }, + Ok(response) => { /* stored */ } +} +``` + ### Rate Limits and Retries The server rate-limits both its gRPC and HTTP surfaces. The sustained diff --git a/crates/client/proto/guardian.proto b/crates/client/proto/guardian.proto index c8d31f264..b5a2a5b1c 100644 --- a/crates/client/proto/guardian.proto +++ b/crates/client/proto/guardian.proto @@ -87,6 +87,17 @@ service Guardian { // x-timestamp), raw or as EIP-712 typed data (`x-auth-format: eip712`). // Wallet-only. Mirror of HTTP POST /session/revoke-all. rpc RevokeAllSessions(RevokeAllSessionsRequest) returns (RevokeAllSessionsResponse); + + // The policy modules that apply to the account, as far as each instance's + // catalog entry discloses them (RFC 0002 section 2.7). Mirror of HTTP + // GET /policies. + rpc GetPolicies(GetPoliciesRequest) returns (GetPoliciesResponse); + + // Dry run of PushDeltaProposal: the same checks and proposal-creation + // modules, nothing stored, no proposal slot taken. Advisory; approval still + // decides. Rate limited per account and signer. Mirror of HTTP + // POST /delta/proposal/check. + rpc CheckDeltaProposal(CheckDeltaProposalRequest) returns (CheckDeltaProposalResponse); } // Auth configuration - one of the auth types @@ -325,6 +336,40 @@ message PushDeltaProposalResponse { string commitment = 4; } +message CheckDeltaProposalRequest { + string account_id = 1; + uint64 nonce = 2; + string delta_payload = 3; // JSON string, as for PushDeltaProposal +} + +message CheckDeltaProposalResponse { + bool success = 1; + string message = 2; + bool allowed = 3; // true on success; a refusal is returned as an error status + bool complete = 4; // false when an instance that opts out of dry runs was skipped + string error_code = 5; +} + +message GetPoliciesRequest { + string account_id = 1; +} + +message PolicyEntry { + string module_id = 1; + repeated string hooks = 2; + string description = 3; + optional string params = 4; // JSON object; only where the instance discloses params + optional string account_layer = 5; // JSON object; this account's layer, where disclosed +} + +message GetPoliciesResponse { + bool success = 1; + string message = 2; + string account_id = 3; + repeated PolicyEntry policies = 4; // evaluation order + string error_code = 5; +} + // Get delta proposals request message GetDeltaProposalsRequest { string account_id = 1; diff --git a/crates/client/src/client.rs b/crates/client/src/client.rs index 5986e38ab..caf11e45e 100644 --- a/crates/client/src/client.rs +++ b/crates/client/src/client.rs @@ -4,14 +4,15 @@ use crate::execution::ProposalExecution; use crate::keystore::Signer; use crate::proto::guardian_client::GuardianClient as GuardianGrpcClient; use crate::proto::{ - AbandonDeltaCandidateRequest, AbandonDeltaCandidateResponse, AuthConfig, ConfigureRequest, - ConfigureResponse, ExecuteDeltaProposalRequest, GetAccountByKeyCommitmentRequest, + AbandonDeltaCandidateRequest, AbandonDeltaCandidateResponse, AuthConfig, + CheckDeltaProposalRequest, CheckDeltaProposalResponse, ConfigureRequest, ConfigureResponse, + ExecuteDeltaProposalRequest, GetAccountByKeyCommitmentRequest, GetAccountByKeyCommitmentResponse, GetCanonicalNonceRequest, GetCanonicalNonceResponse, GetCurrentExecutionRequest, GetDeltaHistoryRequest, GetDeltaHistoryResponse, GetDeltaProposalExecutionRequest, GetDeltaProposalRequest, GetDeltaProposalResponse, GetDeltaProposalsRequest, GetDeltaProposalsResponse, GetDeltaRequest, GetDeltaResponse, - GetDeltaSinceRequest, GetDeltaSinceResponse, GetPubkeyRequest, GetStateRequest, - GetStateResponse, GetStateTailRequest, GetStateTailResponse, + GetDeltaSinceRequest, GetDeltaSinceResponse, GetPoliciesRequest, GetPoliciesResponse, + GetPubkeyRequest, GetStateRequest, GetStateResponse, GetStateTailRequest, GetStateTailResponse, ProposalSignature as ProtoProposalSignature, PushDeltaProposalRequest, PushDeltaProposalResponse, PushDeltaRequest, PushDeltaResponse, RevokeAllSessionsRequest, RevokeSessionRequest, SessionGrantFields, SignDeltaProposalRequest, SignDeltaProposalResponse, @@ -1099,6 +1100,63 @@ impl GuardianClient { Ok(inner) } + /// Dry run of [`Self::push_delta_proposal`]: the same checks and proposal-creation policy + /// modules, without storing a proposal. A module refusal is the same typed error proposal + /// creation returns; `complete` is false when a module that opts out of dry runs was + /// skipped. Advisory: approval still decides. + pub async fn check_delta_proposal( + &mut self, + account_id: &AccountId, + nonce: u64, + delta_payload: impl serde::Serialize, + ) -> ClientResult { + let message = CheckDeltaProposalRequest { + account_id: account_id.to_string(), + nonce, + delta_payload: serde_json::to_string(&delta_payload)?, + }; + let payload = AuthRequestPayload::for_operation( + SignedOperation::CheckDeltaProposal, + &prost::Message::encode_to_vec(&message), + ); + let inner = self + .send_with_replay_retry_as( + account_id, + message, + payload, + AuthMode::Session(SessionOperation::CheckDeltaProposal), + async |client, request| client.check_delta_proposal(request).await, + ) + .await?; + if !inner.success { + return Err(ClientError::ServerError(inner.message.clone())); + } + Ok(inner) + } + + /// The policy modules that apply to the account, as far as the Guardian's operator + /// discloses them, in evaluation order. `params` and `account_layer` are JSON objects. + pub async fn get_policies( + &mut self, + account_id: &AccountId, + ) -> ClientResult { + let message = GetPoliciesRequest { + account_id: account_id.to_string(), + }; + let inner = self + .send_allowing_session( + account_id, + SessionOperation::GetPolicies, + message, + async |client, request| client.get_policies(request).await, + ) + .await?; + if !inner.success { + return Err(ClientError::ServerError(inner.message.clone())); + } + Ok(inner) + } + /// Get all delta proposals for an account pub async fn get_delta_proposals( &mut self, diff --git a/crates/client/src/error.rs b/crates/client/src/error.rs index 65f0f495a..bf939a45f 100644 --- a/crates/client/src/error.rs +++ b/crates/client/src/error.rs @@ -19,6 +19,32 @@ pub const WALLET_SIGNATURE_REQUIRED_CODE: &str = "wallet_signature_required"; pub const UNSUPPORTED_AUTH_VERSION_CODE: &str = "unsupported_auth_version"; const AUTHENTICATION_FAILED_CODE: &str = "authentication_failed"; +/// A policy module refused the request, or the Guardian refused one too large for its modules to +/// judge (`reason_code = request_too_large`). +pub const MODULE_DENIED_CODE: &str = "GUARDIAN_MODULE_DENIED"; + +/// A fail-closed policy module could not decide, or the Guardian could not build the request a +/// module judges; retryable. +pub const MODULE_UNAVAILABLE_CODE: &str = "GUARDIAN_MODULE_UNAVAILABLE"; + +/// A refusal by one of the Guardian's policy modules. `module` is the operator-chosen +/// instance id. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum ModuleRefusal { + /// A generic denial (an instance with `client_reason = "generic"`) carries only the reason + /// code `policy_denied`: no module, no layer and no message. + Denied { + module: Option, + reason_code: String, + /// `global` or `account`: which parameter layer denied, when the server says. + layer: Option, + /// The module's text for the requester, when the instance allows it. + client_message: Option, + }, + /// `module` is absent for an instance whose denials are generic. + Unavailable { module: Option }, +} + /// Errors that can occur when using the GUARDIAN client. #[derive(Debug, Error)] pub enum ClientError { @@ -164,6 +190,26 @@ impl ClientError { ) } + /// The policy module refusal this error carries, if any. A denial is final; an + /// unavailable module is retryable ([`Self::is_retryable`]). + pub fn module_refusal(&self) -> Option { + let code = self.guardian_code()?; + let meta = self.guardian_meta()?; + let field = |name: &str| meta.get(name)?.as_str().map(str::to_owned); + match code.as_str() { + MODULE_DENIED_CODE => Some(ModuleRefusal::Denied { + module: field("module"), + reason_code: field("reason_code")?, + layer: field("layer"), + client_message: field("client_message"), + }), + MODULE_UNAVAILABLE_CODE => Some(ModuleRefusal::Unavailable { + module: field("module"), + }), + _ => None, + } + } + /// Server-provided backoff hint: the `retry-after` status metadata /// (decimal seconds), falling back to `meta.retry_after_secs`. /// Unparseable values mean no hint; classification is unaffected. @@ -212,6 +258,78 @@ mod tests { assert!(!err.is_not_found()); } + fn module_status(code: tonic::Code, details: serde_json::Value) -> ClientError { + tonic::Status::with_details(code, "refused", details.to_string().into_bytes().into()).into() + } + + #[test] + fn module_denial_is_typed_and_final() { + let err = module_status( + tonic::Code::PermissionDenied, + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "This Guardian's policy doesn't allow this request.", + "meta": { "retryable": false, "module": "caps", "reason_code": "amount_cap_exceeded", "layer": "account" } + }), + ); + assert_eq!( + err.module_refusal(), + Some(ModuleRefusal::Denied { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("account".into()), + client_message: None, + }) + ); + assert!(!err.is_retryable()); + } + + #[test] + fn generic_denial_is_typed_without_details() { + let err = module_status( + tonic::Code::PermissionDenied, + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "This Guardian's policy doesn't allow this request.", + "meta": { "retryable": false, "reason_code": "policy_denied" } + }), + ); + assert_eq!( + err.module_refusal(), + Some(ModuleRefusal::Denied { + module: None, + reason_code: "policy_denied".into(), + layer: None, + client_message: None, + }) + ); + } + + #[test] + fn module_unavailable_is_typed_and_retryable() { + let err = module_status( + tonic::Code::Unavailable, + serde_json::json!({ + "code": "GUARDIAN_MODULE_UNAVAILABLE", + "message": "A policy check is unavailable right now. Please try again shortly.", + "meta": { "retryable": true, "module": "sanctions" } + }), + ); + assert_eq!( + err.module_refusal(), + Some(ModuleRefusal::Unavailable { + module: Some("sanctions".into()) + }) + ); + assert!(err.is_retryable()); + } + + #[test] + fn other_errors_are_not_module_refusals() { + let err: ClientError = guardian_status().into(); + assert_eq!(err.module_refusal(), None); + } + #[test] fn user_message_is_none_without_structured_details() { // A bare Status.message may be developer-facing (e.g. pre-service @@ -313,6 +431,58 @@ mod tests { assert!(!ClientError::ServerError("boom".into()).is_not_found()); } + fn refusal_json(refusal: Option) -> serde_json::Value { + match refusal { + None => serde_json::Value::Null, + Some(ModuleRefusal::Denied { + module, + reason_code, + layer, + client_message, + }) => serde_json::json!({ + "kind": "denied", + "module": module, + "reasonCode": reason_code, + "layer": layer, + "clientMessage": client_message, + }), + Some(ModuleRefusal::Unavailable { module }) => { + serde_json::json!({ "kind": "unavailable", "module": module }) + } + } + } + + #[test] + fn module_refusals_match_shared_fixture() { + let path = concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../fixtures/guardian-client/module-refusals.json" + ); + let fixture: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(path).unwrap()).unwrap(); + + for case in fixture["cases"].as_array().unwrap() { + let name = case["name"].as_str().unwrap(); + let code = tonic::Code::from_i32(case["grpc"]["code"].as_i64().unwrap() as i32); + let err: ClientError = tonic::Status::with_details( + code, + "test", + case["body"].to_string().into_bytes().into(), + ) + .into(); + assert_eq!( + refusal_json(err.module_refusal()), + case["expected"]["refusal"], + "refusal mismatch: {name}" + ); + assert_eq!( + err.is_retryable(), + case["expected"]["retryable"].as_bool().unwrap(), + "retryable mismatch: {name}" + ); + } + } + #[test] fn retry_classification_matches_shared_fixture() { let path = concat!( diff --git a/crates/client/src/execution.rs b/crates/client/src/execution.rs index 1491665e6..feddc8292 100644 --- a/crates/client/src/execution.rs +++ b/crates/client/src/execution.rs @@ -2,7 +2,7 @@ pub use guardian_shared::execution::{ ExecutionFailureCode, ExecutionState, ExpirationBound, ForeignAccountUnavailableReason, - RequestInvalidReason, + ModuleDenial, RequestInvalidReason, }; use crate::error::{ClientError, ClientResult}; diff --git a/crates/client/src/lib.rs b/crates/client/src/lib.rs index 92110c8bb..88dbab9b6 100644 --- a/crates/client/src/lib.rs +++ b/crates/client/src/lib.rs @@ -56,8 +56,8 @@ pub use client::{ GuardianClient, MAX_SESSION_TTL, MIN_SESSION_TTL, SessionInfo, SessionSlot, StartSessionOptions, }; pub use error::{ - ClientError, ClientResult, SESSION_EXPIRED_CODE, SESSION_REVOKED_CODE, - WALLET_SIGNATURE_REQUIRED_CODE, + ClientError, ClientResult, MODULE_DENIED_CODE, MODULE_UNAVAILABLE_CODE, ModuleRefusal, + SESSION_EXPIRED_CODE, SESSION_REVOKED_CODE, WALLET_SIGNATURE_REQUIRED_CODE, }; pub use execution::{ExecutionFailure, ExecutionState, ProposalExecution}; pub use keystore::{EcdsaKeyStore, FalconKeyStore, Signer, verify_commitment_signature}; diff --git a/crates/client/src/testing/client_tests.rs b/crates/client/src/testing/client_tests.rs index c8e6aa291..da80c7e64 100644 --- a/crates/client/src/testing/client_tests.rs +++ b/crates/client/src/testing/client_tests.rs @@ -241,6 +241,49 @@ async fn test_push_delta_proposal_success() { assert!(response.delta.is_some()); } +#[tokio::test] +async fn a_proposal_refused_by_a_policy_module_surfaces_as_a_typed_refusal() { + let details = serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "This Guardian's policy doesn't allow this request.", + "meta": { + "retryable": false, + "module": "caps", + "reason_code": "amount_cap_exceeded", + "layer": "global" + } + }) + .to_string() + .into_bytes(); + let service = MockGuardianService::default().with_push_delta_proposal(Err( + Status::with_details(tonic::Code::PermissionDenied, "denied", details.into()), + )); + let endpoint = start_mock_server(service).await.unwrap(); + let mut client = GuardianClient::connect(endpoint) + .await + .unwrap() + .with_signer(create_test_signer()); + + let error = client + .push_delta_proposal( + &create_test_account_id(), + 1, + serde_json::json!({"tx_summary": {}, "signatures": []}), + ) + .await + .unwrap_err(); + assert_eq!( + error.module_refusal(), + Some(crate::ModuleRefusal::Denied { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("global".into()), + client_message: None, + }) + ); + assert!(!error.is_retryable()); +} + #[tokio::test] async fn test_get_delta_proposals_success() { let mock_delta1 = create_mock_delta(); @@ -652,6 +695,46 @@ async fn terminal_authentication_failure_is_not_retried() { assert!(!error.is_replay_rejection()); } +#[tokio::test] +async fn policies_and_proposal_checks_round_trip() { + let service = MockGuardianService::default(); + let handle = service.handle(); + let endpoint = start_mock_server(service).await.unwrap(); + let mut client = GuardianClient::connect(endpoint) + .await + .unwrap() + .with_signer(create_test_signer()); + let account_id = create_test_account_id(); + + let policies = client.get_policies(&account_id).await.unwrap(); + assert_eq!(policies.policies[0].module_id, "caps"); + assert!(policies.policies[0].params.is_some()); + + let passed = client + .check_delta_proposal(&account_id, 1, serde_json::json!({ "tx_summary": {} })) + .await + .unwrap(); + assert!(passed.allowed); + assert!(!passed.complete); + + let refused = client + .check_delta_proposal(&account_id, 0, serde_json::json!({ "tx_summary": {} })) + .await + .unwrap_err(); + assert!(matches!( + refused.module_refusal(), + Some(crate::ModuleRefusal::Denied { module: None, ref reason_code, .. }) if reason_code == "policy_denied" + )); + assert_eq!( + handle.calls(), + vec![ + "get_policies", + "check_delta_proposal", + "check_delta_proposal" + ] + ); +} + #[tokio::test] async fn test_get_canonical_nonce_success() { let service = diff --git a/crates/client/src/testing/mocks.rs b/crates/client/src/testing/mocks.rs index 33db2013e..71d8fb39b 100644 --- a/crates/client/src/testing/mocks.rs +++ b/crates/client/src/testing/mocks.rs @@ -1,17 +1,18 @@ use crate::proto::guardian_server::{Guardian, GuardianServer}; use crate::proto::{ - AbandonDeltaCandidateRequest, AbandonDeltaCandidateResponse, AccountState, ConfigureRequest, - ConfigureResponse, CreateSessionRequest, CreateSessionResponse, - DeltaObject as ProtoDeltaObject, ExecuteDeltaProposalRequest, ExecuteDeltaProposalResponse, - ExecutionEnvelope, GetAccountByKeyCommitmentRequest, GetAccountByKeyCommitmentResponse, - GetCanonicalNonceRequest, GetCanonicalNonceResponse, GetCurrentExecutionRequest, - GetCurrentExecutionResponse, GetDeltaHistoryRequest, GetDeltaHistoryResponse, - GetDeltaProposalExecutionRequest, GetDeltaProposalExecutionResponse, GetDeltaProposalRequest, - GetDeltaProposalResponse, GetDeltaProposalsRequest, GetDeltaProposalsResponse, GetDeltaRequest, - GetDeltaResponse, GetDeltaSinceRequest, GetDeltaSinceResponse, GetPubkeyRequest, - GetStateRequest, GetStateResponse, GetStateTailRequest, GetStateTailResponse, - PushDeltaProposalRequest, PushDeltaProposalResponse, PushDeltaRequest, PushDeltaResponse, - RevokeAllSessionsRequest, RevokeAllSessionsResponse, RevokeSessionRequest, + AbandonDeltaCandidateRequest, AbandonDeltaCandidateResponse, AccountState, + CheckDeltaProposalRequest, CheckDeltaProposalResponse, ConfigureRequest, ConfigureResponse, + CreateSessionRequest, CreateSessionResponse, DeltaObject as ProtoDeltaObject, + ExecuteDeltaProposalRequest, ExecuteDeltaProposalResponse, ExecutionEnvelope, + GetAccountByKeyCommitmentRequest, GetAccountByKeyCommitmentResponse, GetCanonicalNonceRequest, + GetCanonicalNonceResponse, GetCurrentExecutionRequest, GetCurrentExecutionResponse, + GetDeltaHistoryRequest, GetDeltaHistoryResponse, GetDeltaProposalExecutionRequest, + GetDeltaProposalExecutionResponse, GetDeltaProposalRequest, GetDeltaProposalResponse, + GetDeltaProposalsRequest, GetDeltaProposalsResponse, GetDeltaRequest, GetDeltaResponse, + GetDeltaSinceRequest, GetDeltaSinceResponse, GetPoliciesRequest, GetPoliciesResponse, + GetPubkeyRequest, GetStateRequest, GetStateResponse, GetStateTailRequest, GetStateTailResponse, + PolicyEntry, PushDeltaProposalRequest, PushDeltaProposalResponse, PushDeltaRequest, + PushDeltaResponse, RevokeAllSessionsRequest, RevokeAllSessionsResponse, RevokeSessionRequest, RevokeSessionResponse, SignDeltaProposalRequest, SignDeltaProposalResponse, }; use guardian_shared::FromJson; @@ -39,6 +40,8 @@ pub struct MockGuardianHandle { calls: Arc>>, /// Every `push_delta_proposal` request body, in arrival order. push_delta_proposal_requests: Arc>>, + /// Every `check_delta_proposal` request body, in arrival order. + check_delta_proposal_requests: Arc>>, /// Every `abandon_delta_candidate` request body, in arrival order. abandon_requests: Arc>>, /// Every `execute_delta_proposal` request with the auth metadata it carried, in arrival @@ -64,6 +67,11 @@ impl MockGuardianHandle { self.push_delta_proposal_requests.lock().unwrap().clone() } + /// Every `check_delta_proposal` request received so far. + pub fn checked_proposals(&self) -> Vec { + self.check_delta_proposal_requests.lock().unwrap().clone() + } + /// Every `abandon_delta_candidate` request received so far. pub fn abandon_requests(&self) -> Vec { self.abandon_requests.lock().unwrap().clone() @@ -742,6 +750,61 @@ impl Guardian for MockGuardianService { response.map(Response::new) } + async fn check_delta_proposal( + &self, + request: Request, + ) -> Result, Status> { + self.record_call("check_delta_proposal"); + self.handle + .check_delta_proposal_requests + .lock() + .unwrap() + .push(request.get_ref().clone()); + if request.get_ref().nonce == 0 { + return Err(Status::with_details( + tonic::Code::PermissionDenied, + "refused", + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "This Guardian's policy doesn't allow this request.", + "meta": { "retryable": false, "reason_code": "policy_denied" } + }) + .to_string() + .into_bytes() + .into(), + )); + } + Ok(Response::new(CheckDeltaProposalResponse { + success: true, + message: String::new(), + allowed: true, + complete: false, + error_code: String::new(), + })) + } + + async fn get_policies( + &self, + request: Request, + ) -> Result, Status> { + self.record_call("get_policies"); + Ok(Response::new(GetPoliciesResponse { + success: true, + message: String::new(), + account_id: request.into_inner().account_id, + policies: vec![PolicyEntry { + module_id: "caps".into(), + hooks: vec!["before_transaction_approved".into()], + description: "At most 5 per transaction".into(), + params: Some( + r#"{"max_per_transaction":{"0x0000000000000000000000000000aa":"5"}}"#.into(), + ), + account_layer: None, + }], + error_code: String::new(), + })) + } + async fn get_state_tail( &self, request: Request, diff --git a/crates/guardian-module-sdk/Cargo.toml b/crates/guardian-module-sdk/Cargo.toml new file mode 100644 index 000000000..78e31a0c6 --- /dev/null +++ b/crates/guardian-module-sdk/Cargo.toml @@ -0,0 +1,40 @@ +[package] +name = "guardian-module-sdk" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +authors.workspace = true +license.workspace = true +repository.workspace = true +homepage.workspace = true +description = "Module interface, protocol types and serving harness for Guardian policy modules" +readme = "README.md" +documentation = "https://docs.rs/guardian-module-sdk" +keywords = ["guardian", "miden", "policy", "grpc", "multisig"] +categories = ["cryptography::cryptocurrencies", "network-programming"] +include = ["src/**/*", "proto/**/*", "build.rs", "Cargo.toml", "README.md"] + +[package.metadata.docs.rs] +all-features = true + +[dependencies] +async-trait = "0.1" +bech32 = "0.11" +prost = { workspace = true } +prost-types = "0.14" +secrecy = "0.10" +serde = { workspace = true, features = ["derive"] } +serde_json = { workspace = true } +thiserror = { workspace = true } +tokio = { workspace = true, features = ["rt-multi-thread", "macros", "net", "fs"] } +tonic = { workspace = true } +tonic-prost = { workspace = true } + +[features] +conformance = [] + +[dev-dependencies] +guardian-module-sdk = { path = ".", features = ["conformance"] } + +[build-dependencies] +tonic-prost-build = { workspace = true } diff --git a/crates/guardian-module-sdk/README.md b/crates/guardian-module-sdk/README.md new file mode 100644 index 000000000..04afd652f --- /dev/null +++ b/crates/guardian-module-sdk/README.md @@ -0,0 +1,163 @@ +# guardian-module-sdk + +Build policy modules for [Guardian](https://github.com/OpenZeppelin/guardian): +services the Guardian asks before it signs a transaction, creates a proposal or +accepts a new account. A module answers allow or deny; it cannot sign, change +its own configuration, or see the Guardian's secrets. + +The crate has: + +- `Module`, the trait a module implements, and `ModuleFactory` for kinds + compiled into a Guardian build. +- The `guardian.module.v1` protocol types (`HookRequest`, `Decision`, + `ModuleInfo`, the Miden transaction and account projections). Protocol + version 1 is not frozen yet: it freezes with the first published release of + this crate, and after that new features arrive as named capabilities. +- `serve`, a gRPC harness that exposes any `Module` as a remote service with a + bearer token per instance. +- `policies`, the Guardian's built-in policy kinds, one concern each, as a + reference: `SpendingLimit` (caps and allowed assets), `RecipientPolicy`, + `SignerPolicy` and `CodePolicy`. +- `conformance` (feature `conformance`), a suite that checks a module before + it is deployed. + +## A module + +```rust +use guardian_module_sdk::proto::hook_request; +use guardian_module_sdk::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, + PROTOCOL_VERSION, ParamsVerdict, +}; + +struct NoPrivateNotes; + +#[guardian_module_sdk::async_trait] +impl Module for NoPrivateNotes { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(ModuleInfo { + name: "no-private-notes".into(), + version: "1.0.0".into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![Hook::BeforeTransactionApproved as i32], + ..Default::default() + }) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(if params == b"{}" { + ParamsVerdict::ok() + } else { + ParamsVerdict::invalid("takes no params") + }) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + let Some(hook_request::Subject::Transaction(subject)) = &request.subject else { + return Err(ModuleError::InvalidRequest("judges transactions only".into())); + }; + let miden = subject + .miden() + .ok_or_else(|| ModuleError::InvalidRequest("not a Miden transaction".into()))?; + let private = miden + .output_notes + .iter() + .any(|note| note.note_type == guardian_module_sdk::NoteType::Private as i32); + Ok(if private { + Decision::deny("private_note", "creates a private note") + .with_client_message("Private notes are not allowed for this account") + } else { + Decision::allow() + }) + } +} +``` + +Rules every module follows: + +- `evaluate` has no side effects. The same transaction is evaluated when the + proposal is created and again before the Guardian signs, clients retry, and + the Guardian may call it concurrently. +- A deny carries a `reason_code` of 1 to 64 lowercase letters, digits or + underscores. `message` is logged by the Guardian and never shown to clients; + `client_message` (plain text, at most 256 characters) is shown only where + the operator allows it. +- Return `ModuleError` rather than allow when the request lacks what the module + needs. The operator's `on_error` setting then decides, and the default is to + refuse. +- Params arrive as UTF-8 JSON in `HookRequest.params` on every call: the + module keeps no params of its own, so operator changes apply on the next + request. + +## Serve it over gRPC + +```rust +use guardian_module_sdk::serve::serve; + +serve(NoPrivateNotes) + .instance("no-private-notes", token) + .run("127.0.0.1:7443".parse()?) + .await?; +``` + +Each instance the Guardian calls (its catalog `id`) has its own token; a call +for an unknown instance, or with another instance's token, is refused. A server +with no instance registered refuses every call. For a test or a local experiment +on a loopback address, `serve(module).allow_unauthenticated()` answers without +credentials; never expose such a server, since anyone who reaches it can query +the module. For TLS +add `serve(...).into_service()` to a tonic server configured for TLS, as +[`examples/policy-module`](https://github.com/OpenZeppelin/guardian/tree/main/examples/policy-module) +does. Raise the server's receive limit if you lower it: the Guardian sends +requests up to `DEFAULT_REQUEST_MAX_BYTES` (2 MiB) by default. + +The Guardian side is a catalog entry: + +```toml +[[module]] +id = "no-private-notes" +kind = "grpc" +endpoint = "grpc://modules.internal:7443" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 200 +on_error = "deny" +auth = { token_secret = "guardian/modules/no-private-notes-token" } +``` + +## Check it + +```toml +[dev-dependencies] +guardian-module-sdk = { version = "0.19.0-rc.1", features = ["conformance"] } +``` + +```rust +use guardian_module_sdk::conformance::Suite; + +#[tokio::test] +async fn conforms() { + Suite::new(NoPrivateNotes) + .allows("public payment", public_payment()) + .denies("private payment", private_payment()) + .valid_params(serde_json::json!({})) + .invalid_params(serde_json::json!({ "x": 1 })) + .run() + .await + .assert_conformant(); +} +``` + +The suite serves the module over loopback gRPC with two instances, and checks +`Describe`, params validation on both transports, identical answers in process +and over gRPC, repeated, reordered and concurrent evaluations, the shape of +every decision, the outcome each request is stated to have (`allows`, `denies`, +`denies_with`, `fails`), per-instance tokens and a request at the size cap. It +needs at least one request the module must deny. + +## Further reading + +- [Policy module guides](https://github.com/OpenZeppelin/guardian/tree/main/docs/guides/policy-modules): + built-in, remote and custom modules end to end. +- [RFC 0002](https://github.com/OpenZeppelin/guardian/blob/main/docs/rfcs/0002-guardian-modules.md): + the design, the protocol and the trust model. diff --git a/crates/guardian-module-sdk/build.rs b/crates/guardian-module-sdk/build.rs new file mode 100644 index 000000000..7927b3cca --- /dev/null +++ b/crates/guardian-module-sdk/build.rs @@ -0,0 +1,5 @@ +fn main() -> Result<(), Box> { + tonic_prost_build::configure() + .compile_protos(&["proto/guardian_module_v1.proto"], &["proto"])?; + Ok(()) +} diff --git a/crates/guardian-module-sdk/examples/note-policy-serve.rs b/crates/guardian-module-sdk/examples/note-policy-serve.rs new file mode 100644 index 000000000..a19f56c5f --- /dev/null +++ b/crates/guardian-module-sdk/examples/note-policy-serve.rs @@ -0,0 +1,38 @@ +//! The `note-policy` module served over gRPC, for the Guardian to call as a remote module. +//! Walkthrough in `docs/guides/policy-modules/custom.md`. +//! +//! ```text +//! cargo run -p guardian-module-sdk --example note-policy-serve -- \ +//! --listen 127.0.0.1:7444 --instance note-policy +//! ``` + +mod note_policy; + +use std::net::SocketAddr; + +use guardian_module_sdk::serve::serve; +use note_policy::NotePolicy; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let mut args = std::env::args().skip(1); + let mut listen: SocketAddr = "127.0.0.1:7444".parse()?; + let mut server = serve(NotePolicy); + while let Some(arg) = args.next() { + match arg.as_str() { + "--listen" => listen = args.next().ok_or("--listen needs an address")?.parse()?, + "--instance" => { + let id = args.next().ok_or("--instance needs an id")?; + let token_file = args.next().ok_or("--instance needs a token file")?; + server = server.instance(id, std::fs::read_to_string(token_file)?.trim()); + } + other => return Err(format!("unknown argument {other}").into()), + } + } + if !server.has_instances() { + return Err("at least one --instance is required".into()); + } + println!("note-policy listening on {listen}"); + server.run(listen).await?; + Ok(()) +} diff --git a/crates/guardian-module-sdk/examples/note_policy/mod.rs b/crates/guardian-module-sdk/examples/note_policy/mod.rs new file mode 100644 index 000000000..303339873 --- /dev/null +++ b/crates/guardian-module-sdk/examples/note_policy/mod.rs @@ -0,0 +1,187 @@ +//! The `note-policy` module: limits how many payment notes a transaction may create and can +//! refuse private notes, whose recipients the Guardian cannot see. Shared by the gRPC example +//! (`note-policy-serve`) and the in-process one (`examples/custom-guardian`, which the release +//! template copies it into). + +// Each including example uses only part of this file. +#![allow(dead_code)] + +use std::sync::Arc; + +use async_trait::async_trait; +use guardian_module_sdk::proto::hook_request; +use guardian_module_sdk::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleFactory, ModuleInfo, + ModuleInstanceConfig, NoteType, PROTOCOL_VERSION, ParamsVerdict, +}; +use serde::Deserialize; + +pub const KIND: &str = "note-policy"; + +/// The module's own version, reported by `describe`. Not the crate version: this file is +/// compiled into both the SDK example and a server build. +pub const VERSION: &str = "1.0.0"; + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct Params { + max_payment_notes: Option, + #[serde(default)] + deny_private_notes: bool, +} + +fn parse(params: &[u8]) -> Result { + serde_json::from_slice(params).map_err(|e| e.to_string()) +} + +pub struct NotePolicy; + +#[async_trait] +impl Module for NotePolicy { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(ModuleInfo { + name: KIND.into(), + version: VERSION.into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![ + Hook::BeforeProposalCreated as i32, + Hook::BeforeTransactionApproved as i32, + ], + ..Default::default() + }) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(match parse(params) { + Ok(_) => ParamsVerdict::ok(), + Err(message) => ParamsVerdict::invalid(message), + }) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + let params = parse(&request.params).map_err(ModuleError::InvalidRequest)?; + let Some(hook_request::Subject::Transaction(subject)) = &request.subject else { + return Err(ModuleError::InvalidRequest( + "this module judges transactions only".into(), + )); + }; + let Some(projection) = subject.miden() else { + return Err(ModuleError::InvalidRequest( + "not a Miden transaction".into(), + )); + }; + let payments: Vec<_> = projection + .output_notes + .iter() + .filter(|note| !note.tx_fee) + .collect(); + + if params.deny_private_notes + && payments + .iter() + .any(|note| note.note_type == NoteType::Private as i32) + { + return Ok(Decision::deny( + "private_note_not_allowed", + "the transaction creates a private note", + )); + } + if let Some(max) = params.max_payment_notes + && payments.len() > max as usize + { + return Ok(Decision::deny( + "too_many_payment_notes", + format!("{} payment notes, at most {max} allowed", payments.len()), + )); + } + Ok(Decision::allow()) + } +} + +/// Creates the module for a catalog instance of kind `note-policy` running in process. +pub struct NotePolicyFactory; + +impl ModuleFactory for NotePolicyFactory { + fn create(&self, _instance: &ModuleInstanceConfig) -> Result, ModuleError> { + Ok(Arc::new(NotePolicy)) + } +} + +#[cfg(test)] +mod tests { + use guardian_module_sdk::{ + MidenTransaction, OutputNote, TransactionProjection, TransactionSubject, + }; + + use super::*; + + fn request(params: serde_json::Value, notes: Vec) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + output_notes: notes, + ..Default::default() + })), + ..Default::default() + })), + ..Default::default() + } + } + + fn note(note_type: NoteType, tx_fee: bool) -> OutputNote { + OutputNote { + note_type: note_type as i32, + tx_fee, + ..Default::default() + } + } + + #[tokio::test] + async fn counts_payments_but_not_the_fee_note() { + let params = serde_json::json!({ "max_payment_notes": 1 }); + let one_payment = vec![note(NoteType::Public, false), note(NoteType::Public, true)]; + assert!( + NotePolicy + .evaluate(&request(params.clone(), one_payment)) + .await + .unwrap() + .allows() + ); + let two_payments = vec![note(NoteType::Public, false), note(NoteType::Public, false)]; + let decision = NotePolicy + .evaluate(&request(params, two_payments)) + .await + .unwrap(); + assert_eq!(decision.reason_code, "too_many_payment_notes"); + } + + #[tokio::test] + async fn refuses_private_notes_when_asked() { + let notes = vec![note(NoteType::Private, false)]; + let decision = NotePolicy + .evaluate(&request( + serde_json::json!({ "deny_private_notes": true }), + notes.clone(), + )) + .await + .unwrap(); + assert_eq!(decision.reason_code, "private_note_not_allowed"); + assert!( + NotePolicy + .evaluate(&request(serde_json::json!({}), notes)) + .await + .unwrap() + .allows() + ); + } + + #[tokio::test] + async fn unknown_params_are_invalid() { + let verdict = NotePolicy + .validate_params(br#"{"max_notes": 1}"#) + .await + .unwrap(); + assert!(!verdict.ok); + } +} diff --git a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto b/crates/guardian-module-sdk/proto/guardian_module_v1.proto similarity index 61% rename from speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto rename to crates/guardian-module-sdk/proto/guardian_module_v1.proto index 755b15476..e317175a7 100644 --- a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto +++ b/crates/guardian-module-sdk/proto/guardian_module_v1.proto @@ -1,6 +1,7 @@ -// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 24). +// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 35). // The proto in RFC section 3 is authoritative; regenerate this file when it changes. -// Protocol version 1 is frozen when M2a ships. +// Protocol version 1 is not frozen yet: it freezes with the first published guardian-module-sdk +// release, and from then on changes within it are additive only (RFC section 3.5). syntax = "proto3"; package guardian.module.v1; @@ -11,15 +12,12 @@ service GuardianModule { rpc Describe(DescribeRequest) returns (ModuleInfo); rpc ValidateParams(ValidateParamsRequest) returns (ParamsVerdict); rpc Evaluate(HookRequest) returns (Decision); - rpc Notify(CommitEvent) returns (NotifyAck); - rpc NotifyGap(Gap) returns (NotifyAck); } enum Hook { HOOK_UNSPECIFIED = 0; HOOK_BEFORE_TRANSACTION_APPROVED = 1; HOOK_BEFORE_ACCOUNT_REGISTERED = 2; - HOOK_AFTER_TRANSACTION_COMMITTED = 3; HOOK_BEFORE_PROPOSAL_CREATED = 4; } @@ -44,18 +42,16 @@ message ParamsVerdict { string message = 2; bytes normalized_params = 3; // UTF-8 JSON; empty: store the params as sent (section 3.5) } -message NotifyAck {} - message HookRequest { string request_id = 1; // one per hook invocation, shared by every module and layer called in it (section 3.1) Hook hook = 2; bool dry_run = 3; // a policy check: nothing is stored or signed whatever the decision (section 2.7) string network = 4; // network family: "miden" - string network_id = 5; // the account's network within the family: "mainnet", "testnet", "devnet", "cedar" or "local" (section 3.1) + string network_id = 5; // the network this Guardian serves within the family: "mainnet", "testnet", "devnet", "cedar" or "local"; from its own configuration, never from the request (section 3.1) string account_id = 6; string instance_id = 7; // catalog id of the instance being called bytes params = 8; // UTF-8 JSON, params of the layer being evaluated (global, account layer, or the account's own for default/assigned) - google.protobuf.Timestamp accounting_time = 9; // recorded as signed_at if this transaction is signed (section 3.4); at before_proposal_created and in a dry run, the evaluation time, never recorded + google.protobuf.Timestamp accounting_time = 9; // the evaluation time, from the Guardian's clock string submitter = 10; // signer commitment that authenticated this request; verified (section 3.2) bool submitter_session = 11; // the request was authenticated by a session key the submitter delegated (section 3.2) optional AccountView before = 12; // the account as the Guardian holds it; absent for a first configuration (section 3.2) @@ -68,56 +64,37 @@ message HookRequest { message AccountView { string commitment = 1; - string auth_scheme = 2; // "falcon" or "ecdsa", from the registered auth configuration (section 3.2) + string auth_scheme = 2; // the scheme every signer shares, "falcon" or "ecdsa", or "mixed" (section 3.2) repeated string signer_commitments = 3; optional uint32 default_threshold = 4; // absent for single-key accounts map procedure_thresholds = 5; // procedure root -> threshold; only overrides the account's code can apply (section 3.2) string code_commitment = 6; // commitment of the account's code repeated string procedure_roots = 7; // roots of the procedures the account's code exports + map signer_schemes = 8; // signer commitment -> "falcon" or "ecdsa"; one entry per signer (section 3.2) } message TransactionSubject { TransactionProjection projection = 1; // the contract modules should rely on, per network RawTransaction raw = 2; // the network's own encoding; UNSTABLE across that network's protocol bumps - repeated PendingTransaction pending = 3; // signed for this account, not yet acknowledged by this module (section 3.4) string proposer = 4; // signer commitment that created the matching proposal; verified; empty when there is none (section 3.2) - bool proposer_session = 5; // the proposer created it through a delegated session key (section 3.2) - bytes unverified_metadata = 6; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) -} - -message PendingTransaction { - string new_commitment = 1; // = event_id once committed - TransactionProjection projection = 2; - google.protobuf.Timestamp signed_at = 3; // the accounting clock (section 3.4) - PendingState state = 4; - uint64 nonce = 5; // account nonce after this transaction; compared with the module's watermark - optional google.protobuf.Timestamp committed_at = 6; // set when state = committed - string submitter = 7; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) - string proposer = 8; // as in TransactionSubject at that ack; empty when there was no matching proposal - bool proposer_session = 9; // as in TransactionSubject at that ack -} -enum PendingState { - PENDING_STATE_UNSPECIFIED = 0; - PENDING_STATE_CANDIDATE = 1; // signed, waiting to become committed - PENDING_STATE_COMMITTED = 2; // committed, notify not yet acknowledged by this module + bytes unverified_metadata = 5; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) } message RegistrationSubject { - AccountStateProjection initial_state = 1; // the account about to be accepted, per network + AccountStateProjection initial_state = 1; // the account about to be accepted, per network: its whole vault and storage } enum Effect { - EFFECT_UNSPECIFIED = 0; // a module that does not set `effect`: `allow` decides + EFFECT_UNSPECIFIED = 0; // never a decision: a module failure EFFECT_ALLOW = 1; EFFECT_DENY = 2; } message Decision { - bool allow = 1; // read only when effect is unspecified - string reason_code = 2; // required on a deny; ignored on an allow + Effect effect = 1; // unspecified, or a value the Guardian does not know, is a module failure + string reason_code = 2; // required on a deny, [a-z0-9_]{1,64}; a deny with another code is still a deny, reported as policy_denied; ignored on an allow string message = 3; // logged, never forwarded to clients - Effect effect = 4; // wins over allow when set; a value the Guardian does not know is a module failure - string client_message = 5; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) + string client_message = 4; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) } // A transaction as its network describes it. One variant per network; a module reads the @@ -142,14 +119,15 @@ message RawTransaction { } message MidenTransaction { - int64 nonce_delta = 1; - uint32 reference_block = 2; // the block the transaction was executed against - optional uint32 expiration_block = 3; // absent when the transaction sets no expiration (section 3.1) + uint64 nonce_delta = 1; + uint32 bound_block = 2; // the block the summary binds; the transaction executes against this block or a later one (section 3.1) + optional uint32 expiration_delta = 3; // blocks after the block the transaction executes against at which it expires; absent when its script sets none. Not an absolute height: that block is not known at approval (section 3.1) repeated VaultChange vault_changes = 4; repeated OutputNote output_notes = 5; repeated InputNote input_notes = 6; repeated StorageChange storage_changes = 7; optional string new_code_commitment = 8; // set when the transaction replaces the account's code (section 3.1) + optional uint64 approval_expiration_block = 9; // the block at which the cosigners' approval of this transaction lapses; absent when it never lapses (section 3.1) } message MidenAccountState { @@ -173,7 +151,8 @@ message OutputNote { repeated Asset assets = 5; string script_root = 6; optional string p2id_target = 7; // set only for known P2ID / P2IDE scripts - bool tx_fee = 8; // the fee note pay_fee creates; not a payment + bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note, and only while it carries no more of the fee asset than a transaction can owe) + optional string reclaimer = 9; // P2IDE only, set when its reclaim height is set: the account that can take the note once that height is reached, chosen freely by the note's creator; a recipient rule must judge it as well as p2id_target } enum NoteType { NOTE_TYPE_UNSPECIFIED = 0; NOTE_TYPE_PUBLIC = 1; NOTE_TYPE_PRIVATE = 2; } @@ -195,29 +174,3 @@ message StorageSlot { StorageSlotKind kind = 2; oneof content { string value = 3; MapChanges map = 4; } } - -message CommitEvent { - string event_id = 1; // = new_commitment; stable across redelivery - string instance_id = 2; - string account_id = 3; - string network = 4; // as in HookRequest - string network_id = 5; // as in HookRequest - string prev_commitment = 6; - string new_commitment = 7; - uint64 nonce = 8; // account nonce after this transaction; the delivery watermark (section 3.3) - TransactionProjection projection = 9; - google.protobuf.Timestamp committed_at = 10; - google.protobuf.Timestamp signed_at = 11; // the accounting clock, identical to the value the module saw in pending (section 3.4) - string submitter = 12; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) - string proposer = 13; // as in TransactionSubject at that ack; empty when there was no matching proposal (section 3.2) - bool proposer_session = 14; // as in TransactionSubject at that ack -} - -message Gap { - string instance_id = 1; - string account_id = 2; - string network = 3; // as in HookRequest - string network_id = 4; // as in HookRequest - google.protobuf.Timestamp dropped_before = 5; // restart position: events for the account committed before this and not acknowledged may be missing - uint64 resume_from_nonce = 6; // first nonce delivered after the gap; the module's watermark becomes resume_from_nonce - 1 (section 3.3) -} diff --git a/crates/guardian-module-sdk/src/conformance.rs b/crates/guardian-module-sdk/src/conformance.rs new file mode 100644 index 000000000..c61be9fff --- /dev/null +++ b/crates/guardian-module-sdk/src/conformance.rs @@ -0,0 +1,879 @@ +//! Conformance suite for stateless modules. +//! +//! [`Suite`] runs one module in process and through the [`serve`](crate::serve) harness over +//! loopback gRPC, with two instances on one service, and checks that it answers `Describe` +//! for protocol version 1, validates params the same way on both transports, returns the same +//! outcome for every request on both transports, keeps `evaluate` free of side effects +//! (repeated, reordered and concurrent evaluations agree), returns well-formed decisions, +//! answers each request as the suite says it must, and accepts a request at the Guardian's size +//! cap. +//! +//! Consistency alone is not conformance: a module that allows everything is consistent. The +//! suite therefore needs at least one request the module must deny ([`Suite::denies`] or +//! [`Suite::denies_with`]), and checks every stated expectation. +//! +//! ```no_run +//! # async fn example(request: guardian_module_sdk::HookRequest, blocked: guardian_module_sdk::HookRequest) { +//! use guardian_module_sdk::policies::RecipientPolicy; +//! use guardian_module_sdk::conformance::Suite; +//! +//! Suite::new(RecipientPolicy) +//! .allows("small payment", request) +//! .denies_with("payment to a blocked recipient", blocked, "recipient_blocked") +//! .valid_params(serde_json::json!({ "denylist": [] })) +//! .invalid_params(serde_json::json!({ "unknown": 1 })) +//! .run() +//! .await +//! .assert_conformant(); +//! # } +//! ``` + +use std::fmt; +use std::sync::Arc; + +use tokio::net::TcpListener; +use tokio::sync::oneshot; +use tokio::task::JoinSet; +use tonic::Request; +use tonic::metadata::MetadataValue; +use tonic::transport::server::TcpIncoming; +use tonic::transport::{Channel, Server}; + +use crate::proto::guardian_module_client::GuardianModuleClient; +use crate::proto::hook_request; +use crate::serve::{serve, status}; +use crate::{ + DEFAULT_REQUEST_MAX_BYTES, Decision, DescribeRequest, Effect, Hook, HookRequest, Module, + PROTOCOL_VERSION, ParamsVerdict, RawTransaction, ValidateParamsRequest, is_valid_reason_code, +}; + +const INSTANCE_A: &str = "conformance-a"; +const INSTANCE_B: &str = "conformance-b"; +const TOKEN_A: &str = "conformance-token-a"; +const TOKEN_B: &str = "conformance-token-b"; +const CLIENT_MESSAGE_MAX_CHARS: usize = 256; +const REPEATS: usize = 3; +const PADDING_ENCODING: &str = "conformance.padding"; + +type Outcome = Result; + +/// What a request must be answered with. +#[derive(Debug, Clone, PartialEq, Eq)] +enum Expected { + Allow, + Deny, + DenyWith(String), + Error, +} + +impl Expected { + fn met_by(&self, outcome: &Outcome) -> bool { + match (self, outcome) { + (Expected::Allow, Ok(decision)) => decision.effect == Effect::Allow as i32, + (Expected::Deny, Ok(decision)) => decision.effect == Effect::Deny as i32, + (Expected::DenyWith(code), Ok(decision)) => { + decision.effect == Effect::Deny as i32 && &decision.reason_code == code + } + (Expected::Error, Err(_)) => true, + (_, _) => false, + } + } +} + +impl fmt::Display for Expected { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Expected::Allow => write!(f, "an allow"), + Expected::Deny => write!(f, "a deny"), + Expected::DenyWith(code) => write!(f, "a deny with reason code {code}"), + Expected::Error => write!(f, "an error"), + } + } +} + +pub struct Suite { + module: Arc, + requests: Vec<(String, HookRequest)>, + /// One entry per request: what it must be answered with, when the suite says. + expected: Vec>, + valid_params: Vec, + invalid_params: Vec, + request_max_bytes: usize, +} + +impl Suite { + pub fn new(module: M) -> Self { + Self { + module: Arc::new(module), + requests: Vec::new(), + expected: Vec::new(), + valid_params: Vec::new(), + invalid_params: Vec::new(), + request_max_bytes: DEFAULT_REQUEST_MAX_BYTES, + } + } + + /// A request the module must answer the same way on every transport and every time, + /// whatever the answer is. The suite sets `instance_id`; everything else is sent as given. + pub fn request(self, name: impl Into, request: HookRequest) -> Self { + self.expecting(name, request, None) + } + + /// A request the module must allow. + pub fn allows(self, name: impl Into, request: HookRequest) -> Self { + self.expecting(name, request, Some(Expected::Allow)) + } + + /// A request the module must deny. Every suite needs one: a module that refuses nothing + /// answers consistently too. + pub fn denies(self, name: impl Into, request: HookRequest) -> Self { + self.expecting(name, request, Some(Expected::Deny)) + } + + /// A request the module must deny with `reason_code`. + pub fn denies_with( + self, + name: impl Into, + request: HookRequest, + reason_code: impl Into, + ) -> Self { + self.expecting(name, request, Some(Expected::DenyWith(reason_code.into()))) + } + + /// A request the module cannot judge and must answer with an error, so the instance's + /// `on_error` decides, never an allow. + pub fn fails(self, name: impl Into, request: HookRequest) -> Self { + self.expecting(name, request, Some(Expected::Error)) + } + + fn expecting( + mut self, + name: impl Into, + request: HookRequest, + expected: Option, + ) -> Self { + self.requests.push((name.into(), request)); + self.expected.push(expected); + self + } + + pub fn valid_params(mut self, params: serde_json::Value) -> Self { + self.valid_params.push(params); + self + } + + pub fn invalid_params(mut self, params: serde_json::Value) -> Self { + self.invalid_params.push(params); + self + } + + /// The size of the request sent at the cap; the Guardian's default unless the operator + /// raises `GUARDIAN_MODULE_REQUEST_MAX_BYTES`. + pub fn request_max_bytes(mut self, bytes: usize) -> Self { + self.request_max_bytes = bytes; + self + } + + pub async fn run(self) -> Report { + let mut report = Report::default(); + if self.requests.is_empty() { + report.fail("setup", "", "the suite needs at least one request"); + } + if !self + .expected + .iter() + .any(|expected| matches!(expected, Some(Expected::Deny | Expected::DenyWith(_)))) + { + report.fail( + "setup", + "", + "the suite needs at least one request the module must deny (`denies` or `denies_with`): a module that refuses nothing would conform otherwise", + ); + } + if self.valid_params.is_empty() { + report.fail( + "setup", + "", + "the suite needs at least one valid params value", + ); + } + let (channel, shutdown) = match self.start_remote().await { + Ok(started) => started, + Err(detail) => { + report.fail("setup", "", detail); + return report; + } + }; + let remote = Remote { + client: GuardianModuleClient::new(channel), + }; + self.check_describe(&remote, &mut report).await; + self.check_params(&remote, &mut report).await; + let baseline = self.check_transport(&remote, &mut report).await; + self.check_decisions(&baseline, &mut report); + self.check_expectations(&baseline, &mut report); + self.check_purity(&baseline, &mut report).await; + self.check_instances(&remote, &baseline, &mut report).await; + self.check_size_cap(&remote, &mut report).await; + let _ = shutdown.send(()); + report + } + + async fn start_remote(&self) -> Result<(Channel, oneshot::Sender<()>), String> { + let listener = TcpListener::bind("127.0.0.1:0") + .await + .map_err(|e| format!("bind loopback: {e}"))?; + let addr = listener + .local_addr() + .map_err(|e| format!("loopback address: {e}"))?; + let service = serve(Arc::clone(&self.module)) + .instance(INSTANCE_A, TOKEN_A) + .instance(INSTANCE_B, TOKEN_B) + .into_service(); + let (shutdown, stopped) = oneshot::channel::<()>(); + tokio::spawn(async move { + let _ = Server::builder() + .add_service(service) + .serve_with_incoming_shutdown(TcpIncoming::from(listener), async { + let _ = stopped.await; + }) + .await; + }); + let channel = Channel::from_shared(format!("http://{addr}")) + .map_err(|e| e.to_string())? + .connect() + .await + .map_err(|e| format!("connect to the served module: {e}"))?; + Ok((channel, shutdown)) + } + + async fn check_describe(&self, remote: &Remote, report: &mut Report) { + let guardian = DescribeRequest { + guardian_protocol_version: PROTOCOL_VERSION, + guardian_min_protocol_version: PROTOCOL_VERSION, + guardian_capabilities: Vec::new(), + }; + let local = match self.module.describe(&guardian).await { + Ok(info) => info, + Err(error) => { + report.fail("describe", "", format!("in process: {error}")); + return; + } + }; + if local.protocol_version != PROTOCOL_VERSION { + report.fail( + "describe", + "", + format!( + "protocol_version {} is not {PROTOCOL_VERSION}", + local.protocol_version + ), + ); + } + if local.name.is_empty() { + report.fail("describe", "", "name is empty"); + } + if local.hooks.is_empty() { + report.fail("describe", "", "declares no hooks"); + } + for hook in &local.hooks { + if !matches!(Hook::try_from(*hook), Ok(known) if known != Hook::Unspecified) { + report.fail("describe", "", format!("declares unknown hook {hook}")); + } + } + match remote.describe(guardian).await { + Ok(served) if served == local => {} + Ok(served) => report.fail( + "describe", + "", + format!("over gRPC {served:?}, in process {local:?}"), + ), + Err(code) => report.fail("describe", "", format!("over gRPC: {code:?}")), + } + } + + async fn check_params(&self, remote: &Remote, report: &mut Report) { + for params in &self.valid_params { + let case = params.to_string(); + let Some(verdict) = self.validate_both(remote, params, &case, report).await else { + continue; + }; + if !verdict.ok { + report.fail("params", &case, format!("refused: {}", verdict.message)); + continue; + } + if verdict.normalized_params.is_empty() { + continue; + } + let normalized = + match serde_json::from_slice::(&verdict.normalized_params) { + Ok(value) if value.is_object() => value, + _ => { + report.fail("params", &case, "normalized_params is not a JSON object"); + continue; + } + }; + match self.module.validate_params(&json_bytes(&normalized)).await { + Ok(again) if again.ok && normalizes_to(&again, &normalized) => {} + Ok(again) => report.fail( + "params", + &case, + format!("normalized params do not validate to themselves: {again:?}"), + ), + Err(error) => report.fail("params", &case, format!("normalized params: {error}")), + } + } + for params in &self.invalid_params { + let case = params.to_string(); + let Some(verdict) = self.validate_both(remote, params, &case, report).await else { + continue; + }; + if verdict.ok { + report.fail("params", &case, "accepted params the suite marks invalid"); + } else if verdict.message.is_empty() { + report.fail("params", &case, "a refusal carries no message"); + } + } + } + + async fn validate_both( + &self, + remote: &Remote, + params: &serde_json::Value, + case: &str, + report: &mut Report, + ) -> Option { + let bytes = json_bytes(params); + let local = match self.module.validate_params(&bytes).await { + Ok(verdict) => verdict, + Err(error) => { + report.fail("params", case, format!("in process: {error}")); + return None; + } + }; + match remote.validate(INSTANCE_A, TOKEN_A, bytes).await { + Ok(served) if served == local => {} + Ok(served) => report.fail( + "params", + case, + format!("over gRPC {served:?}, in process {local:?}"), + ), + Err(code) => report.fail("params", case, format!("over gRPC: {code:?}")), + } + Some(local) + } + + async fn check_transport(&self, remote: &Remote, report: &mut Report) -> Vec { + let mut baseline = Vec::with_capacity(self.requests.len()); + for (name, request) in &self.requests { + let request = for_instance(request, INSTANCE_A); + let local = evaluate_local(&self.module, &request).await; + let served = remote.evaluate(TOKEN_A, request).await; + if served != local { + report.fail( + "transport", + name, + format!("over gRPC {served:?}, in process {local:?}"), + ); + } + baseline.push(local); + } + baseline + } + + fn check_decisions(&self, baseline: &[Outcome], report: &mut Report) { + for ((name, _), outcome) in self.requests.iter().zip(baseline) { + let Ok(decision) = outcome else { continue }; + if let Err(detail) = well_formed(decision) { + report.fail("decision", name, detail); + } + } + } + + fn check_expectations(&self, baseline: &[Outcome], report: &mut Report) { + for (((name, _), expected), outcome) in + self.requests.iter().zip(&self.expected).zip(baseline) + { + let Some(expected) = expected else { continue }; + if !expected.met_by(outcome) { + report.fail( + "expectation", + name, + format!("expected {expected}, got {outcome:?}"), + ); + } + } + } + + async fn check_purity(&self, baseline: &[Outcome], report: &mut Report) { + for ((name, request), expected) in self.requests.iter().zip(baseline) { + let request = for_instance(request, INSTANCE_A); + for _ in 0..REPEATS { + let again = evaluate_local(&self.module, &request).await; + if &again != expected { + report.fail( + "purity", + name, + format!("repeated: {again:?}, first {expected:?}"), + ); + break; + } + } + } + for ((name, request), expected) in self.requests.iter().zip(baseline).rev() { + let again = evaluate_local(&self.module, &for_instance(request, INSTANCE_A)).await; + if &again != expected { + report.fail( + "purity", + name, + format!("in reverse order: {again:?}, first {expected:?}"), + ); + } + } + let mut concurrent = JoinSet::new(); + for _ in 0..REPEATS { + for (index, (_, request)) in self.requests.iter().enumerate() { + let module = Arc::clone(&self.module); + let request = for_instance(request, INSTANCE_A); + concurrent.spawn(async move { (index, evaluate_local(&module, &request).await) }); + } + } + while let Some(joined) = concurrent.join_next().await { + match joined { + Ok((index, outcome)) if outcome != baseline[index] => report.fail( + "purity", + &self.requests[index].0, + format!("concurrently: {outcome:?}, first {:?}", baseline[index]), + ), + Ok(_) => {} + Err(error) => report.fail("purity", "", format!("evaluation panicked: {error}")), + } + } + } + + async fn check_instances(&self, remote: &Remote, baseline: &[Outcome], report: &mut Report) { + for (name, request) in &self.requests { + let request = for_instance(request, INSTANCE_B); + let local = evaluate_local(&self.module, &request).await; + let served = remote.evaluate(TOKEN_B, request).await; + if served != local { + report.fail( + "instances", + name, + format!("second instance over gRPC {served:?}, in process {local:?}"), + ); + } + } + for ((name, request), expected) in self.requests.iter().zip(baseline) { + let again = remote + .evaluate(TOKEN_A, for_instance(request, INSTANCE_A)) + .await; + if &again != expected { + report.fail( + "instances", + name, + format!("after the second instance ran: {again:?}, first {expected:?}"), + ); + } + } + let Some((name, request)) = self.requests.first() else { + return; + }; + let crossed = remote + .evaluate(TOKEN_A, for_instance(request, INSTANCE_B)) + .await; + if crossed != Err(tonic::Code::PermissionDenied) { + report.fail( + "instances", + name, + format!("one instance's token used for another: {crossed:?}"), + ); + } + let anonymous = remote + .evaluate_unauthenticated(for_instance(request, INSTANCE_A)) + .await; + if anonymous != Err(tonic::Code::Unauthenticated) { + report.fail("instances", name, format!("no token: {anonymous:?}")); + } + } + + async fn check_size_cap(&self, remote: &Remote, report: &mut Report) { + let Some((name, request)) = self.requests.first() else { + return; + }; + let padded = at_size(for_instance(request, INSTANCE_A), self.request_max_bytes); + let case = format!("{name} at {} bytes", prost::Message::encoded_len(&padded)); + let local = evaluate_local(&self.module, &padded).await; + let served = remote.evaluate(TOKEN_A, padded).await; + if served != local { + report.fail( + "size cap", + &case, + format!("over gRPC {served:?}, in process {local:?}"), + ); + } + } +} + +struct Remote { + client: GuardianModuleClient, +} + +impl Remote { + async fn describe(&self, guardian: DescribeRequest) -> Result { + self.client + .clone() + .describe(authorized(guardian, TOKEN_A)) + .await + .map(tonic::Response::into_inner) + .map_err(|status| status.code()) + } + + async fn validate( + &self, + instance_id: &str, + token: &str, + params: Vec, + ) -> Result { + let request = ValidateParamsRequest { + instance_id: instance_id.into(), + params, + }; + self.client + .clone() + .validate_params(authorized(request, token)) + .await + .map(tonic::Response::into_inner) + .map_err(|status| status.code()) + } + + async fn evaluate(&self, token: &str, request: HookRequest) -> Outcome { + self.client + .clone() + .evaluate(authorized(request, token)) + .await + .map(tonic::Response::into_inner) + .map_err(|status| status.code()) + } + + async fn evaluate_unauthenticated(&self, request: HookRequest) -> Outcome { + self.client + .clone() + .evaluate(Request::new(request)) + .await + .map(tonic::Response::into_inner) + .map_err(|status| status.code()) + } +} + +/// What the suite found; empty when the module conforms. +#[derive(Debug, Default)] +pub struct Report { + failures: Vec, +} + +impl Report { + pub fn failures(&self) -> &[Failure] { + &self.failures + } + + pub fn is_conformant(&self) -> bool { + self.failures.is_empty() + } + + /// Panics with every failure when the module does not conform. + pub fn assert_conformant(&self) { + assert!(self.is_conformant(), "module does not conform:\n{self}"); + } + + fn fail(&mut self, check: &'static str, case: &str, detail: impl Into) { + self.failures.push(Failure { + check, + case: case.to_string(), + detail: detail.into(), + }); + } +} + +impl fmt::Display for Report { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + for failure in &self.failures { + writeln!(f, "{failure}")?; + } + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Failure { + /// `setup`, `describe`, `params`, `transport`, `decision`, `purity`, `instances` or + /// `size cap`. + pub check: &'static str, + pub case: String, + pub detail: String, +} + +impl fmt::Display for Failure { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + if self.case.is_empty() { + write!(f, "[{}] {}", self.check, self.detail) + } else { + write!(f, "[{}] {}: {}", self.check, self.case, self.detail) + } + } +} + +async fn evaluate_local(module: &M, request: &HookRequest) -> Outcome { + module + .evaluate(request) + .await + .map_err(|error| status(error).code()) +} + +fn authorized(message: T, token: &str) -> Request { + let mut request = Request::new(message); + if let Ok(value) = MetadataValue::try_from(format!("Bearer {token}")) { + request.metadata_mut().insert("authorization", value); + } + request +} + +fn for_instance(request: &HookRequest, instance_id: &str) -> HookRequest { + HookRequest { + instance_id: instance_id.into(), + ..request.clone() + } +} + +fn json_bytes(value: &serde_json::Value) -> Vec { + serde_json::to_vec(value).unwrap_or_default() +} + +fn normalizes_to(verdict: &ParamsVerdict, normalized: &serde_json::Value) -> bool { + verdict.normalized_params.is_empty() + || serde_json::from_slice::(&verdict.normalized_params) + .is_ok_and(|again| &again == normalized) +} + +fn well_formed(decision: &Decision) -> Result<(), String> { + let allowed = match Effect::try_from(decision.effect) { + Ok(Effect::Unspecified) => return Err("the decision sets no effect".into()), + Ok(Effect::Allow) => true, + Ok(Effect::Deny) => false, + Err(_) => return Err(format!("unknown effect {}", decision.effect)), + }; + if !allowed && !is_valid_reason_code(&decision.reason_code) { + return Err(format!( + "a deny needs a reason_code of 1 to 64 lowercase letters, digits or underscores, got {:?}", + decision.reason_code + )); + } + if decision.client_message.chars().count() > CLIENT_MESSAGE_MAX_CHARS { + return Err(format!( + "client_message is longer than {CLIENT_MESSAGE_MAX_CHARS} characters" + )); + } + if decision.client_message.chars().any(char::is_control) { + return Err("client_message contains control characters".into()); + } + Ok(()) +} + +/// Pads `request` to `target` encoded bytes: a transaction request through a `raw` payload the +/// module cannot mistake for a real encoding, a registration request through its `request_id`. +fn at_size(mut request: HookRequest, target: usize) -> HookRequest { + let pad = |request: &mut HookRequest, len: usize| match request.subject.as_mut() { + Some(hook_request::Subject::Transaction(transaction)) => { + transaction.raw = Some(RawTransaction { + encoding: PADDING_ENCODING.into(), + data: vec![0; len], + }); + } + _ => request.request_id = "r".repeat(len), + }; + pad(&mut request, 0); + let mut len = target.saturating_sub(prost::Message::encoded_len(&request)); + pad(&mut request, len); + while prost::Message::encoded_len(&request) > target && len > 0 { + len -= 1; + pad(&mut request, len); + } + request +} + +#[cfg(test)] +mod tests { + use std::sync::atomic::{AtomicU64, Ordering}; + + use async_trait::async_trait; + use serde_json::json; + + use super::*; + use crate::{ModuleError, ModuleInfo, TransactionSubject}; + + fn transaction() -> HookRequest { + HookRequest { + params: b"{}".to_vec(), + subject: Some(hook_request::Subject::Transaction( + TransactionSubject::default(), + )), + ..Default::default() + } + } + + fn info() -> ModuleInfo { + ModuleInfo { + name: "test".into(), + version: "0".into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![Hook::BeforeTransactionApproved as i32], + ..Default::default() + } + } + + struct Fixed(Decision); + + #[async_trait] + impl Module for Fixed { + async fn describe(&self, _: &DescribeRequest) -> Result { + Ok(info()) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(if params == b"{}" { + ParamsVerdict::ok() + } else { + ParamsVerdict::invalid("only {}") + }) + } + + async fn evaluate(&self, _: &HookRequest) -> Result { + Ok(self.0.clone()) + } + } + + struct Counting(AtomicU64); + + #[async_trait] + impl Module for Counting { + async fn describe(&self, _: &DescribeRequest) -> Result { + Ok(info()) + } + + async fn validate_params(&self, _: &[u8]) -> Result { + Ok(ParamsVerdict::ok()) + } + + async fn evaluate(&self, _: &HookRequest) -> Result { + if self.0.fetch_add(1, Ordering::SeqCst) < 2 { + Ok(Decision::allow()) + } else { + Ok(Decision::deny("limit", "over the limit")) + } + } + } + + fn suite(module: M) -> Suite { + Suite::new(module) + .denies("payment", transaction()) + .valid_params(json!({})) + .invalid_params(json!({ "x": 1 })) + } + + fn checks(report: &Report) -> Vec<&'static str> { + let mut checks: Vec<_> = report.failures().iter().map(|f| f.check).collect(); + checks.dedup(); + checks + } + + #[tokio::test] + async fn a_well_behaved_module_conforms() { + suite(Fixed(Decision::deny("blocked", "no"))) + .run() + .await + .assert_conformant(); + } + + #[tokio::test] + async fn a_module_that_allows_everything_does_not_conform() { + let always_allows = || Fixed(Decision::allow()); + let unstated = Suite::new(always_allows()) + .request("payment", transaction()) + .valid_params(json!({})) + .invalid_params(json!({ "x": 1 })) + .run() + .await; + assert_eq!(checks(&unstated), vec!["setup"], "{unstated}"); + + let stated = suite(always_allows()).run().await; + assert_eq!(checks(&stated), vec!["expectation"], "{stated}"); + } + + #[tokio::test] + async fn each_expectation_is_checked() { + let denies = || Fixed(Decision::deny("blocked", "no")); + let wrong_code = Suite::new(denies()) + .denies_with("payment", transaction(), "amount_cap_exceeded") + .valid_params(json!({})) + .invalid_params(json!({ "x": 1 })) + .run() + .await; + assert_eq!(checks(&wrong_code), vec!["expectation"], "{wrong_code}"); + + let wrong_outcome = suite(denies()) + .allows("allowed payment", transaction()) + .fails("unjudgeable payment", transaction()) + .run() + .await; + assert_eq!(wrong_outcome.failures().len(), 2, "{wrong_outcome}"); + assert_eq!( + checks(&wrong_outcome), + vec!["expectation"], + "{wrong_outcome}" + ); + + suite(denies()) + .denies_with("coded payment", transaction(), "blocked") + .run() + .await + .assert_conformant(); + } + + #[tokio::test] + async fn counting_in_evaluate_is_caught() { + let report = suite(Counting(AtomicU64::new(0))).run().await; + assert!(checks(&report).contains(&"purity"), "{report}"); + } + + #[tokio::test] + async fn a_malformed_deny_is_caught() { + let report = suite(Fixed(Decision::deny("Not Valid", "no"))).run().await; + assert_eq!(checks(&report), vec!["decision"], "{report}"); + let long = Decision::deny("ok", "no").with_client_message("x".repeat(257)); + let report = suite(Fixed(long)).run().await; + assert_eq!(checks(&report), vec!["decision"], "{report}"); + } + + #[tokio::test] + async fn accepting_invalid_params_is_caught() { + let report = Suite::new(Counting(AtomicU64::new(0))) + .denies("payment", transaction()) + .valid_params(json!({})) + .invalid_params(json!({ "x": 1 })) + .run() + .await; + assert!(checks(&report).contains(&"params"), "{report}"); + } + + #[test] + fn padding_reaches_the_cap() { + for target in [4_096, DEFAULT_REQUEST_MAX_BYTES] { + let padded = at_size(transaction(), target); + let size = prost::Message::encoded_len(&padded); + assert!(size <= target && size + 2 >= target, "{size} for {target}"); + let registration = at_size(HookRequest::default(), target); + let size = prost::Message::encoded_len(®istration); + assert!(size <= target && size + 2 >= target, "{size} for {target}"); + } + } +} diff --git a/crates/guardian-module-sdk/src/lib.rs b/crates/guardian-module-sdk/src/lib.rs new file mode 100644 index 000000000..db0b307f8 --- /dev/null +++ b/crates/guardian-module-sdk/src/lib.rs @@ -0,0 +1,336 @@ +//! Interface, protocol types and serving harness for Guardian policy modules. + +use std::sync::Arc; + +#[cfg(feature = "conformance")] +pub mod conformance; +pub mod policies; +pub mod serve; + +pub use async_trait::async_trait; +pub use prost_types; +pub use secrecy; + +#[allow(clippy::large_enum_variant)] +pub mod proto { + tonic::include_proto!("guardian.module.v1"); +} + +pub use proto::{ + AccountStateProjection, AccountView, Asset, Decision, DescribeRequest, Direction, Effect, Hook, + HookRequest, InputNote, MidenAccountState, MidenTransaction, ModuleInfo, NoteType, OutputNote, + ParamsVerdict, RawTransaction, RegistrationSubject, StorageChange, StorageOp, StorageSlotKind, + TransactionProjection, TransactionSubject, ValidateParamsRequest, VaultChange, +}; + +pub const PROTOCOL_VERSION: u32 = 1; + +/// The Guardian's default cap on an encoded `HookRequest`. A module's server must accept +/// requests at least this large. +pub const DEFAULT_REQUEST_MAX_BYTES: usize = 2 * 1024 * 1024; + +/// Optional protocol features, named in `DescribeRequest.guardian_capabilities` and +/// `ModuleInfo.required_capabilities`. New features are added as capabilities, not as a new +/// protocol version, so modules and Guardians of one major version keep working together. +pub mod capability { + /// `ParamsVerdict.normalized_params` is stored. + pub const PARAMS_NORMALIZATION: &str = "params.normalization"; +} + +#[derive(Debug, thiserror::Error)] +#[non_exhaustive] +pub enum ModuleError { + #[error("module unavailable: {0}")] + Unavailable(String), + #[error("invalid request: {0}")] + InvalidRequest(String), + #[error("module error: {0}")] + Internal(String), +} + +#[async_trait] +pub trait Module: Send + Sync { + /// `guardian` carries the Guardian's protocol range and capabilities. + async fn describe(&self, guardian: &DescribeRequest) -> Result; + + async fn validate_params(&self, params: &[u8]) -> Result; + + /// Must be free of side effects: the same transaction is evaluated at proposal creation + /// and again at approval, and clients retry. + async fn evaluate(&self, request: &HookRequest) -> Result; +} + +#[async_trait] +impl Module for Arc { + async fn describe(&self, guardian: &DescribeRequest) -> Result { + (**self).describe(guardian).await + } + + async fn validate_params(&self, params: &[u8]) -> Result { + (**self).validate_params(params).await + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + (**self).evaluate(request).await + } +} + +#[derive(Debug, Clone)] +#[non_exhaustive] +pub struct ModuleInstanceConfig { + pub id: String, + pub kind: String, + pub endpoint: Option, + pub auth_token: Option, + pub tls: Option, + pub timeout: std::time::Duration, + /// The catalog params, with any `$secret` references unresolved. + pub params: serde_json::Value, + /// The values of the `$secret` references in `params`, by secret name. Only in-process + /// instances receive them; a remote module holds its own credentials. + pub secrets: std::collections::BTreeMap, +} + +impl ModuleInstanceConfig { + pub fn new( + id: impl Into, + kind: impl Into, + timeout: std::time::Duration, + params: serde_json::Value, + ) -> Self { + Self { + id: id.into(), + kind: kind.into(), + endpoint: None, + auth_token: None, + tls: None, + timeout, + params, + secrets: Default::default(), + } + } + + pub fn with_endpoint(mut self, endpoint: Option) -> Self { + self.endpoint = endpoint; + self + } + + pub fn with_auth_token(mut self, auth_token: Option) -> Self { + self.auth_token = auth_token; + self + } + + pub fn with_tls(mut self, tls: Option) -> Self { + self.tls = tls; + self + } + + pub fn with_secrets( + mut self, + secrets: std::collections::BTreeMap, + ) -> Self { + self.secrets = secrets; + self + } + + /// The value of the `{"$secret": name}` reference in this instance's params. + pub fn secret(&self, name: &str) -> Option<&secrecy::SecretString> { + self.secrets.get(name) + } +} + +/// TLS settings of a remote module: a private CA (the system roots when absent) and an +/// optional client identity for mutual TLS. +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct ModuleTls { + pub ca_pem: Option>, + pub client_identity: Option, +} + +impl ModuleTls { + pub fn new(ca_pem: Option>, client_identity: Option) -> Self { + Self { + ca_pem, + client_identity, + } + } +} + +#[derive(Debug, Clone)] +#[non_exhaustive] +pub struct ClientIdentity { + pub cert_pem: Vec, + pub key_pem: secrecy::SecretString, +} + +impl ClientIdentity { + pub fn new(cert_pem: Vec, key_pem: secrecy::SecretString) -> Self { + Self { cert_pem, key_pem } + } +} + +pub trait ModuleFactory: Send + Sync { + fn create(&self, instance: &ModuleInstanceConfig) -> Result, ModuleError>; +} + +impl TransactionProjection { + pub fn miden(transaction: MidenTransaction) -> Self { + Self { + network: Some(proto::transaction_projection::Network::Miden(transaction)), + } + } +} + +impl AccountStateProjection { + pub fn miden(state: MidenAccountState) -> Self { + Self { + network: Some(proto::account_state_projection::Network::Miden(state)), + } + } +} + +impl RawTransaction { + /// `encoding` of a Miden `TransactionSummary` in Miden's binary serialization. + pub const MIDEN_TRANSACTION_SUMMARY: &str = "miden.transaction_summary"; +} + +fn miden_transaction(projection: &Option) -> Option<&MidenTransaction> { + match projection.as_ref()?.network.as_ref()? { + proto::transaction_projection::Network::Miden(transaction) => Some(transaction), + } +} + +impl TransactionSubject { + /// The Miden projection, when this is a Miden transaction. + pub fn miden(&self) -> Option<&MidenTransaction> { + miden_transaction(&self.projection) + } +} + +impl RegistrationSubject { + /// The Miden account state, when this is a Miden account. + pub fn miden(&self) -> Option<&MidenAccountState> { + match self.initial_state.as_ref()?.network.as_ref()? { + proto::account_state_projection::Network::Miden(state) => Some(state), + } + } +} + +impl Decision { + pub fn allow() -> Self { + Self { + reason_code: String::new(), + message: String::new(), + effect: Effect::Allow as i32, + client_message: String::new(), + } + } + + pub fn deny(reason_code: impl Into, message: impl Into) -> Self { + Self { + reason_code: reason_code.into(), + message: message.into(), + effect: Effect::Deny as i32, + client_message: String::new(), + } + } + + /// Whether this decision allows the request. + pub fn allows(&self) -> bool { + self.effect == Effect::Allow as i32 + } + + /// Text for the person who sent the request. The Guardian forwards it only for instances + /// whose catalog entry allows it, as plain text of at most 256 characters. + pub fn with_client_message(mut self, client_message: impl Into) -> Self { + self.client_message = client_message.into(); + self + } +} + +impl ParamsVerdict { + pub fn ok() -> Self { + Self { + ok: true, + message: String::new(), + normalized_params: Vec::new(), + } + } + + pub fn invalid(message: impl Into) -> Self { + Self { + ok: false, + message: message.into(), + normalized_params: Vec::new(), + } + } + + /// Valid, and to be stored in the module's current shape: `params` is what the Guardian + /// keeps instead of what the operator or an older catalog sent. + pub fn normalized(params: &serde_json::Value) -> Self { + Self { + ok: true, + message: String::new(), + normalized_params: serde_json::to_vec(params).unwrap_or_default(), + } + } +} + +pub fn is_valid_reason_code(code: &str) -> bool { + (1..=64).contains(&code.len()) + && code + .bytes() + .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_') +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn instance_config_debug_redacts_the_token() { + let config = ModuleInstanceConfig { + id: "remote".into(), + kind: "grpc".into(), + endpoint: None, + auth_token: Some(secrecy::SecretString::from("very-secret-token")), + tls: Some(ModuleTls { + ca_pem: None, + client_identity: Some(ClientIdentity { + cert_pem: Vec::new(), + key_pem: secrecy::SecretString::from("very-secret-key"), + }), + }), + timeout: std::time::Duration::from_millis(10), + params: serde_json::json!({}), + secrets: [( + "k".to_string(), + secrecy::SecretString::from("very-secret-param"), + )] + .into(), + }; + let debug = format!("{config:?}"); + assert!(!debug.contains("very-secret-token")); + assert!(!debug.contains("very-secret-key")); + assert!(!debug.contains("very-secret-param")); + } + + #[test] + fn the_miden_accessors_read_only_the_miden_variant() { + assert!(TransactionSubject::default().miden().is_none()); + let subject = TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + nonce_delta: 1, + ..Default::default() + })), + ..Default::default() + }; + assert_eq!(subject.miden().map(|miden| miden.nonce_delta), Some(1)); + assert!(RegistrationSubject::default().miden().is_none()); + let registration = RegistrationSubject { + initial_state: Some(AccountStateProjection::miden(MidenAccountState::default())), + }; + assert!(registration.miden().is_some()); + } +} diff --git a/crates/guardian-module-sdk/src/policies/code_policy.rs b/crates/guardian-module-sdk/src/policies/code_policy.rs new file mode 100644 index 000000000..0eb3ff89d --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/code_policy.rs @@ -0,0 +1,228 @@ +//! `code-policy`: which account code the account may run. + +use std::collections::BTreeSet; + +use async_trait::async_trait; +use serde::Deserialize; + +use super::{IdKind, Rule}; +use crate::proto::hook_request; +use crate::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, ParamsVerdict, +}; + +pub const KIND: &str = "code-policy"; + +const HOOKS: [Hook; 3] = [ + Hook::BeforeAccountRegistered, + Hook::BeforeProposalCreated, + Hook::BeforeTransactionApproved, +]; + +/// Which code `allowed` is checked against. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum CodeCheck { + /// The code an account registers with, and code a transaction replaces it with; an account + /// already on other code keeps working until it changes code. + #[default] + Changed, + /// The code the account runs after the registration or transaction, at every hook. + All, +} + +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + /// The account code commitments the account may run. + #[serde(default)] + pub allowed: Option>, + /// Which code `allowed` is checked against; `changed` unless set. Needs `allowed`. + #[serde(default)] + pub check: Option, +} + +struct Rules { + allowed: Option>, + check: CodeCheck, +} + +impl TryFrom for Rules { + type Error = String; + + fn try_from(params: Params) -> Result { + if params.check.is_some() && params.allowed.is_none() { + return Err("check applies to allowed, which is not set".into()); + } + Ok(Self { + allowed: params + .allowed + .as_deref() + .map(|list| super::ids("allowed", IdKind::Commitment, list)) + .transpose()?, + check: params.check.unwrap_or_default(), + }) + } +} + +impl Rules { + fn parse(params: &[u8]) -> Result { + super::parse::(params).and_then(Self::try_from) + } + + fn judge(&self, request: &HookRequest) -> Result { + let Some(allowed) = &self.allowed else { + return Ok(Decision::allow()); + }; + Ok(match self.checked(request)? { + Some(code) if !allowed.contains(&code.to_ascii_lowercase()) => { + Rule::Code.deny(format!("code {code} is not allowed")) + } + _ => Decision::allow(), + }) + } + + /// The code commitment `allowed` must list for this request, if any: under `changed` the + /// code an account registers with or a transaction replaces its code with, under `all` the + /// code the account runs after the request. + fn checked(&self, request: &HookRequest) -> Result, ModuleError> { + let after_code = || super::after(request).map(|after| after.code_commitment.clone()); + match (self.check, &request.subject) { + (CodeCheck::All, _) + | (CodeCheck::Changed, Some(hook_request::Subject::Registration(_))) => { + after_code().map(Some) + } + (CodeCheck::Changed, _) => Ok(super::transaction(request)?.new_code_commitment.clone()), + } + } +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct CodePolicy; + +#[async_trait] +impl Module for CodePolicy { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(super::info(KIND, &HOOKS)) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(super::verdict(params, Rules::parse(params), &[])) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + Rules::parse(&request.params) + .map_err(ModuleError::InvalidRequest)? + .judge(request) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::super::testing::*; + use super::*; + use crate::MidenTransaction; + + const REVIEWED: &str = "0x000000000000000000000000000000000000000000000000000000000000c0de"; + const UNREVIEWED: &str = "0x0000000000000000000000000000000000000000000000000000000000000bad"; + + async fn decide(request: &HookRequest) -> Decision { + CodePolicy.evaluate(request).await.unwrap() + } + + fn rule(check: &str) -> serde_json::Value { + json!({ "allowed": [REVIEWED], "check": check }) + } + + fn running(mut request: HookRequest, code: &str) -> HookRequest { + if let Some(after) = request.after.as_mut() { + after.code_commitment = code.into(); + } + request + } + + fn registration(params: serde_json::Value, code: &str) -> HookRequest { + running(registration_request(params, None, &[SIGNER]), code) + } + + fn replacing_code_with(code: Option<&str>) -> MidenTransaction { + MidenTransaction { + new_code_commitment: code.map(str::to_string), + ..Default::default() + } + } + + #[tokio::test] + async fn changed_check_judges_registration_and_code_replacement_only() { + let changed = rule("changed"); + assert!( + decide(®istration(changed.clone(), REVIEWED)) + .await + .allows() + ); + let refused = decide(®istration(changed.clone(), UNREVIEWED)).await; + assert_eq!(refused.reason_code, "code_not_allowed"); + assert!(!refused.client_message.contains(UNREVIEWED)); + + let unchanged = running( + tx_request(changed.clone(), replacing_code_with(None)), + UNREVIEWED, + ); + assert!( + decide(&unchanged).await.allows(), + "code an account already runs is kept until it changes" + ); + let upgrade = tx_request(changed.clone(), replacing_code_with(Some(UNREVIEWED))); + assert_eq!(decide(&upgrade).await.reason_code, "code_not_allowed"); + let reviewed = tx_request(changed, replacing_code_with(Some(REVIEWED))); + assert!(decide(&reviewed).await.allows()); + } + + #[tokio::test] + async fn all_check_judges_the_code_an_account_runs_at_every_hook() { + let all = rule("all"); + let unchanged = running( + tx_request(all.clone(), replacing_code_with(None)), + UNREVIEWED, + ); + assert_eq!(decide(&unchanged).await.reason_code, "code_not_allowed"); + let upgraded = running( + tx_request(all, replacing_code_with(Some(REVIEWED))), + REVIEWED, + ); + assert!( + decide(&upgraded).await.allows(), + "an account on unlisted code can still upgrade to listed code" + ); + } + + #[tokio::test] + async fn a_transaction_without_a_projection_is_not_judged_under_changed() { + let unprojected = without_projection(tx_request( + rule("changed"), + replacing_code_with(Some(UNREVIEWED)), + )); + assert!(matches!( + CodePolicy.evaluate(&unprojected).await, + Err(ModuleError::InvalidRequest(_)) + )); + } + + #[tokio::test] + async fn params_are_validated() { + for params in [ + json!({ "allowed": [REVIEWED], "check": "sometimes" }), + json!({ "allowed": [format!("0x{}", "c".repeat(63))] }), + json!({ "check": "all" }), + json!({ "allowed_code_commitments": [REVIEWED] }), + ] { + let verdict = CodePolicy + .validate_params(&serde_json::to_vec(¶ms).unwrap()) + .await + .unwrap(); + assert!(!verdict.ok, "{params}"); + } + } +} diff --git a/crates/guardian-module-sdk/src/policies/mod.rs b/crates/guardian-module-sdk/src/policies/mod.rs new file mode 100644 index 000000000..63eacb53a --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/mod.rs @@ -0,0 +1,420 @@ +//! First-party policies, one concern each, so an instance is configured with only the params of +//! the rule it enforces: +//! +//! | Kind | Judges | Hooks | +//! |---|---|---| +//! | [`spending-limit`](spending_limit) | Which assets a transaction moves and how much of each it sends | proposal creation, transaction approval | +//! | [`recipient-policy`](recipient_policy) | Who a transaction pays | proposal creation, transaction approval | +//! | [`signer-policy`](signer_policy) | Who may sign for the account | registration, proposal creation, transaction approval | +//! | [`code-policy`](code_policy) | Which account code the account may run | registration, proposal creation, transaction approval | +//! +//! Each kind refuses params that belong to another, and supports only the hooks where its rule +//! can refuse something, so a catalog that subscribes it to another hook does not start. An +//! instance with no rule configured allows without reading the request; one with a rule that +//! cannot read what it needs returns an error, so the instance's `on_error` applies. Every +//! denial carries a fixed reason code and a fixed client message that names the rule, never a +//! list entry or a limit; the details go only to the logged message. + +use std::collections::BTreeSet; + +use serde::de::DeserializeOwned; + +use crate::proto::hook_request; +use crate::{ + AccountView, Decision, Hook, HookRequest, MidenTransaction, ModuleError, ModuleInfo, + PROTOCOL_VERSION, ParamsVerdict, +}; + +pub mod code_policy; +pub mod recipient_policy; +pub mod signer_policy; +pub mod spending_limit; + +pub use code_policy::CodePolicy; +pub use recipient_policy::RecipientPolicy; +pub use signer_policy::SignerPolicy; +pub use spending_limit::SpendingLimit; + +/// Every first-party policy kind, as a catalog names it. +pub const KINDS: [&str; 4] = [ + spending_limit::KIND, + recipient_policy::KIND, + signer_policy::KIND, + code_policy::KIND, +]; + +/// What an id names, which fixes its length in the hex form the Guardian reports it in. +#[derive(Clone, Copy)] +pub(crate) enum IdKind { + /// A faucet or a recipient: an account id. + Account, + /// A signer commitment or a code commitment: a word. + Commitment, +} + +impl IdKind { + fn hex_digits(self) -> usize { + match self { + IdKind::Account => 30, + IdKind::Commitment => 64, + } + } + + fn noun(self) -> &'static str { + match self { + IdKind::Account => "an account id", + IdKind::Commitment => "a commitment", + } + } +} + +/// Ids in the hex form the Guardian reports them in (`0x` and the hex digits of an account id or +/// a commitment), lowercased; an account may also be named by its bech32 address, which is read +/// as its hex id. Any other spelling would never match a request, so a list or a cap would +/// silently not apply; it is refused instead: a placeholder left in an example catalog, an id +/// cut short when it was pasted, a bech32 address that is not an account's, or an account id +/// where a commitment belongs. +pub(crate) fn ids( + field: &str, + kind: IdKind, + values: &[String], +) -> Result, String> { + values.iter().map(|value| id(field, kind, value)).collect() +} + +pub(crate) fn id(field: &str, kind: IdKind, value: &str) -> Result { + let digits = value + .strip_prefix("0x") + .or_else(|| value.strip_prefix("0X")) + .filter(|rest| rest.bytes().all(|b| b.is_ascii_hexdigit())); + match (digits, kind) { + (Some(rest), _) if rest.len() == kind.hex_digits() => Ok(value.to_ascii_lowercase()), + (Some(rest), _) if !rest.is_empty() => Err(format!( + "{field}: {value:?} has {} hex digits, but {} has {}", + rest.len(), + kind.noun(), + kind.hex_digits() + )), + (None, IdKind::Account) => account_address(value).map_err(|refused| { + let why = match refused { + NotAnAccount::NotBech32 => { + "is neither an account id in 0x hex form nor a bech32 account address".into() + } + NotAnAccount::Routing => { + "has a routing part after `_` that is not valid bech32m".into() + } + NotAnAccount::Type(address_type) => { + format!("is a bech32 address of type {address_type}, not of an account id") + } + NotAnAccount::Length(bytes) => format!( + "is a bech32 account address of {bytes} bytes, but an account id has {}", + IdKind::Account.hex_digits() / 2 + ), + }; + format!("{field}: {value:?} {why}") + }), + _ => Err(format!( + "{field}: {value:?} is not {} in 0x hex form", + kind.noun() + )), + } +} + +/// The address type byte of a Miden account address. +const ACCOUNT_ADDRESS: u8 = 232; + +/// The prefix Miden checksums an address's routing part under (it is written without it). +const ROUTING_PREFIX: &str = "mrp1"; + +/// Why a string is not a Miden bech32m account address. +enum NotAnAccount { + /// Not a bech32m string at all. + NotBech32, + /// The part after `_` is empty or fails its checksum, which Miden refuses too. + Routing, + /// An address of another type. + Type(u8), + /// An account address whose id has this many bytes. + Length(usize), +} + +/// The hex id of the account a Miden bech32m address names, `[_]`. The +/// routing part is checked as Miden checks it, then set aside: it says how to reach the +/// account, not which account it is. +fn account_address(value: &str) -> Result { + fn checked(text: &str) -> Option> { + bech32::primitives::decode::CheckedHrpstring::new::(text).ok() + } + let (identifier, routing) = value + .split_once('_') + .map_or((value, None), |(identifier, routing)| { + (identifier, Some(routing)) + }); + let bytes: Vec = checked(identifier) + .ok_or(NotAnAccount::NotBech32)? + .byte_iter() + .collect(); + if let Some(routing) = routing { + checked(&format!("{ROUTING_PREFIX}{routing}")).ok_or(NotAnAccount::Routing)?; + } + match bytes.split_first() { + Some((&ACCOUNT_ADDRESS, id)) if id.len() * 2 == IdKind::Account.hex_digits() => { + Ok(format!( + "0x{}", + id.iter().map(|b| format!("{b:02x}")).collect::() + )) + } + Some((&ACCOUNT_ADDRESS, id)) => Err(NotAnAccount::Length(id.len())), + Some((&address_type, _)) => Err(NotAnAccount::Type(address_type)), + None => Err(NotAnAccount::NotBech32), + } +} + +/// Where a kind's params name accounts: entries of a list, or the keys of a map. +pub(crate) enum Accounts { + List(&'static str), + Keys(&'static str), +} + +/// `params` with every account named by its bech32 address rewritten to its hex id, so stored +/// params, their history and their disclosure show the id requests carry; `None` when no entry +/// needed it, so params already in hex are stored as sent. +fn hex_accounts(params: &[u8], accounts: &[Accounts]) -> Option { + let hex = |value: &str| account_address(value).ok(); + let mut value: serde_json::Value = serde_json::from_slice(params).ok()?; + let mut changed = false; + for field in accounts { + match field { + Accounts::List(name) => { + let entries = value + .get_mut(*name) + .and_then(serde_json::Value::as_array_mut); + for entry in entries.into_iter().flatten() { + if let Some(id) = entry.as_str().and_then(hex) { + *entry = id.into(); + changed = true; + } + } + } + Accounts::Keys(name) => { + let Some(map) = value + .get_mut(*name) + .and_then(serde_json::Value::as_object_mut) + else { + continue; + }; + let renamed: Vec<(String, String)> = map + .keys() + .filter_map(|key| hex(key).map(|id| (key.clone(), id))) + .collect(); + for (key, id) in renamed { + if let Some(entry) = map.remove(&key) { + map.insert(id, entry); + changed = true; + } + } + } + } + } + changed.then_some(value) +} + +pub(crate) fn normalized(values: &[String]) -> BTreeSet { + values.iter().map(|v| v.to_ascii_lowercase()).collect() +} + +/// A rule's denial. Each denies with a fixed reason code and a fixed client message that names +/// the rule, never a list entry or a limit, so a denial discloses no params. +#[derive(Debug, Clone, Copy)] +pub(crate) enum Rule { + RecipientAllowlist, + RecipientDenylist, + AssetAllowlist, + AmountCap, + Signers, + Code, +} + +impl Rule { + pub(crate) fn deny(self, logged: String) -> Decision { + let (reason_code, client_message) = match self { + Rule::RecipientAllowlist => ( + "recipient_not_allowed", + "A payment goes to a recipient this Guardian does not accept.", + ), + Rule::RecipientDenylist => ( + "recipient_blocked", + "A payment goes to a recipient this Guardian blocks.", + ), + Rule::AssetAllowlist => ( + "asset_not_allowed", + "The transaction moves an asset this Guardian does not accept.", + ), + Rule::AmountCap => ( + "amount_cap_exceeded", + "The transaction sends more than this Guardian allows per transaction.", + ), + Rule::Signers => ( + "signer_not_allowed", + "The account would have a signer this Guardian does not accept.", + ), + Rule::Code => ( + "code_not_allowed", + "The account would run code this Guardian does not accept.", + ), + }; + Decision::deny(reason_code, logged).with_client_message(client_message) + } +} + +/// The params as a kind reads them: absent bytes are no params, anything else must be a JSON +/// object of that kind's fields only. +pub(crate) fn parse(params: &[u8]) -> Result { + if params.is_empty() { + Ok(P::default()) + } else { + serde_json::from_slice(params).map_err(|e| e.to_string()) + } +} + +/// The verdict on `params` as a kind parsed them; valid params that name an account in +/// `accounts` by its bech32 address come back normalized to the hex id. +pub(crate) fn verdict( + params: &[u8], + parsed: Result, + accounts: &[Accounts], +) -> ParamsVerdict { + match parsed { + Ok(_) => hex_accounts(params, accounts) + .map(|normalized| ParamsVerdict::normalized(&normalized)) + .unwrap_or_else(ParamsVerdict::ok), + Err(message) => ParamsVerdict::invalid(message), + } +} + +pub(crate) fn info(kind: &str, hooks: &[Hook]) -> ModuleInfo { + ModuleInfo { + name: kind.into(), + version: env!("CARGO_PKG_VERSION").into(), + protocol_version: PROTOCOL_VERSION, + hooks: hooks.iter().map(|hook| *hook as i32).collect(), + ..Default::default() + } +} + +/// The transaction a request asks about, in its Miden projection. A request that carries no +/// transaction, or no projection this module can read, is not judged: it is an error, so the +/// instance's `on_error` applies, never an allow. +pub(crate) fn transaction(request: &HookRequest) -> Result<&MidenTransaction, ModuleError> { + match &request.subject { + Some(hook_request::Subject::Transaction(tx)) => tx.miden().ok_or_else(|| { + ModuleError::InvalidRequest("transaction has no Miden projection to judge".into()) + }), + Some(hook_request::Subject::Registration(_)) => Err(ModuleError::InvalidRequest( + "this policy judges transactions, not registrations".into(), + )), + None => Err(ModuleError::InvalidRequest("request has no subject".into())), + } +} + +/// The account as it will be if every module allows; a request without it is not judged. +pub(crate) fn after(request: &HookRequest) -> Result<&AccountView, ModuleError> { + request + .after + .as_ref() + .ok_or_else(|| ModuleError::InvalidRequest("request has no account view".into())) +} + +#[cfg(test)] +pub(crate) mod testing { + use crate::proto::{asset, hook_request}; + use crate::{ + AccountView, Asset, HookRequest, MidenTransaction, OutputNote, RegistrationSubject, + TransactionProjection, TransactionSubject, + }; + + pub const USDC: &str = "0x00000000000000000000000000aa00"; + pub const ETH: &str = "0x00000000000000000000000000bb00"; + pub const RECIPIENT: &str = "0x0000000000000000000000000000a1"; + pub const SIGNER: &str = "0x0000000000000000000000000000000000000000000000000000000000000051"; + /// An account id and its bech32 addresses, as `miden_protocol` encodes them: on devnet, and + /// on testnet with basic-wallet routing params. + pub const ADDRESSED: &str = "0x1fc2e85e8e2c2511561d4c1a78b478"; + pub const DEVNET_ADDRESS: &str = "mdev1aq0u96z73ckz2y2kr4xp57950qrn4xjc"; + pub const ROUTED_ADDRESS: &str = "mtst1aq0u96z73ckz2y2kr4xp57950qmexkt5_qr7qqq9wr6w"; + + /// A valid bech32m address of `address_type` (232 is an account) over `id_bytes` zero bytes. + pub fn address_of(address_type: u8, id_bytes: usize) -> String { + let mut payload = vec![address_type]; + payload.extend(vec![0u8; id_bytes]); + bech32::encode::(bech32::Hrp::parse("mdev").unwrap(), &payload).unwrap() + } + + pub fn fungible(faucet: &str, amount: u64) -> Asset { + Asset { + faucet_id: faucet.into(), + value: Some(asset::Value::FungibleAmount(amount.to_string())), + } + } + + pub fn p2id(target: &str, assets: Vec) -> OutputNote { + OutputNote { + note_id: format!("0xnote{target}"), + assets, + p2id_target: Some(target.into()), + ..Default::default() + } + } + + pub fn fee_note(amount: u64) -> OutputNote { + OutputNote { + note_id: "0xfee".into(), + assets: vec![fungible(USDC, amount)], + tx_fee: true, + ..Default::default() + } + } + + pub fn view(signers: &[&str]) -> AccountView { + AccountView { + signer_commitments: signers.iter().map(|s| s.to_string()).collect(), + ..Default::default() + } + } + + pub fn tx_request(params: serde_json::Value, projection: MidenTransaction) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + before: Some(view(&[SIGNER])), + after: Some(view(&[SIGNER])), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(projection)), + ..Default::default() + })), + ..Default::default() + } + } + + pub fn registration_request( + params: serde_json::Value, + before: Option<&[&str]>, + after: &[&str], + ) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + before: before.map(view), + after: Some(view(after)), + subject: Some(hook_request::Subject::Registration( + RegistrationSubject::default(), + )), + ..Default::default() + } + } + + pub fn without_projection(mut request: HookRequest) -> HookRequest { + if let Some(hook_request::Subject::Transaction(subject)) = &mut request.subject { + subject.projection = None; + } + request + } +} diff --git a/crates/guardian-module-sdk/src/policies/recipient_policy.rs b/crates/guardian-module-sdk/src/policies/recipient_policy.rs new file mode 100644 index 000000000..f25430c8e --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/recipient_policy.rs @@ -0,0 +1,387 @@ +//! `recipient-policy`: who a transaction may pay. + +use std::collections::BTreeSet; + +use async_trait::async_trait; +use serde::Deserialize; + +use super::{Accounts, IdKind, Rule}; +use crate::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, ParamsVerdict, +}; + +pub const KIND: &str = "recipient-policy"; + +const HOOKS: [Hook; 2] = [Hook::BeforeProposalCreated, Hook::BeforeTransactionApproved]; + +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + /// The only accounts a payment note may go to. A note whose recipient cannot be identified + /// (a partial note, or one that is neither P2ID nor P2IDE) is refused, since it cannot be + /// shown to go to a listed account. Excludes `denylist`. + #[serde(default)] + pub allowlist: Option>, + /// Accounts no payment note may go to. Excludes `allowlist`. + #[serde(default)] + pub denylist: Option>, + /// With `denylist`: whether a payment note whose recipient cannot be identified is refused. + /// Unset, it is refused whenever the denylist names anyone, since a blocked recipient could + /// otherwise be paid through a note the Guardian cannot read. + #[serde(default)] + pub deny_unknown: Option, +} + +enum Rules { + Any, + Allow(BTreeSet), + Deny { + blocked: BTreeSet, + deny_unknown: bool, + }, +} + +impl TryFrom for Rules { + type Error = String; + + fn try_from(params: Params) -> Result { + if params.deny_unknown.is_some() && params.denylist.is_none() { + return Err("deny_unknown applies to denylist, which is not set (an allowlist refuses unknown recipients already)".into()); + } + match (params.allowlist, params.denylist) { + (Some(_), Some(_)) => Err("allowlist and denylist are mutually exclusive".into()), + (Some(list), None) => Ok(Rules::Allow(super::ids( + "allowlist", + IdKind::Account, + &list, + )?)), + (None, Some(list)) => Ok(Rules::Deny { + deny_unknown: params.deny_unknown.unwrap_or(!list.is_empty()), + blocked: super::ids("denylist", IdKind::Account, &list)?, + }), + (None, None) => Ok(Rules::Any), + } + } +} + +impl Rules { + fn parse(params: &[u8]) -> Result { + super::parse::(params).and_then(Self::try_from) + } + + fn judge(&self, request: &HookRequest) -> Result { + if matches!(self, Rules::Any) { + return Ok(Decision::allow()); + } + let projection = super::transaction(request)?; + let payer = request.account_id.to_ascii_lowercase(); + let payments = projection.output_notes.iter().filter(|note| !note.tx_fee); + for note in payments { + let target = match (¬e.p2id_target, note.partial) { + (Some(target), false) => Some(target.to_ascii_lowercase()), + _ => None, + }; + let reclaimer = note + .reclaimer + .as_deref() + .map(str::to_ascii_lowercase) + .filter(|reclaimer| *reclaimer != payer); + let recipients = std::iter::once(target).chain(reclaimer.map(Some)); + if let Some(denial) = recipients + .filter_map(|recipient| self.refusal(¬e.note_id, recipient)) + .next() + { + return Ok(denial); + } + } + Ok(Decision::allow()) + } + + /// The denial for one account a payment note can reach (its P2ID target, or the reclaimer of + /// a reclaimable P2IDE note), `None` for a note whose recipient cannot be read. + fn refusal(&self, note_id: &str, recipient: Option) -> Option { + match (self, recipient) { + (Rules::Any, _) => None, + (Rules::Allow(_), None) => Some( + Rule::RecipientAllowlist.deny(format!("note {note_id} has no checkable recipient")), + ), + (Rules::Allow(allowed), Some(recipient)) => { + (!allowed.contains(&recipient)).then(|| { + Rule::RecipientAllowlist.deny(format!("recipient {recipient} is not allowed")) + }) + } + (Rules::Deny { deny_unknown, .. }, None) => deny_unknown.then(|| { + Rule::RecipientDenylist.deny(format!("note {note_id} has no checkable recipient")) + }), + (Rules::Deny { blocked, .. }, Some(recipient)) => blocked + .contains(&recipient) + .then(|| Rule::RecipientDenylist.deny(format!("recipient {recipient} is blocked"))), + } + } +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct RecipientPolicy; + +#[async_trait] +impl Module for RecipientPolicy { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(super::info(KIND, &HOOKS)) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(super::verdict( + params, + Rules::parse(params), + &[Accounts::List("allowlist"), Accounts::List("denylist")], + )) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + Rules::parse(&request.params) + .map_err(ModuleError::InvalidRequest)? + .judge(request) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::super::testing::*; + use super::*; + use crate::MidenTransaction; + + const BLOCKED: &str = "0x000000000000000000000000000bad"; + + async fn decide(request: &HookRequest) -> Decision { + RecipientPolicy.evaluate(request).await.unwrap() + } + + fn paying(notes: Vec) -> MidenTransaction { + MidenTransaction { + output_notes: notes, + ..Default::default() + } + } + + fn with_an_unreadable_note() -> MidenTransaction { + let mut partial = p2id(RECIPIENT, vec![fungible(USDC, 1)]); + partial.partial = true; + paying(vec![p2id(RECIPIENT, vec![fungible(USDC, 1)]), partial]) + } + + #[tokio::test] + async fn an_allowlist_refuses_unlisted_and_unreadable_recipients() { + let params = json!({ "allowlist": [RECIPIENT] }); + let listed = paying(vec![p2id( + "0x0000000000000000000000000000A1", + vec![fungible(USDC, 1)], + )]); + assert!(decide(&tx_request(params.clone(), listed)).await.allows()); + + assert_eq!( + decide(&tx_request(params.clone(), with_an_unreadable_note())) + .await + .reason_code, + "recipient_not_allowed" + ); + + let unlisted = paying(vec![p2id( + "0x0000000000000000000000000000a9", + vec![fungible(USDC, 1)], + )]); + assert_eq!( + decide(&tx_request(params, unlisted)).await.reason_code, + "recipient_not_allowed" + ); + } + + #[tokio::test] + async fn a_denylist_refuses_listed_recipients_and_by_default_unreadable_ones() { + let params = json!({ "denylist": ["0x000000000000000000000000000BAD"] }); + let blocked = paying(vec![fee_note(1), p2id(BLOCKED, vec![fungible(USDC, 1)])]); + assert_eq!( + decide(&tx_request(params.clone(), blocked)) + .await + .reason_code, + "recipient_blocked" + ); + assert_eq!( + decide(&tx_request(params, with_an_unreadable_note())) + .await + .reason_code, + "recipient_blocked", + "a recipient the denylist cannot check is refused: a blocked one could hide there" + ); + + let lenient = json!({ "denylist": [BLOCKED], "deny_unknown": false }); + assert!( + decide(&tx_request(lenient, with_an_unreadable_note())) + .await + .allows(), + "the operator opted out" + ); + + let nobody_listed = json!({ "denylist": [] }); + assert!( + decide(&tx_request(nobody_listed, with_an_unreadable_note())) + .await + .allows(), + "an empty denylist has nobody to hide" + ); + + let strict_anyway = json!({ "denylist": [], "deny_unknown": true }); + assert_eq!( + decide(&tx_request(strict_anyway, with_an_unreadable_note())) + .await + .reason_code, + "recipient_blocked" + ); + } + + #[tokio::test] + async fn the_fee_note_is_not_a_payment() { + let params = json!({ "allowlist": [RECIPIENT] }); + let projection = paying(vec![fee_note(5), p2id(RECIPIENT, vec![fungible(USDC, 5)])]); + assert!(decide(&tx_request(params, projection)).await.allows()); + } + + #[tokio::test] + async fn no_list_allows_and_a_request_it_cannot_judge_is_an_error() { + let projection = paying(vec![p2id(BLOCKED, vec![fungible(USDC, 1)])]); + assert!( + decide(&tx_request(json!({}), projection.clone())) + .await + .allows() + ); + assert!( + decide(&without_projection(tx_request( + json!({}), + projection.clone() + ))) + .await + .allows(), + "an instance with no rule allows without reading the transaction, like every kind" + ); + let unprojected = + without_projection(tx_request(json!({ "denylist": [BLOCKED] }), projection)); + assert!(matches!( + RecipientPolicy.evaluate(&unprojected).await, + Err(ModuleError::InvalidRequest(_)) + )); + } + + const PAYER: &str = "0x0000000000000000000000000000f1"; + + fn reclaimable(target: &str, reclaimer: &str) -> crate::OutputNote { + crate::OutputNote { + reclaimer: Some(reclaimer.into()), + ..p2id(target, vec![fungible(USDC, 1)]) + } + } + + async fn decide_for_payer(params: serde_json::Value, note: crate::OutputNote) -> Decision { + let mut request = tx_request(params, paying(vec![note])); + request.account_id = PAYER.to_uppercase().replace("0X", "0x"); + decide(&request).await + } + + #[tokio::test] + async fn the_reclaimer_of_a_reclaimable_note_is_judged_as_a_recipient() { + let denied = json!({ "denylist": [BLOCKED] }); + assert_eq!( + decide_for_payer(denied.clone(), reclaimable(RECIPIENT, BLOCKED)) + .await + .reason_code, + "recipient_blocked", + "a blocked account named as reclaimer can take the note" + ); + assert!( + decide_for_payer(denied, reclaimable(RECIPIENT, PAYER)) + .await + .allows(), + "the payer reclaiming its own note pays nobody" + ); + + let allowed = json!({ "allowlist": [RECIPIENT] }); + assert_eq!( + decide_for_payer(allowed.clone(), reclaimable(RECIPIENT, BLOCKED)) + .await + .reason_code, + "recipient_not_allowed", + "an allowed target does not cover an unlisted reclaimer" + ); + assert!( + decide_for_payer(allowed, reclaimable(RECIPIENT, PAYER)) + .await + .allows() + ); + } + + #[tokio::test] + async fn a_recipient_named_by_its_address_is_stored_and_matched_as_its_hex_id() { + let named = json!({ "denylist": [DEVNET_ADDRESS, ROUTED_ADDRESS] }); + let verdict = RecipientPolicy + .validate_params(&serde_json::to_vec(&named).unwrap()) + .await + .unwrap(); + assert!(verdict.ok, "{}", verdict.message); + assert_eq!( + serde_json::from_slice::(&verdict.normalized_params).unwrap(), + json!({ "denylist": [ADDRESSED, ADDRESSED] }) + ); + + let paid = paying(vec![p2id(ADDRESSED, vec![fungible(USDC, 1)])]); + assert_eq!( + decide(&tx_request(named, paid)).await.reason_code, + "recipient_blocked", + "params stored before normalization still match" + ); + + let allowed = json!({ "allowlist": [DEVNET_ADDRESS.to_uppercase()] }); + let verdict = RecipientPolicy + .validate_params(&serde_json::to_vec(&allowed).unwrap()) + .await + .unwrap(); + assert_eq!( + serde_json::from_slice::(&verdict.normalized_params).unwrap(), + json!({ "allowlist": [ADDRESSED] }), + "an address in upper case is the same address" + ); + + let hex = RecipientPolicy + .validate_params(&serde_json::to_vec(&json!({ "denylist": [BLOCKED] })).unwrap()) + .await + .unwrap(); + assert!( + hex.ok && hex.normalized_params.is_empty(), + "hex params are stored as sent" + ); + } + + #[tokio::test] + async fn params_are_validated() { + for params in [ + json!({ "denylist": ["mtst1qrkd5x7qy0mw0yqzlvqlqd3w9cafjkw"] }), + json!({ "denylist": [address_of(0, 15)] }), + json!({ "denylist": [address_of(232, 10)] }), + json!({ "denylist": [format!("{DEVNET_ADDRESS}_")] }), + json!({ "denylist": [format!("{DEVNET_ADDRESS}_garbage")] }), + json!({ "allowlist": [format!("{ROUTED_ADDRESS}_qr7qqq9wr6w")] }), + json!({ "denylist": [DEVNET_ADDRESS.replacen('m', "M", 1)] }), + json!({ "denylist": ["0xa1b2c3"] }), + json!({ "allowlist": [RECIPIENT], "denylist": [BLOCKED] }), + json!({ "deny_unknown": true }), + json!({ "allowlist": [RECIPIENT], "deny_unknown": false }), + json!({ "recipient_denylist": [BLOCKED] }), + json!({ "max_per_transaction": {} }), + ] { + let verdict = RecipientPolicy + .validate_params(&serde_json::to_vec(¶ms).unwrap()) + .await + .unwrap(); + assert!(!verdict.ok, "{params}"); + } + } +} diff --git a/crates/guardian-module-sdk/src/policies/signer_policy.rs b/crates/guardian-module-sdk/src/policies/signer_policy.rs new file mode 100644 index 000000000..48b91bfaa --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/signer_policy.rs @@ -0,0 +1,233 @@ +//! `signer-policy`: who may sign for the account. + +use std::collections::BTreeSet; + +use async_trait::async_trait; +use serde::Deserialize; + +use super::{IdKind, Rule}; +use crate::{ + AccountView, Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, + ParamsVerdict, +}; + +pub const KIND: &str = "signer-policy"; + +const HOOKS: [Hook; 3] = [ + Hook::BeforeAccountRegistered, + Hook::BeforeProposalCreated, + Hook::BeforeTransactionApproved, +]; + +/// Which signers a list is checked against. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum SignerCheck { + /// The signers a registration or a transaction adds; signers the account already has are + /// kept until they change. + #[default] + Added, + /// Every signer the account has after the registration or transaction. + All, +} + +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + /// The only signer commitments the account may have. Excludes `denylist`. + #[serde(default)] + pub allowlist: Option>, + /// Signer commitments the account may not have. Excludes `allowlist`. + #[serde(default)] + pub denylist: Option>, + /// Which signers the list is checked against; `added` unless set. Needs a list. + #[serde(default)] + pub check: Option, +} + +enum List { + Allow(BTreeSet), + Deny(BTreeSet), +} + +impl List { + fn permits(&self, signer: &str) -> bool { + match self { + List::Allow(list) => list.contains(signer), + List::Deny(list) => !list.contains(signer), + } + } +} + +struct Rules { + list: Option, + check: SignerCheck, +} + +impl TryFrom for Rules { + type Error = String; + + fn try_from(params: Params) -> Result { + if params.check.is_some() && params.allowlist.is_none() && params.denylist.is_none() { + return Err("check applies to allowlist or denylist, neither of which is set".into()); + } + let list = match (params.allowlist, params.denylist) { + (Some(_), Some(_)) => { + return Err("allowlist and denylist are mutually exclusive".into()); + } + (Some(list), None) => Some(List::Allow(super::ids( + "allowlist", + IdKind::Commitment, + &list, + )?)), + (None, Some(list)) => Some(List::Deny(super::ids( + "denylist", + IdKind::Commitment, + &list, + )?)), + (None, None) => None, + }; + Ok(Self { + list, + check: params.check.unwrap_or_default(), + }) + } +} + +impl Rules { + fn parse(params: &[u8]) -> Result { + super::parse::(params).and_then(Self::try_from) + } + + fn judge(&self, request: &HookRequest) -> Result { + let Some(list) = &self.list else { + return Ok(Decision::allow()); + }; + let after = super::after(request)?; + Ok( + match self + .checked(request.before.as_ref(), after) + .into_iter() + .find(|signer| !list.permits(signer)) + { + Some(signer) => Rule::Signers.deny(format!("signer {signer} is not permitted")), + None => Decision::allow(), + }, + ) + } + + fn checked(&self, before: Option<&AccountView>, after: &AccountView) -> Vec { + let existing: BTreeSet = match (self.check, before) { + (SignerCheck::Added, Some(before)) => super::normalized(&before.signer_commitments), + _ => BTreeSet::new(), + }; + super::normalized(&after.signer_commitments) + .into_iter() + .filter(|signer| !existing.contains(signer)) + .collect() + } +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct SignerPolicy; + +#[async_trait] +impl Module for SignerPolicy { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(super::info(KIND, &HOOKS)) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(super::verdict(params, Rules::parse(params), &[])) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + Rules::parse(&request.params) + .map_err(ModuleError::InvalidRequest)? + .judge(request) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::super::testing::*; + use super::*; + + const LISTED: &str = "0x0000000000000000000000000000000000000000000000000000000000000052"; + const OTHER: &str = "0x0000000000000000000000000000000000000000000000000000000000000053"; + const BAD: &str = "0x0000000000000000000000000000000000000000000000000000000000000bad"; + + async fn decide(request: &HookRequest) -> Decision { + SignerPolicy.evaluate(request).await.unwrap() + } + + #[tokio::test] + async fn added_mode_checks_only_new_signers() { + let params = json!({ "allowlist": [LISTED] }); + let adding_listed = + registration_request(params.clone(), Some(&[SIGNER]), &[SIGNER, LISTED]); + assert!(decide(&adding_listed).await.allows()); + let adding_other = registration_request(params, Some(&[SIGNER]), &[SIGNER, OTHER]); + assert_eq!( + decide(&adding_other).await.reason_code, + "signer_not_allowed" + ); + } + + #[tokio::test] + async fn all_mode_checks_every_signer() { + let params = json!({ "check": "all", "allowlist": [LISTED] }); + let request = registration_request(params, Some(&[SIGNER]), &[SIGNER, LISTED]); + assert!(!decide(&request).await.allows()); + } + + #[tokio::test] + async fn registration_checks_every_initial_signer() { + let params = json!({ "denylist": [BAD] }); + let request = registration_request( + params, + None, + &[ + SIGNER, + "0x0000000000000000000000000000000000000000000000000000000000000BAD", + ], + ); + assert!(!decide(&request).await.allows()); + } + + #[tokio::test] + async fn a_transaction_is_judged_on_its_account_views() { + let params = json!({ "denylist": [BAD] }); + let mut request = tx_request(params, crate::MidenTransaction::default()); + request.after = Some(view(&[SIGNER, BAD])); + assert_eq!(decide(&request).await.reason_code, "signer_not_allowed"); + } + + #[tokio::test] + async fn missing_account_view_is_an_error_not_an_allow() { + let mut request = registration_request(json!({ "allowlist": [SIGNER] }), None, &[]); + request.after = None; + assert!(SignerPolicy.evaluate(&request).await.is_err()); + } + + #[tokio::test] + async fn params_are_validated() { + for params in [ + json!({ "denylist": ["0x"] }), + json!({ "allowlist": [], "denylist": [] }), + json!({ "allowlist": ["0x000000000000000000000000000051"] }), + json!({ "check": "all" }), + json!({ "check": "sometimes", "allowlist": [SIGNER] }), + json!({ "signer_allowlist": [SIGNER] }), + json!({ "denylist": [DEVNET_ADDRESS] }), + ] { + let verdict = SignerPolicy + .validate_params(&serde_json::to_vec(¶ms).unwrap()) + .await + .unwrap(); + assert!(!verdict.ok, "{params}"); + } + } +} diff --git a/crates/guardian-module-sdk/src/policies/spending_limit.rs b/crates/guardian-module-sdk/src/policies/spending_limit.rs new file mode 100644 index 000000000..a2f67320c --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/spending_limit.rs @@ -0,0 +1,360 @@ +//! `spending-limit`: which assets a transaction may move, and how much of each it may send. + +use std::collections::{BTreeMap, BTreeSet}; + +use async_trait::async_trait; +use serde::Deserialize; + +use super::{Accounts, IdKind, Rule}; +use crate::proto::asset; +use crate::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, ParamsVerdict, +}; + +pub const KIND: &str = "spending-limit"; + +const HOOKS: [Hook; 2] = [Hook::BeforeProposalCreated, Hook::BeforeTransactionApproved]; + +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + /// The most a transaction may send of each listed asset, faucet id to a decimal amount. The + /// payment notes of one transaction are summed per asset; the fee note does not count, and + /// an asset that is not listed is not capped. + #[serde(default)] + pub max_per_transaction: BTreeMap, + /// The assets a transaction may send in payment notes or receive from the notes it + /// consumes. Unset, any asset; empty, none. + #[serde(default)] + pub allowed_assets: Option>, +} + +struct Rules { + caps: BTreeMap, + assets: Option>, +} + +impl TryFrom for Rules { + type Error = String; + + fn try_from(params: Params) -> Result { + let mut caps = BTreeMap::new(); + for (faucet, amount) in params.max_per_transaction { + let faucet = super::id("max_per_transaction", IdKind::Account, &faucet)?; + let amount = amount + .parse::() + .map_err(|_| format!("max_per_transaction for {faucet} is not a decimal amount"))?; + if caps.insert(faucet.clone(), amount).is_some() { + return Err(format!( + "max_per_transaction names {faucet} more than once (ids are compared in lowercase)" + )); + } + } + Ok(Self { + caps, + assets: params + .allowed_assets + .as_deref() + .map(|list| super::ids("allowed_assets", IdKind::Account, list)) + .transpose()?, + }) + } +} + +impl Rules { + fn parse(params: &[u8]) -> Result { + super::parse::(params).and_then(Self::try_from) + } + + fn judge(&self, request: &HookRequest) -> Result { + if self.caps.is_empty() && self.assets.is_none() { + return Ok(Decision::allow()); + } + let projection = super::transaction(request)?; + let payments = || projection.output_notes.iter().filter(|note| !note.tx_fee); + + if let Some(allowed) = &self.assets { + let sent = payments().flat_map(|n| n.assets.iter()); + let received = projection.input_notes.iter().flat_map(|n| n.assets.iter()); + if let Some(faucet) = sent + .chain(received) + .map(|a| a.faucet_id.to_ascii_lowercase()) + .find(|faucet| !allowed.contains(faucet)) + { + return Ok(Rule::AssetAllowlist.deny(format!("asset {faucet} is not allowed"))); + } + } + + if !self.caps.is_empty() { + let mut sent: BTreeMap = BTreeMap::new(); + for asset in payments().flat_map(|n| n.assets.iter()) { + if let Some(asset::Value::FungibleAmount(amount)) = &asset.value { + let amount = amount.parse::().unwrap_or(u128::MAX); + let total = sent + .entry(asset.faucet_id.to_ascii_lowercase()) + .or_default(); + *total = total.saturating_add(amount); + } + } + for (faucet, cap) in &self.caps { + if sent.get(faucet).is_some_and(|total| total > cap) { + return Ok(Rule::AmountCap + .deny(format!("sent {} of {faucet}, cap {cap}", sent[faucet]))); + } + } + } + + Ok(Decision::allow()) + } +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct SpendingLimit; + +#[async_trait] +impl Module for SpendingLimit { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(super::info(KIND, &HOOKS)) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(super::verdict( + params, + Rules::parse(params), + &[ + Accounts::Keys("max_per_transaction"), + Accounts::List("allowed_assets"), + ], + )) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + Rules::parse(&request.params) + .map_err(ModuleError::InvalidRequest)? + .judge(request) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::super::testing::*; + use super::*; + use crate::proto::hook_request; + use crate::{Asset, InputNote, MidenTransaction, VaultChange}; + + async fn decide(request: &HookRequest) -> Decision { + SpendingLimit.evaluate(request).await.unwrap() + } + + fn cap() -> serde_json::Value { + json!({ "max_per_transaction": { USDC: "1000" } }) + } + + fn paying(notes: Vec) -> MidenTransaction { + MidenTransaction { + output_notes: notes, + ..Default::default() + } + } + + #[tokio::test] + async fn allows_a_payment_under_the_cap() { + let projection = paying(vec![p2id(RECIPIENT, vec![fungible(USDC, 500)])]); + assert!(decide(&tx_request(cap(), projection)).await.allows()); + } + + #[tokio::test] + async fn sums_split_payments_against_the_cap() { + let projection = paying(vec![ + p2id(RECIPIENT, vec![fungible(USDC, 600)]), + p2id( + "0x0000000000000000000000000000a2", + vec![fungible(USDC, 600)], + ), + ]); + let decision = decide(&tx_request(cap(), projection)).await; + assert!(!decision.allows()); + assert_eq!(decision.reason_code, "amount_cap_exceeded"); + } + + #[tokio::test] + async fn incoming_amounts_do_not_offset_outgoing() { + let projection = MidenTransaction { + vault_changes: vec![VaultChange { + asset: Some(fungible(USDC, 500)), + direction: crate::Direction::Out as i32, + }], + input_notes: vec![InputNote { + note_id: "0x14".into(), + assets: vec![fungible(USDC, 1000)], + }], + output_notes: vec![p2id(RECIPIENT, vec![fungible(USDC, 1500)])], + ..Default::default() + }; + assert!(!decide(&tx_request(cap(), projection)).await.allows()); + } + + #[tokio::test] + async fn uncapped_assets_and_nfts_are_not_counted() { + let nft = Asset { + faucet_id: USDC.into(), + value: Some(asset::Value::NftId("0x4f7".into())), + }; + let projection = paying(vec![p2id(RECIPIENT, vec![fungible(ETH, 5000), nft])]); + assert!(decide(&tx_request(cap(), projection)).await.allows()); + } + + #[tokio::test] + async fn the_fee_note_is_not_a_payment() { + let projection = paying(vec![ + fee_note(5000), + p2id(RECIPIENT, vec![fungible(USDC, 500)]), + ]); + assert!(decide(&tx_request(cap(), projection)).await.allows()); + let only_fee = paying(vec![fee_note(5000)]); + assert!( + decide(&tx_request(json!({ "allowed_assets": [ETH] }), only_fee)) + .await + .allows() + ); + } + + #[tokio::test] + async fn allowed_assets_cover_sent_and_received_assets() { + let sending = paying(vec![p2id(RECIPIENT, vec![fungible(ETH, 1)])]); + assert_eq!( + decide(&tx_request(json!({ "allowed_assets": [USDC] }), sending)) + .await + .reason_code, + "asset_not_allowed" + ); + let consuming = MidenTransaction { + input_notes: vec![InputNote { + note_id: "0x14".into(), + assets: vec![fungible(ETH, 1)], + }], + ..Default::default() + }; + assert_eq!( + decide(&tx_request(json!({ "allowed_assets": [USDC] }), consuming)) + .await + .reason_code, + "asset_not_allowed" + ); + } + + #[tokio::test] + async fn a_denial_names_its_rule_to_the_client_and_discloses_no_param() { + let projection = paying(vec![p2id(RECIPIENT, vec![fungible(USDC, 5_000)])]); + let decision = decide(&tx_request(cap(), projection)).await; + assert_eq!(decision.reason_code, "amount_cap_exceeded"); + assert!(!decision.client_message.is_empty()); + assert!(decision.client_message.len() <= 256); + for detail in ["1000", "5000", USDC, RECIPIENT] { + assert!( + !decision.client_message.contains(detail), + "{detail} leaked into {:?}", + decision.client_message + ); + } + assert!( + decision.message.contains("1000"), + "details stay in the logged message" + ); + } + + #[tokio::test] + async fn forged_metadata_does_not_change_the_decision() { + let projection = paying(vec![p2id(RECIPIENT, vec![fungible(USDC, 5000)])]); + let mut request = tx_request(cap(), projection); + if let Some(hook_request::Subject::Transaction(tx)) = &mut request.subject { + tx.unverified_metadata = + serde_json::to_vec(&json!({ "proposal_type": "change_threshold", "amount": "1" })) + .unwrap(); + } + assert!(!decide(&request).await.allows()); + } + + #[tokio::test] + async fn an_instance_with_no_rule_allows_without_reading_the_request() { + let unprojected = without_projection(tx_request(json!({}), MidenTransaction::default())); + assert!(decide(&unprojected).await.allows()); + } + + #[tokio::test] + async fn a_request_it_cannot_judge_is_an_error_not_an_allow() { + let unprojected = without_projection(tx_request(cap(), MidenTransaction::default())); + let registration = registration_request(cap(), None, &[SIGNER]); + for request in [unprojected, registration] { + assert!(matches!( + SpendingLimit.evaluate(&request).await, + Err(ModuleError::InvalidRequest(_)) + )); + } + } + + #[tokio::test] + async fn describes_only_the_transaction_hooks() { + let info = SpendingLimit + .describe(&DescribeRequest::default()) + .await + .unwrap(); + assert_eq!(info.name, KIND); + assert!(!info.hooks.contains(&(Hook::BeforeAccountRegistered as i32))); + } + + #[tokio::test] + async fn params_are_validated() { + for params in [ + json!({ "max_per_transaction": { "faucet": "10" } }), + json!({ "max_per_transaction": { USDC: "ten" } }), + json!({ "max_per_transaction": { "0xREPLACE_WITH_FAUCET_ID": "5" } }), + json!({ "max_per_transaction": { "0x0000000000000000000000000000AA": "5", "0x0000000000000000000000000000aa": "9" } }), + json!({ "allowed_assets": ["0xa1b2c3"] }), + json!({ "max_amount_per_tx": { USDC: "5" } }), + json!({ "denylist": [RECIPIENT] }), + json!({ "max_per_transaction": { DEVNET_ADDRESS: "5", ADDRESSED: "9" } }), + json!({ "allowed_assets": [address_of(0, 15)] }), + ] { + let verdict = SpendingLimit + .validate_params(&serde_json::to_vec(¶ms).unwrap()) + .await + .unwrap(); + assert!(!verdict.ok, "{params}"); + } + let verdict = SpendingLimit + .validate_params(&serde_json::to_vec(&cap()).unwrap()) + .await + .unwrap(); + assert!(verdict.ok); + } + + #[tokio::test] + async fn a_faucet_named_by_its_address_is_stored_and_capped_as_its_hex_id() { + let named = json!({ + "max_per_transaction": { DEVNET_ADDRESS: "5", USDC: "7" }, + "allowed_assets": [ROUTED_ADDRESS, USDC], + }); + let verdict = SpendingLimit + .validate_params(&serde_json::to_vec(&named).unwrap()) + .await + .unwrap(); + assert!(verdict.ok, "{}", verdict.message); + assert_eq!( + serde_json::from_slice::(&verdict.normalized_params).unwrap(), + json!({ + "max_per_transaction": { ADDRESSED: "5", USDC: "7" }, + "allowed_assets": [ADDRESSED, USDC], + }) + ); + + let over = paying(vec![p2id(RECIPIENT, vec![fungible(ADDRESSED, 6)])]); + assert_eq!( + decide(&tx_request(named, over)).await.reason_code, + "amount_cap_exceeded", + "params stored before normalization still cap" + ); + } +} diff --git a/crates/guardian-module-sdk/src/serve.rs b/crates/guardian-module-sdk/src/serve.rs new file mode 100644 index 000000000..aafde1c19 --- /dev/null +++ b/crates/guardian-module-sdk/src/serve.rs @@ -0,0 +1,216 @@ +//! gRPC harness exposing any [`Module`] as a `guardian.module.v1.GuardianModule` service. + +use std::collections::HashMap; +use std::net::SocketAddr; +use std::sync::Arc; + +use tonic::{Request, Response, Status}; + +use crate::proto::guardian_module_server::{GuardianModule, GuardianModuleServer}; +use crate::{ + Decision, DescribeRequest, HookRequest, Module, ModuleError, ModuleInfo, ParamsVerdict, + ValidateParamsRequest, +}; + +/// Serves `module`. Register every instance the Guardian calls with [`Serve::instance`]: a +/// harness with none refuses every call, unless [`Serve::allow_unauthenticated`] says otherwise. +pub fn serve(module: M) -> Serve { + Serve { + module: Arc::new(module), + tokens: HashMap::new(), + access: Access::Instances, + } +} + +/// Who the harness answers. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Access { + /// Calls for a registered instance, carrying that instance's token. + Instances, + /// Every call, without credentials: for tests and local experiments only. + Anyone, +} + +pub struct Serve { + module: Arc, + tokens: HashMap, + access: Access, +} + +impl Serve { + /// Accept requests for `instance_id` only when they carry `token` as a bearer credential. + pub fn instance(mut self, instance_id: impl Into, token: impl Into) -> Self { + self.tokens.insert(instance_id.into(), token.into()); + self + } + + /// Whether any instance is registered. + pub fn has_instances(&self) -> bool { + !self.tokens.is_empty() + } + + /// Answers every call without checking credentials, registered instances or not. Anyone + /// who can reach the address can then query the module and read its params; use it only + /// for tests and local experiments on a loopback address. + pub fn allow_unauthenticated(mut self) -> Self { + self.access = Access::Anyone; + self + } + + pub fn into_service(self) -> GuardianModuleServer> { + GuardianModuleServer::new(Harness { + module: self.module, + tokens: Arc::new(self.tokens), + access: self.access, + }) + } + + pub async fn run(self, addr: SocketAddr) -> Result<(), tonic::transport::Error> { + tonic::transport::Server::builder() + .add_service(self.into_service()) + .serve(addr) + .await + } +} + +pub struct Harness { + module: Arc, + tokens: Arc>, + access: Access, +} + +impl Harness { + fn authorize(&self, request: &Request, instance_id: Option<&str>) -> Result<(), Status> { + match (self.access, self.tokens.is_empty()) { + (Access::Anyone, _) => return Ok(()), + (Access::Instances, true) => { + return Err(Status::unauthenticated( + "no instance is registered with this module server", + )); + } + (Access::Instances, false) => {} + } + let presented = request + .metadata() + .get("authorization") + .and_then(|value| value.to_str().ok()) + .and_then(|value| value.strip_prefix("Bearer ")) + .ok_or_else(|| Status::unauthenticated("missing bearer token"))?; + let accepted = match instance_id { + Some(id) => self + .tokens + .get(id) + .is_some_and(|token| same_token(token, presented)), + None => self + .tokens + .values() + .any(|token| same_token(token, presented)), + }; + if accepted { + Ok(()) + } else { + Err(Status::permission_denied( + "credential does not match the instance", + )) + } + } +} + +/// Compares in time independent of where the tokens differ and of the registered token's +/// length: every byte up to the longer of the two is compared, so response timing reveals +/// neither a token prefix nor how long the token is. An empty registered token matches nothing. +fn same_token(expected: &str, presented: &str) -> bool { + let (expected, presented) = (expected.as_bytes(), presented.as_bytes()); + let length_differs = expected.len() != presented.len(); + let difference = (0..expected.len().max(presented.len())).fold(0u8, |difference, index| { + let a = expected.get(index).copied().unwrap_or(0); + let b = presented.get(index).copied().unwrap_or(0); + difference | (a ^ b) + }); + !expected.is_empty() && !length_differs && difference == 0 +} + +pub(crate) fn status(error: ModuleError) -> Status { + match error { + ModuleError::Unavailable(message) => Status::unavailable(message), + ModuleError::InvalidRequest(message) => Status::invalid_argument(message), + ModuleError::Internal(message) => Status::internal(message), + } +} + +#[tonic::async_trait] +impl GuardianModule for Harness { + async fn describe( + &self, + request: Request, + ) -> Result, Status> { + self.authorize(&request, None)?; + self.module + .describe(request.get_ref()) + .await + .map(Response::new) + .map_err(status) + } + + async fn validate_params( + &self, + request: Request, + ) -> Result, Status> { + self.authorize(&request, Some(&request.get_ref().instance_id))?; + self.module + .validate_params(&request.get_ref().params) + .await + .map(Response::new) + .map_err(status) + } + + async fn evaluate(&self, request: Request) -> Result, Status> { + self.authorize(&request, Some(&request.get_ref().instance_id))?; + self.module + .evaluate(request.get_ref()) + .await + .map(Response::new) + .map_err(status) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn harness( + server: Serve, + ) -> Harness { + Harness { + module: server.module, + tokens: Arc::new(server.tokens), + access: server.access, + } + } + + #[test] + fn a_server_without_instances_answers_nobody_unless_told_to() { + let unregistered = harness(serve(crate::policies::SpendingLimit)); + assert_eq!( + unregistered + .authorize(&Request::new(()), Some("caps")) + .unwrap_err() + .code(), + tonic::Code::Unauthenticated + ); + let open = harness(serve(crate::policies::SpendingLimit).allow_unauthenticated()); + assert!(open.authorize(&Request::new(()), Some("caps")).is_ok()); + } + + #[test] + fn only_the_registered_token_matches() { + assert!(same_token("secret-token", "secret-token")); + for presented in ["", "secret", "secret-tokeN", "secret-token-and-more", "x"] { + assert!(!same_token("secret-token", presented), "{presented:?}"); + } + assert!( + !same_token("", ""), + "an empty registered token matches nothing" + ); + } +} diff --git a/crates/guardian-module-sdk/tests/conformance.rs b/crates/guardian-module-sdk/tests/conformance.rs new file mode 100644 index 000000000..bc86b0b4d --- /dev/null +++ b/crates/guardian-module-sdk/tests/conformance.rs @@ -0,0 +1,341 @@ +#[path = "../examples/note_policy/mod.rs"] +mod note_policy; + +use guardian_module_sdk::conformance::Suite; +use guardian_module_sdk::policies::{CodePolicy, RecipientPolicy, SignerPolicy, SpendingLimit}; +use guardian_module_sdk::proto::guardian_module_client::GuardianModuleClient; +use guardian_module_sdk::proto::{asset, hook_request}; +use guardian_module_sdk::serve::serve; +use guardian_module_sdk::{ + AccountStateProjection, AccountView, Asset, HookRequest, MidenAccountState, MidenTransaction, + Module, NoteType, OutputNote, RegistrationSubject, TransactionProjection, TransactionSubject, +}; +use serde_json::json; +use tokio::net::TcpListener; +use tonic::Request; +use tonic::metadata::MetadataValue; +use tonic::transport::server::TcpIncoming; +use tonic::transport::{Channel, Server}; + +const INSTANCE: &str = "caps"; +const TOKEN: &str = "secret-token"; + +async fn start_remote() -> Channel { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + let service = serve(SpendingLimit) + .instance(INSTANCE, TOKEN) + .into_service(); + tokio::spawn(async move { + Server::builder() + .add_service(service) + .serve_with_incoming(TcpIncoming::from(listener)) + .await + .unwrap(); + }); + Channel::from_shared(format!("http://{addr}")) + .unwrap() + .connect() + .await + .unwrap() +} + +fn authorized(message: T, token: &str) -> Request { + let mut request = Request::new(message); + request.metadata_mut().insert( + "authorization", + MetadataValue::try_from(format!("Bearer {token}")).unwrap(), + ); + request +} + +fn payment(amounts: &[u64], params: serde_json::Value) -> HookRequest { + let notes = amounts + .iter() + .enumerate() + .map(|(i, amount)| OutputNote { + note_id: format!("0x{i}"), + assets: vec![Asset { + faucet_id: "0x0000000000000000000000000000aa".into(), + value: Some(asset::Value::FungibleAmount(amount.to_string())), + }], + p2id_target: Some("0x0000000000000000000000000000a1".into()), + ..Default::default() + }) + .collect(); + HookRequest { + instance_id: INSTANCE.into(), + params: serde_json::to_vec(¶ms).unwrap(), + after: Some(AccountView::default()), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + output_notes: notes, + ..Default::default() + })), + ..Default::default() + })), + ..Default::default() + } +} + +fn view(signers: &[&str], code: &str) -> AccountView { + AccountView { + signer_commitments: signers.iter().map(|s| s.to_string()).collect(), + code_commitment: code.into(), + ..Default::default() + } +} + +fn with_views(mut request: HookRequest, before: &[&str], after: &[&str]) -> HookRequest { + request.before = Some(view( + before, + "0x00000000000000000000000000000000000000000000000000000000000000c1", + )); + request.after = Some(view( + after, + "0x00000000000000000000000000000000000000000000000000000000000000c1", + )); + request +} + +fn registration(params: serde_json::Value, signers: &[&str]) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + after: Some(view( + signers, + "0x00000000000000000000000000000000000000000000000000000000000000c1", + )), + subject: Some(hook_request::Subject::Registration(RegistrationSubject { + initial_state: Some(AccountStateProjection::miden(MidenAccountState::default())), + })), + ..Default::default() + } +} + +const FAUCET: &str = "0x0000000000000000000000000000aa"; +const SIGNER: &str = "0x0000000000000000000000000000000000000000000000000000000000000051"; +const BAD_SIGNER: &str = "0x0000000000000000000000000000000000000000000000000000000000000bad"; +const CODE: &str = "0x00000000000000000000000000000000000000000000000000000000000000c1"; + +#[tokio::test] +async fn spending_limit_conforms() { + let cap = json!({ "max_per_transaction": { FAUCET: "1000" } }); + Suite::new(SpendingLimit) + .allows("under the cap", payment(&[500], cap.clone())) + .denies_with( + "split over the cap", + payment(&[600, 600], cap.clone()), + "amount_cap_exceeded", + ) + .allows("at the cap", payment(&[1000], cap)) + .denies_with( + "an asset that is not allowed", + payment( + &[1], + json!({ "allowed_assets": ["0x0000000000000000000000000000bb"] }), + ), + "asset_not_allowed", + ) + .fails( + "params a module cannot read", + payment(&[1], json!({ "max_per_transaction": { FAUCET: "ten" } })), + ) + .valid_params(json!({})) + .valid_params( + json!({ "max_per_transaction": { FAUCET: "1000" }, "allowed_assets": [FAUCET] }), + ) + .invalid_params(json!({ "unknown": 1 })) + .invalid_params(json!({ "max_per_transaction": { FAUCET: "ten" } })) + .invalid_params(json!({ "denylist": [] })) + .run() + .await + .assert_conformant(); +} + +#[tokio::test] +async fn recipient_policy_conforms() { + Suite::new(RecipientPolicy) + .allows( + "a listed recipient", + payment( + &[1], + json!({ "allowlist": ["0x0000000000000000000000000000a1"] }), + ), + ) + .denies_with( + "a recipient not allowed", + payment( + &[1], + json!({ "allowlist": ["0x0000000000000000000000000007e4"] }), + ), + "recipient_not_allowed", + ) + .denies_with( + "a blocked recipient", + payment( + &[1], + json!({ "denylist": ["0x0000000000000000000000000000a1"] }), + ), + "recipient_blocked", + ) + .valid_params(json!({ "denylist": [] })) + .valid_params( + json!({ "denylist": ["0x0000000000000000000000000000a1"], "deny_unknown": false }), + ) + .invalid_params(json!({ "allowlist": [], "denylist": [] })) + .invalid_params(json!({ "deny_unknown": true })) + .run() + .await + .assert_conformant(); +} + +#[tokio::test] +async fn signer_policy_conforms() { + let signers = json!({ "check": "added", "denylist": [BAD_SIGNER] }); + Suite::new(SignerPolicy) + .denies_with( + "a denied signer added", + with_views( + payment(&[1], signers.clone()), + &[SIGNER], + &[SIGNER, BAD_SIGNER], + ), + "signer_not_allowed", + ) + .allows( + "no signer added", + with_views(payment(&[1], signers.clone()), &[SIGNER], &[SIGNER]), + ) + .denies( + "registration with a denied signer", + registration(signers, &[BAD_SIGNER]), + ) + .valid_params(json!({ "allowlist": [SIGNER] })) + .invalid_params(json!({ "allowlist": [], "denylist": [] })) + .invalid_params(json!({ "check": "all" })) + .run() + .await + .assert_conformant(); +} + +#[tokio::test] +async fn code_policy_conforms() { + let code = json!({ "check": "all", "allowed": [CODE] }); + Suite::new(CodePolicy) + .allows( + "listed code", + with_views(payment(&[1], code.clone()), &[SIGNER], &[SIGNER]), + ) + .allows("registration on listed code", registration(code, &[SIGNER])) + .denies_with( + "registration on code that is not listed", + registration( + json!({ "allowed": ["0x00000000000000000000000000000000000000000000000000000000000000c2"] }), + &[SIGNER], + ), + "code_not_allowed", + ) + .valid_params(json!({ "check": "changed", "allowed": [CODE] })) + .invalid_params(json!({ "check": "all" })) + .invalid_params(json!({ "allowed": ["0xc1"] })) + .run() + .await + .assert_conformant(); +} + +fn notes(notes: Vec, params: serde_json::Value) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + after: Some(AccountView::default()), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + output_notes: notes, + ..Default::default() + })), + ..Default::default() + })), + ..Default::default() + } +} + +fn note(note_type: NoteType, tx_fee: bool) -> OutputNote { + OutputNote { + note_type: note_type as i32, + tx_fee, + ..Default::default() + } +} + +#[tokio::test] +async fn note_policy_conforms() { + let one = json!({ "max_payment_notes": 1 }); + let private = json!({ "deny_private_notes": true }); + Suite::new(note_policy::NotePolicy) + .allows( + "one payment and the fee note", + notes( + vec![note(NoteType::Public, false), note(NoteType::Public, true)], + one.clone(), + ), + ) + .denies( + "two payments", + notes( + vec![note(NoteType::Public, false), note(NoteType::Public, false)], + one, + ), + ) + .denies( + "a private payment", + notes(vec![note(NoteType::Private, false)], private), + ) + .request( + "registration", + registration( + json!({}), + &["0x0000000000000000000000000000000000000000000000000000000000000051"], + ), + ) + .valid_params(json!({ "max_payment_notes": 1, "deny_private_notes": true })) + .valid_params(json!({})) + .invalid_params(json!({ "max_notes": 1 })) + .run() + .await + .assert_conformant(); +} + +#[tokio::test] +#[ignore = "timing report for the prototype gates; run with --ignored --nocapture"] +async fn loopback_evaluate_round_trip() { + let mut client = GuardianModuleClient::new(start_remote().await); + let request = payment( + &[500], + json!({ "max_per_transaction": { "0x0000000000000000000000000000aa": "1000" } }), + ); + for _ in 0..50 { + client + .evaluate(authorized(request.clone(), TOKEN)) + .await + .unwrap(); + } + let mut samples = Vec::with_capacity(1000); + for _ in 0..1000 { + let started = std::time::Instant::now(); + client + .evaluate(authorized(request.clone(), TOKEN)) + .await + .unwrap(); + samples.push(started.elapsed()); + } + samples.sort(); + let local_started = std::time::Instant::now(); + for _ in 0..1000 { + SpendingLimit.evaluate(&request).await.unwrap(); + } + println!( + "remote p50 {:?} p99 {:?}; in-process mean {:?}", + samples[500], + samples[990], + local_started.elapsed() / 1000 + ); +} diff --git a/crates/miden-multisig-client/README.md b/crates/miden-multisig-client/README.md index 9d936ec62..6d90ca8ef 100644 --- a/crates/miden-multisig-client/README.md +++ b/crates/miden-multisig-client/README.md @@ -814,6 +814,32 @@ per-proposal v2 payload is capped at `MAX_CONSUME_NOTES_METADATA_BYTES` (256 KiB) and the size is enforced at creation time so the failure surfaces to the proposer before any signature collection begins. +### Policy modules: rules and checks + +A Guardian can run policy modules that refuse a proposal at creation or a +transaction at approval. `MultisigClient::get_policies` lists the rules the +operator discloses. `check_transaction` (and `check_transaction_with_options`) +builds a `TransactionType` exactly as `propose_transaction` would and asks the +Guardian whether it would be accepted, without storing it or taking a proposal +slot: + +```rust +let policies = client.get_policies().await?; +let check = client.check_transaction(TransactionType::transfer(recipient, faucet, 1_000)).await?; +// check.complete is false when a module that opts out of checks was skipped +``` + +`check_custom_transaction` does the same for a producer-built transaction. + +The answer is advisory: approval still decides, and the Guardian rate limits +checks per account and signer. A refusal, from a check, at creation, push or +registration, is `MultisigError::ModuleDenied { module, reason_code, layer, +client_message }` (final; a generic denial carries only `policy_denied`) or +`MultisigError::ModuleUnavailable { module }` (retryable; `module` is `None` for +an instance with generic denials). A Guardian execution +refused by a module ends failed with `ExecutionFailureCode::ModuleDenied` or +`ExecutionFailureCode::ModuleUnavailable`, and the proposal is kept. + ### Error taxonomy All five errors below carry a stable, cross-SDK string code via diff --git a/crates/miden-multisig-client/src/client/account.rs b/crates/miden-multisig-client/src/client/account.rs index ef682f380..9dfc55f6b 100644 --- a/crates/miden-multisig-client/src/client/account.rs +++ b/crates/miden-multisig-client/src/client/account.rs @@ -292,9 +292,7 @@ impl MultisigClient { guardian_client .configure(&account_id, auth_config, initial_state) .await - .map_err(|e| { - MultisigError::GuardianServer(format!("failed to configure account: {}", e)) - })?; + .map_err(|e| MultisigError::guardian("failed to configure account", e))?; Ok(()) } diff --git a/crates/miden-multisig-client/src/client/anchor_binding_tests.rs b/crates/miden-multisig-client/src/client/anchor_binding_tests.rs index 057bf3cd9..057a05ea6 100644 --- a/crates/miden-multisig-client/src/client/anchor_binding_tests.rs +++ b/crates/miden-multisig-client/src/client/anchor_binding_tests.rs @@ -62,7 +62,7 @@ async fn cosigner_at_a_later_sync_height_verifies_a_pending_proposal_at_its_tip( proposer.miden_client.sync_state().await.unwrap(); // Proposal creation authenticates the notes before deriving the summary - // (see `ProposalBuilder::build_consume_notes`); mirror it here. + // (see `ProposalBuilder::draft_consume_notes`); mirror it here. let node_rpc = proposer.node_rpc_client(); crate::transaction::ensure_notes_authenticated( &mut proposer.miden_client, diff --git a/crates/miden-multisig-client/src/client/endpoint_scheme_tests.rs b/crates/miden-multisig-client/src/client/endpoint_scheme_tests.rs index ad72640e9..96c511396 100644 --- a/crates/miden-multisig-client/src/client/endpoint_scheme_tests.rs +++ b/crates/miden-multisig-client/src/client/endpoint_scheme_tests.rs @@ -100,7 +100,7 @@ async fn offline_creation_queries(scheme: SignatureScheme, seed: u8) -> Vec crate::transaction::ProposalDraft { + let account = client.require_account().unwrap().clone(); + let node_rpc = client.node_rpc_client(); + crate::transaction::ProposalBuilder::new(TransactionType::UpdateProcedureThreshold { + procedure: ProcedureName::ReceiveAsset, + new_threshold: 1, + }) + .with_execution_mode(client.execution_mode) + .draft( + &mut client.miden_client, + &node_rpc, + &account, + client.key_manager.as_ref(), + ) + .await + .unwrap() +} + +/// A check answers for exactly the proposal a push would create: same nonce, same payload, and +/// no approval, since nothing a check sends is stored. +#[tokio::test] +async fn a_check_sends_the_payload_a_push_sends_without_the_signature() { + let dir = tempfile::tempdir().unwrap(); + let (mut client, handle, _signers) = proposing_client( + dir.path(), + ProposalExecutionMode::GuardianExecutable, + AccountShape::OneSigner, + MockGuardianService::default(), + ) + .await; + let draft = draft_on(&mut client).await; + let mut guardian = client.create_authenticated_guardian_client().await.unwrap(); + + let check = draft.check(&mut guardian).await.unwrap(); + assert!(!check.complete); + assert!( + handle.pushed_proposals().is_empty(), + "a check creates nothing" + ); + let _ = draft.push(&mut guardian, client.key_manager.as_ref()).await; + + let checked = &handle.checked_proposals()[0]; + let pushed = &handle.pushed_proposals()[0]; + assert_eq!(checked.nonce, pushed.nonce); + let checked: serde_json::Value = serde_json::from_str(&checked.delta_payload).unwrap(); + let mut pushed: serde_json::Value = serde_json::from_str(&pushed.delta_payload).unwrap(); + assert!( + checked.get("signatures").is_none(), + "a check carries no approval" + ); + let signatures = pushed + .as_object_mut() + .unwrap() + .remove("signatures") + .expect("a push carries the proposer's approval"); + assert_eq!(signatures.as_array().unwrap().len(), 1); + assert_eq!(checked, pushed); +} diff --git a/crates/miden-multisig-client/src/client/guardian_execution.rs b/crates/miden-multisig-client/src/client/guardian_execution.rs index 4030a100f..44688ef27 100644 --- a/crates/miden-multisig-client/src/client/guardian_execution.rs +++ b/crates/miden-multisig-client/src/client/guardian_execution.rs @@ -557,7 +557,7 @@ mod tests { /// One scripted status read: an answer after `takes`, or one that never answers. enum Step { - Answer { takes: Duration, read: Read }, + Answer { takes: Duration, read: Box }, Stall, } @@ -565,7 +565,7 @@ mod tests { fn from(read: Read) -> Self { Step::Answer { takes: Duration::ZERO, - read, + read: Box::new(read), } } } @@ -587,7 +587,7 @@ mod tests { { Step::Answer { takes, read } => { *self.runtime.now.lock().unwrap() += takes; - read + *read } Step::Stall => std::future::pending().await, } @@ -805,7 +805,7 @@ mod tests { Ok(execution(ExecutionState::Submitted)).into(), Step::Answer { takes: Duration::from_secs(10), - read: Ok(execution(ExecutionState::Committed)), + read: Box::new(Ok(execution(ExecutionState::Committed))), }, ], ) diff --git a/crates/miden-multisig-client/src/client/helpers.rs b/crates/miden-multisig-client/src/client/helpers.rs index e5f35afd9..2d338a20e 100644 --- a/crates/miden-multisig-client/src/client/helpers.rs +++ b/crates/miden-multisig-client/src/client/helpers.rs @@ -173,7 +173,7 @@ impl MultisigClient { let push_response = guardian_client .push_delta(&account_id, nonce, &prev_commitment, &delta_payload) .await - .map_err(|e| MultisigError::GuardianServer(format!("failed to push delta: {}", e)))?; + .map_err(|e| MultisigError::guardian("failed to push delta", e))?; // Get GUARDIAN ack signature let ack_sig = push_response.ack_sig.ok_or_else(|| { diff --git a/crates/miden-multisig-client/src/client/mod.rs b/crates/miden-multisig-client/src/client/mod.rs index e08e7eaa1..a6bfd131f 100644 --- a/crates/miden-multisig-client/src/client/mod.rs +++ b/crates/miden-multisig-client/src/client/mod.rs @@ -56,7 +56,7 @@ pub use note_recovery::{ NoteRecoveryOptions, NoteRecoveryReport, RecoveryStep, RecoveryStepProblem, }; pub use proposal_note_import::{NoteImportOutcome, NoteImportSource, NoteImportStatus}; -pub use proposals::{AbandonRequest, AbandonRequestState, AbandonStatus}; +pub use proposals::{AbandonRequest, AbandonRequestState, AbandonStatus, Policy}; pub use public_note_backfill::{BlockRange, PublicBackfillOptions, PublicBackfillReport}; pub use recovery::{TransportRecoveryReport, TransportRecoveryStatus}; diff --git a/crates/miden-multisig-client/src/client/proposals.rs b/crates/miden-multisig-client/src/client/proposals.rs index 912e60f68..f5571983a 100644 --- a/crates/miden-multisig-client/src/client/proposals.rs +++ b/crates/miden-multisig-client/src/client/proposals.rs @@ -10,6 +10,21 @@ use miden_protocol::Word; use super::{MultisigClient, ProposalResult}; +/// A policy GUARDIAN applies to the account, as far as its operator discloses it. +#[derive(Debug, Clone, PartialEq)] +pub struct Policy { + /// The operator-chosen module instance id. + pub module_id: String, + /// The points where it runs, for example `before_proposal_created`. + pub hooks: Vec, + /// The operator's description of the rule. + pub description: String, + /// The rule's parameters, where the operator discloses them. + pub params: Option, + /// This account's own stricter layer on the rule, where disclosed. + pub account_layer: Option, +} + /// Immediate outcome of an abandon request (issue #319). #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum AbandonRequestState { @@ -68,8 +83,8 @@ use crate::execution::{ use crate::keystore::{proposal_public_key_hex, word_from_hex}; use crate::proposal::{Proposal, TransactionType, is_builtin_proposal_type}; use crate::transaction::{ - ProposalBuilder, ProposalOptions, deserialize_transaction_request, execute_for_summary_at_tip, - proposal_auth_args, word_to_hex, + ProposalBuilder, ProposalCheck, ProposalDraft, ProposalOptions, + deserialize_transaction_request, execute_for_summary_at_tip, proposal_auth_args, word_to_hex, }; impl MultisigClient { @@ -341,9 +356,7 @@ impl MultisigClient { let sign_response = guardian_client .sign_delta_proposal(&account_id, proposal_id, signature) .await - .map_err(|e| { - MultisigError::GuardianServer(format!("failed to sign proposal: {}", e)) - })?; + .map_err(|e| MultisigError::guardian("failed to sign proposal", e))?; let updated_raw = sign_response .delta @@ -530,6 +543,38 @@ impl MultisigClient { transaction_request_bytes: &[u8], proposal_type: &str, ) -> Result { + let draft = self + .draft_custom_transaction(transaction_request_bytes, proposal_type) + .await?; + let mut guardian_client = self.create_authenticated_guardian_client().await?; + let proposal = draft + .push(&mut guardian_client, self.key_manager.as_ref()) + .await?; + self.known_proposals + .record(proposal.tx_summary.account_delta().id(), &proposal); + Ok(proposal) + } + + /// Asks GUARDIAN whether a custom transaction would be accepted as a proposal: it is built + /// exactly as [`Self::propose_custom_transaction`] builds it, but nothing is stored. Mirrors + /// [`Self::check_transaction`] for the transactions the SDK does not model. + pub async fn check_custom_transaction( + &mut self, + transaction_request_bytes: &[u8], + proposal_type: &str, + ) -> Result { + let draft = self + .draft_custom_transaction(transaction_request_bytes, proposal_type) + .await?; + let mut guardian_client = self.create_authenticated_guardian_client().await?; + draft.check(&mut guardian_client).await + } + + async fn draft_custom_transaction( + &mut self, + transaction_request_bytes: &[u8], + proposal_type: &str, + ) -> Result { let proposal_type = proposal_type.trim().to_lowercase(); if proposal_type.is_empty() { return Err(MultisigError::InvalidConfig( @@ -559,7 +604,6 @@ impl MultisigClient { let tx_request = deserialize_transaction_request(transaction_request_bytes)?; let tx_summary = execute_for_summary_at_tip(&mut self.miden_client, account_id, tx_request).await?; - let tx_commitment = tx_summary.to_commitment(); let required_signatures = account.threshold()? as usize; @@ -576,34 +620,13 @@ impl MultisigClient { self.execution_mode .attachment_of_bytes(transaction_request_bytes), ) - .with_signature(self.key_manager.as_ref(), tx_commitment) .with_custom_metadata(proposal_type.to_string()) .with_required_signatures(required_signatures); let nonce = account.nonce() + 1; let payload = payload.with_base_commitment(account.commitment()); - - let mut guardian_client = self.create_authenticated_guardian_client().await?; - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; - let proposal = Proposal::new(tx_summary, nonce, TransactionType::Custom, metadata); - - if !proposal - .id - .trim_start_matches("0x") - .eq_ignore_ascii_case(response.commitment.trim_start_matches("0x")) - { - return Err(MultisigError::GuardianServer(format!( - "GUARDIAN returned proposal commitment {} but expected {}", - response.commitment, proposal.id - ))); - } - - self.known_proposals.record(account_id, &proposal); - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } /// Assembles the validated execution advice for a threshold-met custom @@ -791,6 +814,75 @@ impl MultisigClient { Ok(proposal) } + /// Asks GUARDIAN whether `transaction_type` would be accepted as a proposal: the + /// transaction is built exactly as [`Self::propose_transaction`] builds it, but nothing is + /// stored and no proposal slot is taken. A policy refusal is the same + /// [`MultisigError::ModuleDenied`] creation returns. Advisory: approval still decides, + /// and GUARDIAN rate limits checks per account and signer. + pub async fn check_transaction( + &mut self, + transaction_type: TransactionType, + ) -> Result { + self.check_transaction_with_options(transaction_type, ProposalOptions::default()) + .await + } + + /// [`Self::check_transaction`] with per-proposal settings. See [`ProposalOptions`]. + pub async fn check_transaction_with_options( + &mut self, + transaction_type: TransactionType, + options: ProposalOptions, + ) -> Result { + self.sync().await?; + let account = self.require_account()?.clone(); + self.ensure_key_scheme_matches(&account)?; + let mut guardian_client = self.create_authenticated_guardian_client().await?; + let node_rpc = self.node_rpc_client(); + ProposalBuilder::new(transaction_type) + .with_options(options) + .with_execution_mode(self.execution_mode) + .check( + &mut self.miden_client, + &node_rpc, + &mut guardian_client, + &account, + self.key_manager.as_ref(), + ) + .await + } + + /// The policies GUARDIAN applies to this account, as far as its operator discloses them, + /// in the order they are evaluated. + pub async fn get_policies(&mut self) -> Result> { + let account_id = self.require_account()?.id(); + let mut guardian_client = self.create_authenticated_guardian_client().await?; + let response = guardian_client + .get_policies(&account_id) + .await + .map_err(|e| MultisigError::guardian("failed to get policies", e))?; + let json = |field: &str, text: Option| -> Result> { + text.map(|text| { + serde_json::from_str(&text).map_err(|e| { + MultisigError::GuardianServer(format!("policy {field} is not JSON: {e}")) + }) + }) + .transpose() + }; + response + .policies + .into_iter() + .map(|policy| { + Ok(Policy { + params: json("params", policy.params)?, + account_layer: json("account_layer", policy.account_layer)?, + module_id: policy.module_id, + hooks: policy.hooks, + description: policy.description, + }) + }) + .collect() + } + /// Proposes a transaction with automatic fallback to offline mode. /// /// First attempts to create the proposal via GUARDIAN. If GUARDIAN is unavailable @@ -835,7 +927,9 @@ impl MultisigClient { Err( error @ (MultisigError::GuardianConnection(_) | MultisigError::GuardianServer(_) - | MultisigError::GuardianProposalRefused { .. }), + | MultisigError::GuardianProposalRefused { .. } + | MultisigError::ModuleDenied { .. } + | MultisigError::ModuleUnavailable { .. }), ) => { if transaction_type.supports_offline_execution() { let exported = self.create_proposal_offline(transaction_type).await?; diff --git a/crates/miden-multisig-client/src/error.rs b/crates/miden-multisig-client/src/error.rs index d03ca0d82..05e188dee 100644 --- a/crates/miden-multisig-client/src/error.rs +++ b/crates/miden-multisig-client/src/error.rs @@ -28,6 +28,25 @@ pub enum MultisigError { #[error("GUARDIAN server error: {0}")] GuardianServer(String), + /// A GUARDIAN policy module refused the request, or GUARDIAN refused one too large for its + /// modules to judge (`reason_code = request_too_large`). Final: retrying the same request + /// gets the same answer. + #[error("GUARDIAN policy {}denied the request: {reason_code}{}", module.as_deref().map(|module| format!("module {module} ")).unwrap_or_default(), layer.as_deref().map(|layer| format!(" ({layer} layer)")).unwrap_or_default())] + ModuleDenied { + /// Absent for a generic denial, which reports only `policy_denied`. + module: Option, + reason_code: String, + layer: Option, + /// The module's text for the requester, when the instance allows it. + client_message: Option, + }, + + /// A fail-closed GUARDIAN policy module could not decide, or GUARDIAN could not build the + /// request a module judges. Retryable. + /// `module` is absent for an instance whose denials are generic. + #[error("a GUARDIAN policy module is unavailable; try again shortly")] + ModuleUnavailable { module: Option }, + /// GUARDIAN refused a Guardian-execution request with a stable code, such as /// `GUARDIAN_PROPOSAL_NOT_READY` or `GUARDIAN_EXECUTION_CONFLICT`. `retryable` is the /// server's `meta.retryable`; `retry_after` is the server's backoff hint, when it sent one; @@ -401,9 +420,36 @@ pub(crate) fn rpc_kind(error: &RpcError) -> Option<&GrpcError> { } } +impl MultisigError { + /// A GUARDIAN call failure with `context`; a policy module refusal keeps its typed variant. + pub(crate) fn guardian(context: &str, err: guardian_client::ClientError) -> Self { + if err.module_refusal().is_some() { + Self::from(err) + } else { + Self::GuardianServer(format!("{context}: {err}")) + } + } +} + impl From for MultisigError { fn from(err: guardian_client::ClientError) -> Self { - MultisigError::GuardianServer(err.to_string()) + match err.module_refusal() { + Some(guardian_client::ModuleRefusal::Denied { + module, + reason_code, + layer, + client_message, + }) => MultisigError::ModuleDenied { + module, + reason_code, + layer, + client_message, + }, + Some(guardian_client::ModuleRefusal::Unavailable { module }) => { + MultisigError::ModuleUnavailable { module } + } + None => MultisigError::GuardianServer(err.to_string()), + } } } @@ -412,6 +458,9 @@ impl MultisigError { /// when GUARDIAN answered with a stable code, else /// [`GuardianServer`](MultisigError::GuardianServer). pub(crate) fn proposal_push(err: guardian_client::ClientError) -> Self { + if err.module_refusal().is_some() { + return Self::from(err); + } match err.guardian_code() { Some(code) => MultisigError::GuardianProposalRefused { message: err.user_message().unwrap_or_else(|| err.to_string()), @@ -474,6 +523,72 @@ mod tests { .into() } + fn guardian_status( + code: tonic::Code, + details: serde_json::Value, + ) -> guardian_client::ClientError { + tonic::Status::with_details(code, "refused", details.to_string().into_bytes().into()).into() + } + + #[test] + fn guardian_module_refusals_keep_module_and_reason() { + let denied = MultisigError::from(guardian_status( + tonic::Code::PermissionDenied, + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "denied", + "meta": { "retryable": false, "module": "caps", "reason_code": "amount_cap_exceeded" } + }), + )); + assert!(matches!( + denied, + MultisigError::ModuleDenied { ref module, ref reason_code, .. } + if module.as_deref() == Some("caps") && reason_code == "amount_cap_exceeded" + )); + + let unavailable = MultisigError::from(guardian_status( + tonic::Code::Unavailable, + serde_json::json!({ + "code": "GUARDIAN_MODULE_UNAVAILABLE", + "message": "unavailable", + "meta": { "retryable": true, "module": "sanctions" } + }), + )); + assert!(matches!( + unavailable, + MultisigError::ModuleUnavailable { ref module } if module.as_deref() == Some("sanctions") + )); + } + + #[test] + fn a_proposal_push_keeps_a_module_refusal_typed_and_maps_other_refusals() { + let denied = MultisigError::proposal_push(guardian_status( + tonic::Code::PermissionDenied, + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "denied", + "meta": { "retryable": false, "module": "caps", "reason_code": "amount_cap_exceeded" } + }), + )); + assert!( + matches!(denied, MultisigError::ModuleDenied { ref reason_code, .. } if reason_code == "amount_cap_exceeded"), + "{denied:?}" + ); + + let full = MultisigError::proposal_push(guardian_status( + tonic::Code::InvalidArgument, + serde_json::json!({ + "code": "GUARDIAN_PROPOSAL_REQUEST_TOO_LARGE", + "message": "too large", + "meta": { "retryable": false } + }), + )); + assert!(matches!( + full, + MultisigError::GuardianProposalRefused { .. } + )); + } + #[test] fn miden_client_conversion_retains_typed_rpc_kind() { let error = MultisigError::from(request_error(GrpcError::ResourceExhausted)); @@ -549,17 +664,6 @@ mod tests { )); } - fn guardian_status( - code: tonic::Code, - details: serde_json::Value, - ) -> guardian_client::ClientError { - guardian_client::ClientError::from(tonic::Status::with_details( - code, - "refused", - details.to_string().into_bytes().into(), - )) - } - #[test] fn a_coded_push_refusal_is_typed_with_its_code_and_retry_meta() { let error = MultisigError::proposal_push(guardian_status( diff --git a/crates/miden-multisig-client/src/lib.rs b/crates/miden-multisig-client/src/lib.rs index 1906c1cab..b69d1332e 100644 --- a/crates/miden-multisig-client/src/lib.rs +++ b/crates/miden-multisig-client/src/lib.rs @@ -66,7 +66,7 @@ pub(crate) type MidenSdkClient = Client; // Main client pub use builder::MultisigClientBuilder; -pub use client::{AbandonRequest, AbandonRequestState, AbandonStatus}; +pub use client::{AbandonRequest, AbandonRequestState, AbandonStatus, Policy}; pub use client::{ BlockRange, ConsumableNote, ExecutionWaitOptions, HistoryAssetKind, HistoryDecodeSection, HistoryDecodeWarning, HistoryEntry, HistoryEntryStatus, HistoryNote, HistoryNoteAsset, @@ -112,11 +112,11 @@ pub use prover::{ProverConfig, ProverRetryPolicy}; pub use rpc::{RpcConfig, RpcRetryPolicy}; pub use transaction::{ GUARDIAN_EXECUTABLE_APPROVAL_EXPIRATION_DELTA, GUARDIAN_EXECUTABLE_TX_EXPIRATION_DELTA, - MAX_APPROVAL_EXPIRATION_DELTA, ProposalBuilder, ProposalExecutionMode, ProposalOptions, - TransactionRequestBuilderExt, build_p2id_transaction_request, deserialize_transaction_request, - generate_salt, multisig_auth_args, proposal_auth_args, proposer_auth_args, - summary_approval_expiration_block_num, summary_expiration_delta, summary_salt, - synced_fee_faucet_id, + MAX_APPROVAL_EXPIRATION_DELTA, ProposalBuilder, ProposalCheck, ProposalExecutionMode, + ProposalOptions, TransactionRequestBuilderExt, build_p2id_transaction_request, + deserialize_transaction_request, generate_salt, multisig_auth_args, proposal_auth_args, + proposer_auth_args, summary_approval_expiration_block_num, summary_expiration_delta, + summary_salt, synced_fee_faucet_id, }; // Export/Import @@ -132,7 +132,7 @@ pub use guardian_client::{MAX_SESSION_TTL, MIN_SESSION_TTL, SessionInfo, StartSe // Guardian execution pub use guardian_client::execution::{ ExecutionFailure, ExecutionFailureCode, ExecutionState, ExpirationBound, - ForeignAccountUnavailableReason, ProposalExecution, RequestInvalidReason, + ForeignAccountUnavailableReason, ModuleDenial, ProposalExecution, RequestInvalidReason, }; // Re-exports for convenience diff --git a/crates/miden-multisig-client/src/transaction/builder.rs b/crates/miden-multisig-client/src/transaction/builder.rs index bcac48e42..abdeb60c9 100644 --- a/crates/miden-multisig-client/src/transaction/builder.rs +++ b/crates/miden-multisig-client/src/transaction/builder.rs @@ -49,6 +49,25 @@ pub struct ProposalBuilder { execution_mode: ProposalExecutionMode, } +/// A proposal built for an account and not yet sent: the payload GUARDIAN would store, without +/// the proposer's approval, and the proposal it describes. [`Self::check`] asks GUARDIAN whether +/// it would be created; [`Self::push`] signs and creates it. Both send the same payload, so a +/// check answers for exactly the proposal a push would create. +#[derive(Debug, Clone)] +pub(crate) struct ProposalDraft { + proposal: Proposal, + payload: ProposalPayload, +} + +/// The answer of a proposal check that passed: GUARDIAN's policy modules would let the +/// proposal be created. A refusal is the same error creating it returns. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct ProposalCheck { + /// False when a module that opts out of checks was skipped, so creation could still be + /// refused. + pub complete: bool, +} + /// Per-proposal settings a caller may set when proposing a transaction. #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] pub struct ProposalOptions { @@ -170,7 +189,23 @@ impl ProposalBuilder { self } - /// Builds and submits the proposal to GUARDIAN. + /// Builds the proposal and asks GUARDIAN whether it would be created, without storing it. + /// Advisory: approval still decides. + pub async fn check( + self, + miden_client: &mut MidenSdkClient, + node_rpc: &Arc, + guardian_client: &mut GuardianClient, + account: &MultisigAccount, + key_manager: &dyn KeyManager, + ) -> Result { + self.draft(miden_client, node_rpc, account, key_manager) + .await? + .check(guardian_client) + .await + } + + /// Builds the proposal, signs it as its proposer and creates it on GUARDIAN. pub async fn build( self, miden_client: &mut MidenSdkClient, @@ -179,6 +214,21 @@ impl ProposalBuilder { account: &MultisigAccount, key_manager: &dyn KeyManager, ) -> Result { + self.draft(miden_client, node_rpc, account, key_manager) + .await? + .push(guardian_client, key_manager) + .await + } + + /// Builds the proposal for `account` with `key_manager` as its proposer, without contacting + /// GUARDIAN: the transaction is executed locally for its summary, and nothing is signed. + pub(crate) async fn draft( + self, + miden_client: &mut MidenSdkClient, + node_rpc: &Arc, + account: &MultisigAccount, + key_manager: &dyn KeyManager, + ) -> Result { match self.transaction_type { TransactionType::AddCosigner { new_commitment, @@ -186,24 +236,12 @@ impl ProposalBuilder { } => { let new_signer = SignerSpec::new(new_commitment, scheme.unwrap_or(key_manager.scheme())); - self.build_add_cosigner( - miden_client, - guardian_client, - account, - new_signer, - key_manager, - ) - .await + self.draft_add_cosigner(miden_client, account, new_signer, key_manager) + .await } TransactionType::RemoveCosigner { commitment } => { - self.build_remove_cosigner( - miden_client, - guardian_client, - account, - commitment, - key_manager, - ) - .await + self.draft_remove_cosigner(miden_client, account, commitment, key_manager) + .await } TransactionType::P2ID { recipient, @@ -212,9 +250,8 @@ impl ProposalBuilder { note_type, heights, } => { - self.build_p2id( + self.draft_p2id( miden_client, - guardian_client, account, recipient, faucet_id, @@ -226,10 +263,9 @@ impl ProposalBuilder { .await } TransactionType::ConsumeNotes { ref note_ids, .. } => { - self.build_consume_notes( + self.draft_consume_notes( miden_client, node_rpc, - guardian_client, account, note_ids.clone(), key_manager, @@ -240,9 +276,8 @@ impl ProposalBuilder { ref new_endpoint, new_commitment, } => { - self.build_switch_guardian( + self.draft_switch_guardian( miden_client, - guardian_client, account, new_commitment, new_endpoint.clone(), @@ -254,9 +289,8 @@ impl ProposalBuilder { procedure, new_threshold, } => { - self.build_update_procedure_threshold( + self.draft_update_procedure_threshold( miden_client, - guardian_client, account, procedure, new_threshold, @@ -268,9 +302,8 @@ impl ProposalBuilder { new_threshold, ref signer_commitments, } => { - self.build_update_signers( + self.draft_update_signers( miden_client, - guardian_client, account, new_threshold, signer_commitments, @@ -284,18 +317,6 @@ impl ProposalBuilder { } } - fn ensure_response_commitment(proposal: &Proposal, response_commitment: &str) -> Result<()> { - let response_commitment = ensure_hex_prefix(response_commitment); - if hex_body_eq(&proposal.id, &response_commitment) { - return Ok(()); - } - - Err(MultisigError::GuardianServer(format!( - "GUARDIAN returned proposal commitment {} but transaction summary commitment is {}", - response_commitment, proposal.id - ))) - } - async fn fresh_auth_args(&self, miden_client: &MidenSdkClient) -> Result { proposer_auth_args( miden_client, @@ -306,14 +327,13 @@ impl ProposalBuilder { .await } - async fn build_add_cosigner( + async fn draft_add_cosigner( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, new_signer: SignerSpec, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let current_threshold = account.threshold()?; let approvers = account.cosigners()?; @@ -347,9 +367,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - // Sign the transaction summary commitment - let tx_commitment = tx_summary.to_commitment(); - // Build proposal metadata let signer_commitments_hex: Vec = current_signers.iter().map(word_to_hex).collect(); @@ -380,7 +397,6 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) .with_add_signer_metadata( new_threshold, signer_commitments_hex.clone(), @@ -389,13 +405,8 @@ impl ProposalBuilder { .with_signer_schemes(&signer_schemes) .with_required_signatures(required_signatures); - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; let payload = payload.with_base_commitment(account.commitment()); - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; // Build the Proposal let proposal = Proposal::new( @@ -407,28 +418,25 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } /// Changes the signing threshold, leaving the signer set as it is. /// /// The on-chain procedure takes a set and a threshold together, so this is - /// the same call `build_add_cosigner` makes with the set left alone. A + /// the same call `draft_add_cosigner` makes with the set left alone. A /// membership change is refused here rather than served: deriving the new /// set from the current one is what makes add and remove safe, and a /// caller-supplied set would give that up for no gain, since this variant /// exists to move the threshold. - async fn build_update_signers( + async fn draft_update_signers( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, new_threshold: u32, requested_signers: &[Word], key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let current_threshold = account.threshold()?; let target_signers = account.cosigners()?; @@ -459,7 +467,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - let tx_commitment = tx_summary.to_commitment(); let signer_commitments_hex: Vec = current_signers.iter().map(word_to_hex).collect(); @@ -493,7 +500,6 @@ impl ProposalBuilder { let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) .with_threshold_metadata( new_threshold, signer_commitments_hex.clone(), @@ -505,11 +511,6 @@ impl ProposalBuilder { let nonce = account.nonce() + 1; let payload = payload.with_base_commitment(account.commitment()); - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; - let proposal = Proposal::new( tx_summary, nonce, @@ -519,19 +520,16 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } - async fn build_remove_cosigner( + async fn draft_remove_cosigner( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, commitment_to_remove: Word, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let current_threshold = account.threshold()?; let current_signers = account.cosigners()?; @@ -579,9 +577,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - // Sign the transaction summary commitment - let tx_commitment = tx_summary.to_commitment(); - // Build proposal metadata let signer_commitments_hex: Vec = new_signers.iter().map(word_to_hex).collect(); @@ -612,7 +607,6 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) .with_remove_signer_metadata( new_threshold, signer_commitments_hex.clone(), @@ -621,13 +615,8 @@ impl ProposalBuilder { .with_signer_schemes(&signer_schemes) .with_required_signatures(required_signatures); - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; let payload = payload.with_base_commitment(account.commitment()); - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; // Build the Proposal let proposal = Proposal::new( @@ -638,16 +627,13 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } #[allow(clippy::too_many_arguments)] - async fn build_p2id( + async fn draft_p2id( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, recipient: AccountId, faucet_id: AccountId, @@ -655,7 +641,7 @@ impl ProposalBuilder { note_type: NoteType, heights: P2ideHeights, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let required_signatures = account.effective_threshold_for(ThresholdedTransaction::P2id)? as usize; @@ -681,9 +667,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - // Sign the transaction summary commitment - let tx_commitment = tx_summary.to_commitment(); - // Build proposal metadata let metadata = ProposalMetadata { tx_summary_json: Some(tx_summary.to_json()), @@ -711,7 +694,6 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) .with_payment_metadata( recipient.to_string(), faucet_id.to_string(), @@ -722,13 +704,8 @@ impl ProposalBuilder { ) .with_required_signatures(required_signatures); - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; let payload = payload.with_base_commitment(account.commitment()); - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; // Build the Proposal let proposal = Proposal::new( @@ -743,20 +720,17 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } - async fn build_consume_notes( + async fn draft_consume_notes( &self, miden_client: &mut MidenSdkClient, node_rpc: &Arc, - guardian_client: &mut GuardianClient, account: &MultisigAccount, note_ids: Vec, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let required_signatures = account.effective_threshold_for(ThresholdedTransaction::ConsumeNotes)? as usize; @@ -800,7 +774,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - let tx_commitment = tx_summary.to_commitment(); let note_ids_hex: Vec = note_ids.iter().map(|id| id.to_hex()).collect(); let metadata = ProposalMetadata { @@ -835,7 +808,6 @@ impl ProposalBuilder { let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) .with_note_consumption_metadata_v2(note_ids_hex, notes_base64, word_to_hex(&salt)) .with_required_signatures(required_signatures); @@ -852,13 +824,8 @@ impl ProposalBuilder { } } - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; let payload = payload.with_base_commitment(account.commitment()); - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; // Clone notes for the runtime TransactionType; metadata keeps its own copy. let notes_for_tx_type = metadata.consume_notes_notes.clone(); @@ -872,21 +839,18 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } #[allow(clippy::too_many_arguments)] - async fn build_switch_guardian( + async fn draft_switch_guardian( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, new_guardian_pubkey: Word, new_guardian_endpoint: String, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let required_signatures = account.effective_threshold_for(ThresholdedTransaction::UpdateGuardian)? as usize; @@ -912,9 +876,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - // Sign the transaction summary commitment - let tx_commitment = tx_summary.to_commitment(); - // Build proposal metadata let metadata = ProposalMetadata { tx_summary_json: Some(tx_summary.to_json()), @@ -942,7 +903,6 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) .with_guardian_update_metadata( word_to_hex(&new_guardian_pubkey), new_guardian_endpoint.clone(), @@ -950,13 +910,8 @@ impl ProposalBuilder { ) .with_required_signatures(required_signatures); - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; let payload = payload.with_base_commitment(account.commitment()); - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; // Build the Proposal let proposal = Proposal::new( @@ -968,20 +923,17 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } - async fn build_update_procedure_threshold( + async fn draft_update_procedure_threshold( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, procedure: ProcedureName, new_threshold: u32, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let required_signatures = account .effective_threshold_for(ThresholdedTransaction::SetProcedureThreshold)? @@ -998,7 +950,6 @@ impl ProposalBuilder { )?; let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - let tx_commitment = tx_summary.to_commitment(); let metadata = ProposalMetadata { tx_summary_json: Some(tx_summary.to_json()), @@ -1025,18 +976,12 @@ impl ProposalBuilder { let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) .with_procedure_threshold_metadata(procedure, new_threshold as u64, word_to_hex(&salt)) .with_required_signatures(required_signatures); let nonce = account.nonce() + 1; let payload = payload.with_base_commitment(account.commitment()); - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; - let proposal = Proposal::new( tx_summary, nonce, @@ -1046,9 +991,68 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; + Ok(ProposalDraft::new(proposal, payload)) + } +} - Ok(proposal) +impl ProposalDraft { + pub(crate) fn new(proposal: Proposal, payload: ProposalPayload) -> Self { + Self { proposal, payload } + } + + fn account_id(&self) -> AccountId { + self.proposal.tx_summary.account_delta().id() + } + + /// Asks GUARDIAN whether this proposal would be created, without storing it. It carries no + /// signature: nothing it checks is stored, so it must not hand GUARDIAN an approval. A + /// refusal is the same error a push returns. Advisory: approval still decides. + pub(crate) async fn check( + &self, + guardian_client: &mut GuardianClient, + ) -> Result { + let response = guardian_client + .check_delta_proposal( + &self.account_id(), + self.proposal.nonce, + &self.payload.to_json(), + ) + .await + .map_err(MultisigError::proposal_push)?; + Ok(ProposalCheck { + complete: response.complete, + }) + } + + /// Signs the proposal with `key_manager`, the proposer it was drafted for, and creates it on + /// GUARDIAN. Refuses a reply whose commitment is not the summary's. + pub(crate) async fn push( + self, + guardian_client: &mut GuardianClient, + key_manager: &dyn KeyManager, + ) -> Result { + let account_id = self.account_id(); + let payload = self + .payload + .with_signature(key_manager, self.proposal.tx_summary.to_commitment()); + let response = guardian_client + .push_delta_proposal(&account_id, self.proposal.nonce, &payload.to_json()) + .await + .map_err(MultisigError::proposal_push)?; + Self::ensure_response_commitment(&self.proposal, &response.commitment)?; + Ok(self.proposal) + } + + fn ensure_response_commitment(proposal: &Proposal, response_commitment: &str) -> Result<()> { + let response_commitment = ensure_hex_prefix(response_commitment); + if hex_body_eq(&proposal.id, &response_commitment) { + return Ok(()); + } + + Err(MultisigError::GuardianServer(format!( + "GUARDIAN returned proposal commitment {} but transaction summary commitment is {}", + response_commitment, proposal.id + ))) } } @@ -1162,7 +1166,7 @@ mod tests { #[test] fn ensure_response_commitment_rejects_mismatch() { let proposal = test_proposal(); - let result = ProposalBuilder::ensure_response_commitment( + let result = ProposalDraft::ensure_response_commitment( &proposal, "0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20", ); diff --git a/crates/miden-multisig-client/src/transaction/consume.rs b/crates/miden-multisig-client/src/transaction/consume.rs index bc6680c34..feaf8b007 100644 --- a/crates/miden-multisig-client/src/transaction/consume.rs +++ b/crates/miden-multisig-client/src/transaction/consume.rs @@ -21,7 +21,7 @@ use crate::error::{MultisigError, Result}; /// and converts each `InputNoteRecord` to a `Note`. Returns /// `LegacyConsumeNotesNoteMissing` for the first missing ID. Used by /// both proposal creation (the proposer-local fetch in -/// `ProposalBuilder::build_consume_notes`) and the v1 verification +/// `ProposalBuilder::draft_consume_notes`) and the v1 verification /// adapter below. pub(crate) async fn fetch_notes_from_store( client: &MidenSdkClient, diff --git a/crates/miden-multisig-client/src/transaction/mod.rs b/crates/miden-multisig-client/src/transaction/mod.rs index 5e93e9c6c..a0f8c3aae 100644 --- a/crates/miden-multisig-client/src/transaction/mod.rs +++ b/crates/miden-multisig-client/src/transaction/mod.rs @@ -13,7 +13,8 @@ pub use auth_args::{ proposal_auth_args, proposer_auth_args, summary_approval_expiration_block_num, summary_salt, synced_fee_faucet_id, }; -pub use builder::{ProposalBuilder, ProposalOptions}; +pub(crate) use builder::ProposalDraft; +pub use builder::{ProposalBuilder, ProposalCheck, ProposalOptions}; pub use configuration::{ build_update_procedure_threshold_transaction_request, build_update_signers_transaction_request, }; diff --git a/crates/miden-rpc-client/src/lib.rs b/crates/miden-rpc-client/src/lib.rs index 79b4c2f61..1158765fa 100644 --- a/crates/miden-rpc-client/src/lib.rs +++ b/crates/miden-rpc-client/src/lib.rs @@ -549,6 +549,44 @@ impl MidenRpcClient { }) } + /// What the chain charges fees in and at what base rate, from the latest block header: the + /// fee asset id (a hex word) of the protocol configuration it commits to, and its + /// verification base fee. Takes `&self` like [`Self::get_account_commitment`]. + pub async fn get_chain_fee(&self, read_mode: RpcReadMode) -> Result { + const OPERATION: &str = "get_chain_fee"; + let response = self + .retry_read(OPERATION, read_mode, |mut client| async move { + let request = rpc::GetBlockHeaderByNumberRequest { + block_num: None, + include_mmr_proof: Some(false), + include_protocol_config: Some(true), + }; + client + .get_block_header_by_number(Request::new(request)) + .await + .map(tonic::Response::into_inner) + }) + .await?; + let malformed = |reason: &str| RpcClientError::MalformedResponse { + operation: OPERATION, + reason: reason.to_string(), + }; + let verification_base_fee = response + .block_header + .and_then(|header| header.fee_parameters) + .map(|parameters| parameters.verification_base_fee) + .ok_or_else(|| malformed("no fee parameters in the block header"))?; + let asset_id = response + .protocol_config + .and_then(|config| config.fee_asset_id) + .and_then(|word| word_to_hex(&word)) + .ok_or_else(|| malformed("no fee asset id in the protocol configuration"))?; + Ok(ChainFee { + asset_id, + verification_base_fee, + }) + } + /// One page of the transactions committed against `account_id` in /// `block_from..=block_to`. The node records a header for every /// account, private ones included, never prunes them, and rejects a @@ -715,6 +753,13 @@ pub fn account_id_from_proto(id: &account::AccountId) -> Option { /// One entry of a committed block's `updated_accounts`, reduced to what a /// consumer of the block feed compares. +/// The asset a chain charges fees in and its verification base fee, as of one block header. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ChainFee { + pub asset_id: String, + pub verification_base_fee: u32, +} + #[derive(Debug, Clone, PartialEq, Eq)] pub struct BlockAccountState { pub account_id: AccountId, diff --git a/crates/qualification-driver/Cargo.toml b/crates/qualification-driver/Cargo.toml index 0f058254f..33643979b 100644 --- a/crates/qualification-driver/Cargo.toml +++ b/crates/qualification-driver/Cargo.toml @@ -18,6 +18,8 @@ chrono = { workspace = true, features = ["serde"] } clap = { version = "4.5", features = ["derive"] } serde = { workspace = true, features = ["derive"] } guardian-client = { path = "../client" } +# The remote policy module the deterministic profile serves for the stack's catalog. +guardian-module-sdk = { path = "../guardian-module-sdk" } guardian-shared = { path = "../shared" } hex = { workspace = true } miden-client = { workspace = true, features = ["tonic"] } @@ -34,6 +36,7 @@ serde_json = { workspace = true } thiserror = { workspace = true } tokio = { workspace = true, features = ["macros", "process", "rt-multi-thread", "time"] } toml = "0.8" +tonic = { workspace = true, features = ["tls-ring"] } [dev-dependencies] tempfile = { workspace = true } diff --git a/crates/qualification-driver/src/manifest/mod.rs b/crates/qualification-driver/src/manifest/mod.rs index af005bd32..1004435d4 100644 --- a/crates/qualification-driver/src/manifest/mod.rs +++ b/crates/qualification-driver/src/manifest/mod.rs @@ -206,6 +206,13 @@ pub enum Action { MixedSchemeGate, SessionStart, SessionAssert, + ModuleRefusal, + ModuleUnavailable, + ModuleBreakGlass, + ModuleCapAssign, + ModuleCapRefuses, + ModuleRecipientAssign, + ModuleRecipientRefuses, Unknown(String), } @@ -285,6 +292,13 @@ impl From for Action { "mixed-scheme-gate" => Self::MixedSchemeGate, "session-start" => Self::SessionStart, "session-assert" => Self::SessionAssert, + "module-refusal" => Self::ModuleRefusal, + "module-unavailable" => Self::ModuleUnavailable, + "module-break-glass" => Self::ModuleBreakGlass, + "module-cap-assign" => Self::ModuleCapAssign, + "module-cap-refuses" => Self::ModuleCapRefuses, + "module-recipient-assign" => Self::ModuleRecipientAssign, + "module-recipient-refuses" => Self::ModuleRecipientRefuses, other => Self::Unknown(other.to_string()), } } diff --git a/crates/qualification-driver/src/scenario/account.rs b/crates/qualification-driver/src/scenario/account.rs index 545fdd05f..d5fcb9790 100644 --- a/crates/qualification-driver/src/scenario/account.rs +++ b/crates/qualification-driver/src/scenario/account.rs @@ -914,7 +914,8 @@ async fn execute_until_pre_boundary_failure( } tokio::time::sleep(std::time::Duration::from_millis(250)).await; }; - if settled.error.as_ref().map(|error| error.code) != Some(ExecutionFailureCode::NodeUnavailable) + if settled.error.as_ref().map(|error| &error.code) + != Some(&ExecutionFailureCode::NodeUnavailable) { return Err(ActionOutcome::failed_product(format!( "{label}: expected `GUARDIAN_EXECUTION_NODE_UNAVAILABLE`: {settled:?}" diff --git a/crates/qualification-driver/src/scenario/live.rs b/crates/qualification-driver/src/scenario/live.rs index 66186968d..f8a4192ff 100644 --- a/crates/qualification-driver/src/scenario/live.rs +++ b/crates/qualification-driver/src/scenario/live.rs @@ -2945,7 +2945,7 @@ pub async fn assert_signer_set(runner: &Runner) -> ActionOutcome { /// How long GUARDIAN may take to finish applying an executed change before the /// suite treats the disagreement as real. -const SETTLE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(180); +pub(super) const SETTLE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(180); /// Proposes, waiting out the window where GUARDIAN refuses a new proposal /// because earlier changes are still pending: the account's candidate queue @@ -2976,7 +2976,7 @@ async fn propose_when_settled( } /// What the account sends back to the treasury, well under what it holds. -const P2ID_AMOUNT: u64 = 1_000; +pub(super) const P2ID_AMOUNT: u64 = 1_000; /// The procedure whose threshold override the suite exercises. const OVERRIDE_PROCEDURE: miden_multisig_client::ProcedureName = diff --git a/crates/qualification-driver/src/scenario/mod.rs b/crates/qualification-driver/src/scenario/mod.rs index d8c4e83f4..98909de41 100644 --- a/crates/qualification-driver/src/scenario/mod.rs +++ b/crates/qualification-driver/src/scenario/mod.rs @@ -3,6 +3,7 @@ pub mod error_envelope; pub mod identity; pub mod live; pub mod mixed_scheme; +pub mod modules; pub mod queue; pub mod restart_handoff; pub mod signers; @@ -371,6 +372,14 @@ impl Runner { Action::ProcedureThresholdAssert => { Some(live::assert_procedure_threshold(self).await) } + Action::ModuleCapAssign => Some(modules::assign_cap(self).await), + Action::ModuleCapRefuses => Some(modules::assert_cap_refuses(self).await), + Action::ModuleRecipientAssign => { + Some(modules::assign_recipient_denylist(self).await) + } + Action::ModuleRecipientRefuses => { + Some(modules::assert_recipient_refuses(self).await) + } _ => None, } } else { @@ -409,6 +418,9 @@ impl Runner { Some(mixed_scheme::assert_per_scheme_approvals(self).await) } Action::MixedSchemeGate => Some(mixed_scheme::assert_mixed_scheme_gate(self).await), + Action::ModuleRefusal => Some(modules::assert_refusal(self).await), + Action::ModuleUnavailable => Some(modules::assert_unavailable(self).await), + Action::ModuleBreakGlass => Some(modules::assert_break_glass(self).await), _ => None, } }; diff --git a/crates/qualification-driver/src/scenario/modules.rs b/crates/qualification-driver/src/scenario/modules.rs new file mode 100644 index 000000000..51383f60c --- /dev/null +++ b/crates/qualification-driver/src/scenario/modules.rs @@ -0,0 +1,747 @@ +//! Policy modules, driven the way an operator and a client meet them: instances from the +//! stack's catalog (`qualification/stack/lib/modules.sh`), assigned to an account through the +//! operator API, refusing through the SDK. +//! +//! Every instance in that catalog is scoped `assigned`, so it applies only to an account a +//! scenario assigns it to. The deterministic actions assign to the fixture account every +//! scenario shares, so each one clears its assignment on every path, as the pause scenario +//! unpauses. +//! +//! They propose the first threshold-only fixture delta (`queue_1`) rather than `delta_1`: the +//! fixture generator adds `delta_1`'s signer without the approver scheme entry a real +//! add-signer writes, and the Guardian refuses to build a module's account view from that. + +use std::sync::Arc; + +use guardian_client::{ClientError, GuardianClient, ModuleRefusal}; +use guardian_module_sdk::policies::SignerPolicy; +use miden_multisig_client::{MultisigError, TransactionType}; +use serde_json::{Value, json}; + +use super::{ActionOutcome, Runner}; +use crate::fixtures::Fixtures; + +/// The instances the stack's catalog declares. +const GATE: &str = "qual-gate"; +const CAP: &str = "qual-cap"; +const SWITCH: &str = "qual-switch"; +const REMOTE: &str = "qual-remote"; +const RECIPIENT: &str = "qual-recipient"; + +/// A signer commitment nobody holds. Checked against every signer, an allowlist of only this +/// refuses every transaction of the fixture account. +const UNLISTED_SIGNER: &str = "0x1111111111111111111111111111111111111111111111111111111111111111"; + +const REASON: &str = "qualification: policy module scenario"; + +/// Retries `$call` while GUARDIAN still holds an earlier change of the account as pending, +/// which it reports before any module runs. +macro_rules! settled { + ($call:expr) => {{ + let started = std::time::Instant::now(); + let mut wait = std::time::Duration::from_secs(1); + loop { + match $call.await { + Err(error) + if error.to_string().contains("already a pending change") + && started.elapsed() < super::live::SETTLE_DEADLINE => + { + tokio::time::sleep(wait).await; + wait = (wait * 2).min(std::time::Duration::from_secs(5)); + } + other => break other, + } + } + }}; +} + +fn refuse_every_signer() -> Value { + json!({ "check": "all", "allowlist": [UNLISTED_SIGNER] }) +} + +/// The operator API, logged in as the operator holding `policies:write`. +struct Operator<'a> { + runner: &'a Runner, + base: String, +} + +impl<'a> Operator<'a> { + async fn login(runner: &'a Runner, fixtures: &Fixtures) -> Result { + let base = runner.endpoints.http.trim_end_matches('/').to_string(); + super::account::operator_login(runner, &base, fixtures).await?; + Ok(Self { runner, base }) + } + + async fn send( + &self, + method: reqwest::Method, + path: &str, + body: Option, + ) -> Result { + let url = format!("{}/dashboard{path}", self.base); + let mut request = self.runner.http.request(method.clone(), &url); + if let Some(body) = body { + request = request.json(&body); + } + let response = request.send().await.map_err(|error| { + ActionOutcome::failed_setup(format!("calling {method} {path} failed: {error}")) + })?; + let status = response.status(); + let text = response.text().await.unwrap_or_default(); + if !status.is_success() { + return Err(ActionOutcome::failed_product(format!( + "{method} {path} was refused with {status}: {text}" + ))); + } + serde_json::from_str(&text).map_err(|error| { + ActionOutcome::failed_product(format!("{method} {path} answered with no JSON: {error}")) + }) + } + + async fn assign( + &self, + account_id: &str, + module_id: &str, + params: Value, + ) -> Result<(), ActionOutcome> { + self.send( + reqwest::Method::PUT, + &format!("/accounts/{account_id}/modules"), + Some(json!({ "modules": [{ "module_id": module_id, "params": params }], "reason": REASON })), + ) + .await + .map(drop) + } + + async fn clear(&self, account_id: &str) -> Result<(), ActionOutcome> { + self.send( + reqwest::Method::PUT, + &format!("/accounts/{account_id}/modules"), + Some(json!({ "modules": [], "reason": REASON })), + ) + .await + .map(drop) + } + + async fn switch(&self, module_id: &str, enabled: bool) -> Result<(), ActionOutcome> { + let route = if enabled { "enable" } else { "disable" }; + self.send( + reqwest::Method::POST, + &format!("/modules/{module_id}/{route}"), + Some(json!({ "reason": REASON })), + ) + .await + .map(drop) + } + + async fn instance(&self, module_id: &str) -> Result { + let catalog = self.send(reqwest::Method::GET, "/modules", None).await?; + catalog["modules"] + .as_array() + .and_then(|modules| modules.iter().find(|module| module["module_id"] == module_id)) + .cloned() + .ok_or_else(|| { + ActionOutcome::failed_setup(format!( + "the catalog has no instance {module_id}; qualification/stack/lib/modules.sh declares it" + )) + }) + } + + async fn history(&self, module_id: &str) -> Result, ActionOutcome> { + let history = self + .send( + reqwest::Method::GET, + &format!("/modules/{module_id}/params/history"), + None, + ) + .await?; + Ok(history["entries"].as_array().cloned().unwrap_or_default()) + } +} + +/// The first failure wins; a cleanup failure counts only when everything before it passed. +fn then_cleanup(outcome: ActionOutcome, cleanup: Result<(), ActionOutcome>) -> ActionOutcome { + match (outcome, cleanup) { + (ActionOutcome::Passed, Err(failure)) => failure, + (outcome, _) => outcome, + } +} + +/// The fixture account, an authenticated client for it, and its proposal. +struct FixtureProposal { + client: GuardianClient, + account_id: miden_protocol::account::AccountId, + nonce: u64, + payload: miden_multisig_client::ProposalPayload, +} + +impl FixtureProposal { + async fn open(runner: &Runner, fixtures: &Fixtures) -> Result { + let signer = fixtures.signer().map_err(|error| { + ActionOutcome::failed_setup(format!("cannot build the fixture signer: {error}")) + })?; + let client = GuardianClient::connect(runner.endpoints.grpc.clone()) + .await + .map_err(|error| { + ActionOutcome::failed_setup(format!( + "cannot reach {}: {error}", + runner.endpoints.grpc + )) + })? + .with_signer(Arc::new(signer)); + let account_id = miden_protocol::account::AccountId::from_hex(&fixtures.account_id) + .map_err(|error| { + ActionOutcome::failed_setup(format!("the fixture account id is malformed: {error}")) + })?; + let delta = fixtures.chained.first().ok_or_else(|| { + ActionOutcome::failed_setup("the fixtures carry no threshold-only delta") + })?; + let payload = Fixtures::proposal_payload_for(&delta.payload).map_err(|error| { + ActionOutcome::failed_setup(format!("building the fixture proposal payload: {error}")) + })?; + Ok(Self { + client, + account_id, + nonce: delta.nonce, + payload, + }) + } + + async fn check(&mut self) -> Result<(), ClientError> { + self.client + .check_delta_proposal(&self.account_id, self.nonce, &self.payload) + .await + .map(drop) + } + + async fn push(&mut self) -> Result<(), ClientError> { + self.client + .push_delta_proposal(&self.account_id, self.nonce, &self.payload) + .await + .map(drop) + } +} + +/// `Passed` when `result` is a denial by `module` for `reason_code`. +fn expect_denied( + what: &str, + result: Result<(), ClientError>, + module: &str, + reason_code: &str, +) -> ActionOutcome { + match result { + Ok(()) => { + ActionOutcome::failed_product(format!("{what} was accepted while {module} refuses it")) + } + Err(error) => match error.module_refusal() { + Some(ModuleRefusal::Denied { + module: Some(denied_by), + reason_code: code, + .. + }) if denied_by == module && code == reason_code => ActionOutcome::Passed, + Some(refusal) => ActionOutcome::failed_product(format!( + "{what} was refused as {refusal:?}, not by {module} for {reason_code}" + )), + None => ActionOutcome::failed_product(format!( + "{what} failed without a module refusal: {error}" + )), + }, + } +} + +fn expect_allowed(what: &str, result: Result<(), ClientError>) -> ActionOutcome { + match result { + Ok(()) => ActionOutcome::Passed, + Err(error) => ActionOutcome::failed_product(format!("{what} was refused: {error}")), + } +} + +fn first_failure(outcomes: impl IntoIterator) -> ActionOutcome { + outcomes + .into_iter() + .find(|outcome| !matches!(outcome, ActionOutcome::Passed)) + .unwrap_or(ActionOutcome::Passed) +} + +/// An assigned in-process module refuses the fixture proposal, at the dry-run check and at +/// creation, with its id and reason code, and the same proposal passes once the assignment is +/// cleared. +pub async fn assert_refusal(runner: &Runner) -> ActionOutcome { + let Some(fixtures) = runner.fixtures.as_ref() else { + return ActionOutcome::failed_setup("the server fixtures were not loaded"); + }; + let operator = match Operator::login(runner, fixtures).await { + Ok(operator) => operator, + Err(outcome) => return outcome, + }; + let mut proposal = match FixtureProposal::open(runner, fixtures).await { + Ok(proposal) => proposal, + Err(outcome) => return outcome, + }; + let account = fixtures.account_id.clone(); + + if let Err(outcome) = operator.assign(&account, GATE, refuse_every_signer()).await { + return outcome; + } + let refused = first_failure([ + expect_denied( + "the proposal check", + proposal.check().await, + GATE, + "signer_not_allowed", + ), + expect_denied( + "the proposal", + proposal.push().await, + GATE, + "signer_not_allowed", + ), + ]); + let cleared = operator.clear(&account).await; + let outcome = then_cleanup(refused, cleared); + if !matches!(outcome, ActionOutcome::Passed) { + return outcome; + } + expect_allowed( + "the proposal check, once the module was unassigned,", + proposal.check().await, + ) +} + +/// The remote policy module the driver serves for the stack's `qual-remote` instance: +/// `signer-policy` over TLS, with the bearer token the Guardian reads from its secrets backend. +struct RemoteModule { + shutdown: tokio::sync::oneshot::Sender<()>, + server: tokio::task::JoinHandle<()>, +} + +impl RemoteModule { + async fn start() -> Result { + let missing = |name: &str| { + ActionOutcome::failed_setup(format!( + "{name} is unset, but qualification/stack/run.sh always exports it" + )) + }; + let dir = std::path::PathBuf::from( + std::env::var("QUAL_MODULE_TLS_DIR").map_err(|_| missing("QUAL_MODULE_TLS_DIR"))?, + ); + let port: u16 = std::env::var("QUAL_MODULE_PORT") + .map_err(|_| missing("QUAL_MODULE_PORT"))? + .parse() + .map_err(|error| ActionOutcome::failed_setup(format!("QUAL_MODULE_PORT: {error}")))?; + let read = |name: &str| { + std::fs::read(dir.join(name)).map_err(|error| { + ActionOutcome::failed_setup(format!("cannot read the module's {name}: {error}")) + }) + }; + let identity = tonic::transport::Identity::from_pem(read("cert.pem")?, read("key.pem")?); + let token = String::from_utf8_lossy(&read("token")?).trim().to_string(); + + let service = guardian_module_sdk::serve::serve(SignerPolicy) + .instance(REMOTE, token) + .into_service(); + let listener = tokio::net::TcpListener::bind(("0.0.0.0", port)) + .await + .map_err(|error| { + ActionOutcome::failed_setup(format!("cannot listen on port {port}: {error}")) + })?; + let server = tonic::transport::Server::builder() + .tls_config(tonic::transport::ServerTlsConfig::new().identity(identity)) + .map_err(|error| ActionOutcome::failed_setup(format!("module TLS: {error}")))? + .add_service(service); + let incoming = tonic::transport::server::TcpIncoming::from(listener); + let (shutdown, stopped) = tokio::sync::oneshot::channel::<()>(); + let server = tokio::spawn(async move { + let stopped = async { + let _ = stopped.await; + }; + if let Err(error) = server.serve_with_incoming_shutdown(incoming, stopped).await { + eprintln!("the qualification policy module stopped: {error}"); + } + }); + Ok(Self { shutdown, server }) + } + + /// Stops listening and closes the connection the Guardian holds open. Aborting the task + /// is not enough: each accepted connection is served on a task of its own, which keeps + /// answering after the listener is gone. + async fn stop(self) { + let _ = self.shutdown.send(()); + let mut server = self.server; + if tokio::time::timeout(std::time::Duration::from_secs(10), &mut server) + .await + .is_err() + { + server.abort(); + } + } +} + +/// A remote module decides for the account over TLS while it is up, its failure refuses +/// (`on_error = "deny"`) and names it while it is down, and disabling it is the way out. +/// +/// The instance starts disabled in the catalog, because an enabled module that cannot be +/// reached stops the server from starting, and the module runs only for this action. So the +/// action always leaves it disabled and unassigned, whatever it concluded: left enabled, it +/// would stop the server coming back from the restart that follows the run. +pub async fn assert_unavailable(runner: &Runner) -> ActionOutcome { + let Some(fixtures) = runner.fixtures.as_ref() else { + return ActionOutcome::failed_setup("the server fixtures were not loaded"); + }; + let operator = match Operator::login(runner, fixtures).await { + Ok(operator) => operator, + Err(outcome) => return outcome, + }; + let mut proposal = match FixtureProposal::open(runner, fixtures).await { + Ok(proposal) => proposal, + Err(outcome) => return outcome, + }; + let module = match RemoteModule::start().await { + Ok(module) => module, + Err(outcome) => return outcome, + }; + let account = fixtures.account_id.clone(); + + let (outcome, module) = remote_lifecycle(&operator, &mut proposal, &account, module).await; + if let Some(module) = module { + module.stop().await; + } + let disabled = operator.switch(REMOTE, false).await; + let cleared = operator.clear(&account).await; + then_cleanup(then_cleanup(outcome, disabled), cleared) +} + +async fn remote_lifecycle( + operator: &Operator<'_>, + proposal: &mut FixtureProposal, + account: &str, + module: RemoteModule, +) -> (ActionOutcome, Option) { + if let Err(outcome) = operator.switch(REMOTE, true).await { + return (outcome, Some(module)); + } + if let Err(outcome) = operator + .assign(account, REMOTE, refuse_every_signer()) + .await + { + return (outcome, Some(module)); + } + let decided = expect_denied( + "the proposal check, with the remote module up,", + proposal.check().await, + REMOTE, + "signer_not_allowed", + ); + if !matches!(decided, ActionOutcome::Passed) { + return (decided, Some(module)); + } + + module.stop().await; + let down = match proposal.check().await { + Ok(()) => ActionOutcome::failed_product( + "the proposal check passed while the fail-closed remote module was down".to_string(), + ), + Err(error) => match error.module_refusal() { + Some(ModuleRefusal::Unavailable { + module: Some(unavailable), + }) if unavailable == REMOTE => ActionOutcome::Passed, + Some(refusal) => ActionOutcome::failed_product(format!( + "with the remote module down, the check was refused as {refusal:?}, not as {REMOTE} unavailable" + )), + None => ActionOutcome::failed_product(format!( + "with the remote module down, the check failed without a module refusal: {error}" + )), + }, + }; + if !matches!(down, ActionOutcome::Passed) { + return (down, None); + } + + if let Err(outcome) = operator.switch(REMOTE, false).await { + return (outcome, None); + } + ( + expect_allowed( + "the proposal check, with the down module disabled,", + proposal.check().await, + ), + None, + ) +} + +/// An operator disables a module that refuses, the account is let through at once, and the +/// stored switch survives a restart even though the catalog still says enabled. +/// +/// Two passes, as `restart-durability` has: the first disables and leaves it disabled, the +/// pass after the restart finds it disabled, with the disable in the params history, and +/// enables it again. +pub async fn assert_break_glass(runner: &Runner) -> ActionOutcome { + let Some(fixtures) = runner.fixtures.as_ref() else { + return ActionOutcome::failed_setup("the server fixtures were not loaded"); + }; + let operator = match Operator::login(runner, fixtures).await { + Ok(operator) => operator, + Err(outcome) => return outcome, + }; + if runner.post_restart && !runner.upgrade_target { + return assert_switch_survived(&operator).await; + } + + let mut proposal = match FixtureProposal::open(runner, fixtures).await { + Ok(proposal) => proposal, + Err(outcome) => return outcome, + }; + let account = fixtures.account_id.clone(); + if let Err(outcome) = operator.switch(SWITCH, true).await { + return outcome; + } + if let Err(outcome) = operator + .assign(&account, SWITCH, refuse_every_signer()) + .await + { + return outcome; + } + let outcome = first_failure([ + expect_denied( + "the proposal check", + proposal.check().await, + SWITCH, + "signer_not_allowed", + ), + match operator.switch(SWITCH, false).await { + Ok(()) => expect_allowed( + "the proposal check, with the module disabled,", + proposal.check().await, + ), + Err(outcome) => outcome, + }, + ]); + then_cleanup(outcome, operator.clear(&account).await) +} + +async fn assert_switch_survived(operator: &Operator<'_>) -> ActionOutcome { + let instance = match operator.instance(SWITCH).await { + Ok(instance) => instance, + Err(outcome) => return outcome, + }; + if instance["enabled"] != json!(false) || instance["catalog_enabled"] != json!(true) { + return ActionOutcome::failed_product(format!( + "after the restart {SWITCH} reads enabled = {} (catalog {}); the operator's disable \ + should have survived it", + instance["enabled"], instance["catalog_enabled"] + )); + } + let history = match operator.history(SWITCH).await { + Ok(history) => history, + Err(outcome) => return outcome, + }; + if !history.iter().any(|entry| entry["reason"] == REASON) { + return ActionOutcome::failed_product(format!( + "the params history of {SWITCH} does not record the disable: {history:?}" + )); + } + match operator.switch(SWITCH, true).await { + Ok(()) => match operator.instance(SWITCH).await { + Ok(instance) if instance["enabled"] == json!(true) => ActionOutcome::Passed, + Ok(instance) => { + ActionOutcome::failed_product(format!("enabling {SWITCH} again left it {instance}")) + } + Err(outcome) => outcome, + }, + Err(outcome) => outcome, + } +} + +/// Assigns the gate to the scenario's account with a cap of exactly what `asset-send` sends, +/// and reads it back through the account's own policy listing. +pub async fn assign_cap(runner: &Runner) -> ActionOutcome { + assign_to_funded_account(runner, CAP, |faucet| { + let mut limit = serde_json::Map::new(); + limit.insert(faucet.to_hex(), json!(super::live::P2ID_AMOUNT.to_string())); + json!({ "max_per_transaction": limit }) + }) + .await +} + +/// Assigns `qual-recipient` to the scenario's account with a denylist naming the funding +/// faucet, an account the scenario never pays, and reads it back through the account's own +/// policy listing. `deny_unknown` is left unset, so it is on. +pub async fn assign_recipient_denylist(runner: &Runner) -> ActionOutcome { + assign_to_funded_account( + runner, + RECIPIENT, + |faucet| json!({ "denylist": [faucet.to_hex()] }), + ) + .await +} + +/// Assigns `module` to the scenario's account with the params `params` builds from the funding +/// faucet, and checks the account's own policy listing shows them. +async fn assign_to_funded_account( + runner: &Runner, + module: &str, + params: impl FnOnce(miden_protocol::account::AccountId) -> Value, +) -> ActionOutcome { + let Some(fixtures) = runner.fixtures.as_ref() else { + return ActionOutcome::failed_setup("the server fixtures were not loaded"); + }; + let mut guard = runner.session.lock().await; + let Some(session) = guard.as_mut() else { + return ActionOutcome::failed_setup("no account has been created in this scenario"); + }; + let Some(faucet) = session.faucet else { + return ActionOutcome::failed_setup( + "the account was never funded, so there is no asset to build the params from", + ); + }; + let operator = match Operator::login(runner, fixtures).await { + Ok(operator) => operator, + Err(outcome) => return outcome, + }; + let params = params(faucet); + if let Err(outcome) = operator + .assign(&session.account_id.to_string(), module, params.clone()) + .await + { + return outcome; + } + + let policies = match session.clients[0].get_policies().await { + Ok(policies) => policies, + Err(error) => { + return ActionOutcome::failed_product(format!( + "listing the account's policies failed: {error}" + )); + } + }; + match policies.iter().find(|policy| policy.module_id == module) { + Some(policy) + if [&policy.params, &policy.account_layer] + .iter() + .any(|listed| listed.as_ref() == Some(¶ms)) => + { + ActionOutcome::Passed + } + Some(policy) => ActionOutcome::failed_product(format!( + "the account's policies list {module} without the params it was assigned: {policy:?}" + )), + None => ActionOutcome::failed_product(format!( + "the account's policies do not list the {module} it was assigned: {policies:?}" + )), + } +} + +/// One unit over the cap is refused by the dry-run check and at creation, naming the module and +/// `amount_cap_exceeded`; the capped amount itself passes the check. The transaction also pays +/// the network fee, so the capped amount passing is what shows the fee note is not counted as a +/// payment. +pub async fn assert_cap_refuses(runner: &Runner) -> ActionOutcome { + let mut guard = runner.session.lock().await; + let Some(session) = guard.as_mut() else { + return ActionOutcome::failed_setup("no account has been created in this scenario"); + }; + let (Some(faucet), Some(treasury)) = (session.faucet, session.treasury) else { + return ActionOutcome::failed_setup( + "the account was never funded, so it holds nothing to send", + ); + }; + let amount = super::live::P2ID_AMOUNT; + let send = |amount| TransactionType::transfer(treasury, faucet, amount); + let client = &mut session.clients[0]; + + let over_check = settled!(client.check_transaction(send(amount + 1))); + let over_check = expect_module_denied( + "the check of a payment over the cap", + over_check.map(drop), + CAP, + "amount_cap_exceeded", + ); + if !matches!(over_check, ActionOutcome::Passed) { + return over_check; + } + let over = settled!(client.propose_transaction(send(amount + 1))); + let over = expect_module_denied( + "a payment over the cap", + over.map(drop), + CAP, + "amount_cap_exceeded", + ); + if !matches!(over, ActionOutcome::Passed) { + return over; + } + match settled!(client.check_transaction(send(amount))) { + Ok(_) => ActionOutcome::Passed, + Err(error) => ActionOutcome::failed_product(format!( + "the check of a payment of exactly the cap was refused, so the fee may count as a \ + payment: {error}" + )), + } +} + +/// A payment to the blocked recipient is refused by the dry-run check and at creation, naming +/// the module and `recipient_blocked`; a payment to the treasury, which the denylist does not +/// name, passes the check. That transaction also carries the fee note, which has no recipient +/// a denylist can check, so it passing shows the fee note is not read as a payment. +pub async fn assert_recipient_refuses(runner: &Runner) -> ActionOutcome { + let mut guard = runner.session.lock().await; + let Some(session) = guard.as_mut() else { + return ActionOutcome::failed_setup("no account has been created in this scenario"); + }; + let (Some(faucet), Some(treasury)) = (session.faucet, session.treasury) else { + return ActionOutcome::failed_setup( + "the account was never funded, so it holds nothing to send", + ); + }; + let amount = super::live::P2ID_AMOUNT; + let client = &mut session.clients[0]; + + let blocked_check = + settled!(client.check_transaction(TransactionType::transfer(faucet, faucet, amount))); + let blocked_check = expect_module_denied( + "the check of a payment to the blocked recipient", + blocked_check.map(drop), + RECIPIENT, + "recipient_blocked", + ); + if !matches!(blocked_check, ActionOutcome::Passed) { + return blocked_check; + } + let blocked = + settled!(client.propose_transaction(TransactionType::transfer(faucet, faucet, amount))); + let blocked = expect_module_denied( + "a payment to the blocked recipient", + blocked.map(drop), + RECIPIENT, + "recipient_blocked", + ); + if !matches!(blocked, ActionOutcome::Passed) { + return blocked; + } + match settled!(client.check_transaction(TransactionType::transfer(treasury, faucet, amount))) { + Ok(_) => ActionOutcome::Passed, + Err(error) => ActionOutcome::failed_product(format!( + "the check of a payment to a recipient the denylist does not name was refused, so \ + the fee note may be read as a payment to an unknown recipient: {error}" + )), + } +} + +/// A multisig SDK call refused by `expected_module` for `expected_reason`. +fn expect_module_denied( + what: &str, + result: Result<(), MultisigError>, + expected_module: &str, + expected_reason: &str, +) -> ActionOutcome { + match result { + Ok(()) => ActionOutcome::failed_product(format!("{what} was accepted")), + Err(MultisigError::ModuleDenied { + module: Some(module), + reason_code, + .. + }) if module == expected_module && reason_code == expected_reason => ActionOutcome::Passed, + Err(error) => ActionOutcome::failed_product(format!( + "{what} was refused, but not by {expected_module} for {expected_reason}: {error}" + )), + } +} diff --git a/crates/server/Cargo.toml b/crates/server/Cargo.toml index be5d3fbff..20e3f7bec 100644 --- a/crates/server/Cargo.toml +++ b/crates/server/Cargo.toml @@ -44,7 +44,7 @@ zeroize = { version = "1.7", features = ["derive"] } serde_json = { workspace = true } tokio = { workspace = true, features = ["full"] } tokio-util = { version = "0.7", features = ["rt"] } -tonic = { workspace = true } +tonic = { workspace = true, features = ["tls-ring", "tls-native-roots"] } tonic-prost = { workspace = true } tonic-reflection = "0.14" prost = { workspace = true } @@ -57,6 +57,8 @@ tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt", "json"] miden-protocol = { workspace = true, features = ["testing"] } miden-standards = { workspace = true } futures = "0.3" +guardian-module-sdk = { path = "../guardian-module-sdk" } +toml = "0.8" futures-util = { version = "0.3", optional = true } rustls = { version = "0.23", optional = true } rustls-pemfile = { version = "2", optional = true } @@ -89,6 +91,7 @@ tonic-prost-build = { workspace = true } [dev-dependencies] bytes = "1" +reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] } futures = "0.3" miden-protocol = { workspace = true, features = ["testing"] } tokio = { workspace = true, features = ["full", "test-util"] } diff --git a/crates/server/README.md b/crates/server/README.md index 0681c0fff..acbb8f523 100644 --- a/crates/server/README.md +++ b/crates/server/README.md @@ -14,6 +14,28 @@ let builder = ServerBuilder::new() .grpc(true, 50051); ``` +## Custom builds + +`ServerBuilder::from_env()` configures the server from the environment exactly +as the `server` binary does; the binary is that call and `build`. A custom +build adds its own policy module kinds and runs: + +```rust +ServerBuilder::from_env() + .await? + .with_module_kind("acme-sanctions", Arc::new(acme_sanctions::Factory)) + .build() + .await? + .run() + .await; +``` + +Builder methods called after `from_env` override what the environment set. +This crate is not published to crates.io: depend on it at a release tag, from +the `custom-guardian` template each release attaches (pinned to the release's +`Cargo.lock`). See [`examples/custom-guardian`](../../examples/custom-guardian/README.md) +and the [custom modules guide](../../docs/guides/policy-modules/custom.md). + ## Configuration ### Environment Variables diff --git a/crates/server/bench/loadgen/src/config.rs b/crates/server/bench/loadgen/src/config.rs index 458c0f979..851325cb4 100644 --- a/crates/server/bench/loadgen/src/config.rs +++ b/crates/server/bench/loadgen/src/config.rs @@ -9,6 +9,11 @@ pub enum Scenario { StateWrite, Mixed, StateSync, + /// Only `push_delta`, one chained delta per operation; isolates the push path. + StatePush, + /// A proposal carrying the owner's approval, then the `push_delta` it allows: the multisig + /// write path since pushes need a matching approved proposal. One signer per account. + ProposalPush, Canonicalization, } @@ -85,6 +90,9 @@ impl RunConfig { if self.signers_per_account == 0 { bail!("signers-per-account must be greater than 0"); } + if self.scenario == Scenario::ProposalPush && self.signers_per_account != 1 { + bail!("proposal-push needs --signers-per-account 1: only the owner can approve"); + } if self.ops_per_user == 0 { bail!("ops-per-user must be greater than 0"); } diff --git a/crates/server/bench/loadgen/src/scenarios.rs b/crates/server/bench/loadgen/src/scenarios.rs index ecccad466..ecf23ea0b 100644 --- a/crates/server/bench/loadgen/src/scenarios.rs +++ b/crates/server/bench/loadgen/src/scenarios.rs @@ -48,6 +48,7 @@ pub struct UserContext { guardian_commitment: Word, signers_per_account: usize, auth: Option, + approver: Auth, last_timestamp_ms: i64, pub client: LoadClient, pub accounts: Vec, @@ -174,6 +175,54 @@ impl UserContext { } } + /// The owner's approval of `summary`, as proposal creation takes it. + fn approval(&self, summary: &TransactionSummary) -> Value { + let signature = self.approver.sign_word_hex(summary.to_commitment()); + let signature = match &self.approver { + Auth::FalconRpoSigner(_) => { + serde_json::json!({ "scheme": "falcon", "signature": signature }) + } + Auth::EcdsaSigner(signer) => serde_json::json!({ + "scheme": "ecdsa", + "signature": signature, + "public_key": signer.public_key_hex(), + }), + }; + serde_json::json!({ "signer_id": self.signer_commitment, "signature": signature }) + } + + async fn create_proposal( + &mut self, + account_id: &AccountId, + nonce: u64, + delta_payload: Value, + ) -> Result<()> { + match &mut self.client { + LoadClient::Grpc(client) => { + client + .push_delta_proposal(account_id, nonce, delta_payload) + .await?; + Ok(()) + } + LoadClient::Http(_) => { + let payload = serde_json::json!({ + "account_id": account_id.to_string(), + "nonce": nonce, + "delta_payload": delta_payload, + }); + let response = self + .http_request_with_auth( + Method::POST, + "/delta/proposal", + account_id, + Some(payload), + ) + .await?; + ensure_http_success(response, "push_delta_proposal").await + } + } + } + async fn push_state( &mut self, account_id: &AccountId, @@ -414,18 +463,28 @@ pub async fn seed_accounts(config: &RunConfig) -> Result> { let mut user_contexts = Vec::with_capacity(users); for user_id in 0..users { - let (auth, commitment) = match config.auth_scheme { + let (auth, approver, commitment) = match config.auth_scheme { AuthScheme::Falcon => { - let signer = FalconRpoSigner::new(FalconSecretKey::new()); + let key = FalconSecretKey::new(); + let signer = FalconRpoSigner::new(key.clone()); let commitment = commitment_hex_from_pubkey_hex(&signer.public_key_hex(), config.auth_scheme)?; - (Auth::FalconRpoSigner(signer), commitment) + ( + Auth::FalconRpoSigner(signer), + Auth::FalconRpoSigner(FalconRpoSigner::new(key)), + commitment, + ) } AuthScheme::Ecdsa => { - let signer = EcdsaSigner::new(EcdsaSecretKey::new()); + let key = EcdsaSecretKey::new(); + let signer = EcdsaSigner::new(key.clone()); let commitment = commitment_hex_from_pubkey_hex(&signer.public_key_hex(), config.auth_scheme)?; - (Auth::EcdsaSigner(signer), commitment) + ( + Auth::EcdsaSigner(signer), + Auth::EcdsaSigner(EcdsaSigner::new(key)), + commitment, + ) } }; let (client, user_auth) = build_client(config, auth).await?; @@ -437,6 +496,7 @@ pub async fn seed_accounts(config: &RunConfig) -> Result> { guardian_commitment: guardian_commitment_word, signers_per_account, auth: user_auth, + approver, last_timestamp_ms: 0, client, accounts: Vec::new(), @@ -549,6 +609,10 @@ async fn run_worker(config: &RunConfig, user: &mut UserContext) -> WorkerMetrics run_read_operation(user, op_index, account_count).await } } + Scenario::StatePush => run_push_state_operation(user, op_index, account_count).await, + Scenario::ProposalPush => { + run_proposal_push_operation(user, op_index, account_count).await + } Scenario::Canonicalization => { run_canonicalization_operation(config, user, op_index, account_count).await } @@ -582,9 +646,12 @@ async fn run_worker(config: &RunConfig, user: &mut UserContext) -> WorkerMetrics fn scenario_op_count(config: &RunConfig, account_count: usize) -> usize { match config.scenario { Scenario::Canonicalization => account_count, - Scenario::StateRead | Scenario::StateWrite | Scenario::Mixed | Scenario::StateSync => { - usize::try_from(config.ops_per_user).unwrap_or(0) - } + Scenario::StateRead + | Scenario::StateWrite + | Scenario::Mixed + | Scenario::StateSync + | Scenario::StatePush + | Scenario::ProposalPush => usize::try_from(config.ops_per_user).unwrap_or(0), } } @@ -804,11 +871,53 @@ fn create_account_seed( }) } +async fn run_proposal_push_operation( + user: &mut UserContext, + op_index: usize, + account_count: usize, +) -> Result<()> { + let account_index = op_index % account_count; + let (account_id, nonce, prev_commitment, summary) = { + let account = &user.accounts[account_index]; + let nonce = account.next_nonce; + ( + account.account_id, + nonce, + account.commitment.clone(), + delta_summary(&account.account_id, nonce)?, + ) + }; + let delta_payload = summary.to_json(); + let proposal = serde_json::json!({ + "tx_summary": delta_payload, + "metadata": { "proposal_type": "custom" }, + "signatures": [user.approval(&summary)], + }); + user.create_proposal(&account_id, nonce, proposal).await?; + + let new_commitment = user + .push_state(&account_id, nonce, prev_commitment, delta_payload) + .await?; + + if let Some(account) = user.accounts.get_mut(account_index) { + account.next_nonce = nonce + 1; + if let Some(commitment) = new_commitment { + account.commitment = commitment; + } + } + + Ok(()) +} + /// An empty transaction's summary that leaves the account at `nonce`, one past the state it /// builds on: a transaction increments the nonce by one, and GUARDIAN refuses a delta labelled /// with any nonce but the one it leaves the account at (issue #518). The nonce is also the /// salt, so every push on an account has a summary of its own. fn create_delta_payload(account_id: &AccountId, nonce: u64) -> Result { + Ok(delta_summary(account_id, nonce)?.to_json()) +} + +fn delta_summary(account_id: &AccountId, nonce: u64) -> Result { let account_delta = AccountDelta::new( account_id.to_owned(), AccountStoragePatch::default(), @@ -834,7 +943,7 @@ fn create_delta_payload(account_id: &AccountId, nonce: u64) -> Result { ZERO, ]), ); - Ok(tx_summary.to_json()) + Ok(tx_summary) } fn build_signer_commitments( diff --git a/crates/server/build.rs b/crates/server/build.rs index 3d94a16cb..3136a40b4 100644 --- a/crates/server/build.rs +++ b/crates/server/build.rs @@ -17,6 +17,9 @@ fn main() -> Result<(), Box> { .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string()) }) .unwrap_or_else(|| "unknown".to_string()); + // Declaring any rerun-if-changed below replaces Cargo's default, so the proto must be + // listed too or edits to it compile against stale generated code. + println!("cargo:rerun-if-changed=proto/guardian.proto"); println!("cargo:rustc-env=GUARDIAN_GIT_SHA={git_sha}"); println!("cargo:rerun-if-changed=proto/guardian.proto"); println!("cargo:rerun-if-env-changed=GUARDIAN_GIT_SHA"); diff --git a/crates/server/examples/bench_server.rs b/crates/server/examples/bench_server.rs new file mode 100644 index 000000000..55137232b --- /dev/null +++ b/crates/server/examples/bench_server.rs @@ -0,0 +1,60 @@ +//! The server as `main` builds it, on configurable ports and without canonicalization, so pushes +//! commit optimistically and never wait on a node. For benchmarks next to a running server. +//! +//! ```text +//! BENCH_HTTP_PORT=3100 BENCH_GRPC_PORT=50151 cargo run --release -p guardian-server --example bench_server +//! ``` + +use server::ack::AckRegistry; +use server::builder::{ServerBuilder, storage::StorageMetadataBuilder}; +use server::logging::LoggingConfig; +use server::middleware::{BodyLimitConfig, CorsConfig, RateLimitConfig}; +use server::network::{NetworkType, RpcSettings}; + +fn port(var: &str, default: u16) -> u16 { + std::env::var(var) + .ok() + .and_then(|value| value.parse().ok()) + .unwrap_or(default) +} + +#[tokio::main] +async fn main() { + let keystore_path: std::path::PathBuf = std::env::var("GUARDIAN_KEYSTORE_PATH") + .expect("GUARDIAN_KEYSTORE_PATH is required") + .into(); + let (storage_backend, metadata, auditor, coordination) = StorageMetadataBuilder::from_env() + .build() + .await + .expect("Failed to initialize storage backends"); + let ack = AckRegistry::new(keystore_path) + .await + .expect("Failed to initialize ack registry"); + let network_type = + NetworkType::from_env("GUARDIAN_NETWORK_TYPE").expect("Failed to resolve network type"); + + ServerBuilder::new() + .with_logging(LoggingConfig::default()) + .network(network_type) + .with_rpc(RpcSettings::from_env(network_type).expect("Invalid RPC configuration")) + .with_canonicalization(None) + .with_rate_limit(RateLimitConfig::from_env()) + .with_body_limit(BodyLimitConfig::from_env()) + .storage(storage_backend) + .metadata(metadata) + .auditor(auditor) + .coordination(coordination) + .ack(ack) + .http(true, port("BENCH_HTTP_PORT", 3100)) + .grpc(true, port("BENCH_GRPC_PORT", 50151)) + .cors( + CorsConfig::from_env() + .expect("Failed to initialize CORS config") + .layer(), + ) + .build() + .await + .expect("Failed to build server") + .run() + .await; +} diff --git a/crates/server/examples/modules_admin.rs b/crates/server/examples/modules_admin.rs new file mode 100644 index 000000000..7c663a0af --- /dev/null +++ b/crates/server/examples/modules_admin.rs @@ -0,0 +1,125 @@ +//! Operator CLI for the policy module endpoints. +//! +//! ```text +//! modules_admin keygen +//! modules_admin [--url http://localhost:3000] --key GET /modules +//! modules_admin [--url ...] --key PUT /modules/blocklist/params '{"params":{...},"reason":"..."}' +//! ``` + +use guardian_shared::hex::{FromHex, IntoHex}; +use miden_protocol::Word; +use miden_protocol::crypto::dsa::falcon512_poseidon2::SecretKey; +use miden_protocol::utils::serde::{Deserializable, Serializable}; + +type Error = Box; + +fn load_key(path: &str) -> Result { + let bytes = hex::decode(std::fs::read_to_string(path)?.trim())?; + Ok(SecretKey::read_from_bytes(&bytes)?) +} + +/// Writes the operator key readable by its owner only, and never over an existing file. +fn write_private(path: &str, contents: &str) -> Result<(), Error> { + use std::io::Write; + let mut options = std::fs::OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(unix)] + std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600); + options.open(path)?.write_all(contents.as_bytes())?; + Ok(()) +} + +fn keygen(path: &str) -> Result<(), Error> { + let key = SecretKey::new(); + write_private(path, &hex::encode(key.to_bytes()))?; + let public_key = key.public_key(); + println!("key written to {path}"); + println!("commitment: {}", public_key.to_commitment().into_hex()); + println!("allowlist entry (put it in the GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE array):"); + println!( + "{}", + serde_json::json!({ + "public_key": public_key.into_hex(), + "permissions": ["dashboard:read", "policies:write", "policies:write_global"] + }) + ); + Ok(()) +} + +async fn login(http: &reqwest::Client, url: &str, key: &SecretKey) -> Result { + let commitment = key.public_key().to_commitment().into_hex(); + let challenge: serde_json::Value = http + .get(format!("{url}/auth/challenge")) + .query(&[("commitment", &commitment)]) + .send() + .await? + .error_for_status()? + .json() + .await?; + let digest = challenge["challenge"]["signing_digest"] + .as_str() + .ok_or("challenge has no signing_digest")?; + let signature = key.sign(Word::from_hex(digest)?); + let response = http + .post(format!("{url}/auth/verify")) + .json(&serde_json::json!({ + "commitment": commitment, + "signature": format!("0x{}", hex::encode(signature.to_bytes())), + })) + .send() + .await?; + let cookie = response + .headers() + .get(reqwest::header::SET_COOKIE) + .and_then(|value| value.to_str().ok()) + .and_then(|value| value.split(';').next()) + .map(str::to_string) + .ok_or("login failed: no session cookie (is the key in the operator allowlist?)")?; + response.error_for_status()?; + Ok(cookie) +} + +#[tokio::main] +async fn main() -> Result<(), Error> { + let mut args: Vec = std::env::args().skip(1).collect(); + if args.first().map(String::as_str) == Some("keygen") { + return keygen(args.get(1).ok_or("keygen needs a key file path")?); + } + let mut url = "http://localhost:3000".to_string(); + let mut key_path = None; + while args.first().is_some_and(|arg| arg.starts_with("--")) { + let flag = args.remove(0); + let value = (!args.is_empty()) + .then(|| args.remove(0)) + .ok_or("flag needs a value")?; + match flag.as_str() { + "--url" => url = value, + "--key" => key_path = Some(value), + other => return Err(format!("unknown flag {other}").into()), + } + } + let [method, path, rest @ ..] = args.as_slice() else { + return Err("usage: modules_admin --key [JSON]".into()); + }; + let key = load_key(key_path.as_deref().ok_or("--key is required")?)?; + let http = reqwest::Client::new(); + let cookie = login(&http, &url, &key).await?; + + let request = http + .request(method.parse()?, format!("{url}/dashboard{path}")) + .header(reqwest::header::COOKIE, cookie); + let request = match rest.first() { + Some(body) => request + .header(reqwest::header::CONTENT_TYPE, "application/json") + .body(body.clone()), + None => request, + }; + let response = request.send().await?; + let status = response.status(); + let text = response.text().await?; + let pretty = serde_json::from_str::(&text) + .and_then(|value| serde_json::to_string_pretty(&value)) + .unwrap_or(text); + println!("{status}\n{pretty}"); + Ok(()) +} diff --git a/crates/server/migrations/2026-10-15-000001_guardian_modules/down.sql b/crates/server/migrations/2026-10-15-000001_guardian_modules/down.sql new file mode 100644 index 000000000..6bea61760 --- /dev/null +++ b/crates/server/migrations/2026-10-15-000001_guardian_modules/down.sql @@ -0,0 +1,4 @@ +DROP TABLE module_params_history; +DROP TABLE module_state_version; +DROP TABLE module_account_params; +DROP TABLE module_instances; diff --git a/crates/server/migrations/2026-10-15-000001_guardian_modules/up.sql b/crates/server/migrations/2026-10-15-000001_guardian_modules/up.sql new file mode 100644 index 000000000..f96374526 --- /dev/null +++ b/crates/server/migrations/2026-10-15-000001_guardian_modules/up.sql @@ -0,0 +1,53 @@ +-- Policy module state (RFC 0002, issue #251). Kept apart from account_metadata, +-- which configure_account rewrites in full: operators write these rows, cosigners +-- write the metadata row. Instance definitions stay in the catalog file. + +CREATE TABLE module_instances ( + module_id TEXT PRIMARY KEY, + enabled BOOLEAN NOT NULL, + global_params JSONB NOT NULL, + seeded_params JSONB NOT NULL, + updated_at TIMESTAMPTZ NOT NULL, + updated_by TEXT NOT NULL +); + +-- Account layers on scope = all instances (only add restrictions) and +-- assignments of default / assigned instances (position = evaluation order). +CREATE TABLE module_account_params ( + account_id TEXT NOT NULL, + module_id TEXT NOT NULL, + kind TEXT NOT NULL CHECK (kind IN ('layer', 'assignment')), + position INTEGER NOT NULL, + params JSONB NOT NULL, + updated_at TIMESTAMPTZ NOT NULL, + updated_by TEXT NOT NULL, + PRIMARY KEY (account_id, module_id) +); + +CREATE INDEX module_account_params_module_idx ON module_account_params (module_id); + +-- One row. Every module write takes this row lock first and bumps it, so +-- writes serialize and the version moves in commit order; replicas key their +-- cache on it. A sequence would hand out numbers in start order instead, and a +-- slow commit with a lower number would never be noticed. +CREATE TABLE module_state_version ( + singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton), + version BIGINT NOT NULL +); + +INSERT INTO module_state_version (singleton, version) VALUES (TRUE, 0); + +-- Append-only; rows of one write share its version. +CREATE TABLE module_params_history ( + id BIGSERIAL PRIMARY KEY, + version BIGINT NOT NULL, + module_id TEXT NOT NULL, + account_id TEXT NULL, + previous_params JSONB NOT NULL, + new_params JSONB NOT NULL, + operator TEXT NOT NULL, + reason TEXT NOT NULL, + changed_at TIMESTAMPTZ NOT NULL +); + +CREATE INDEX module_params_history_module_idx ON module_params_history (module_id, version); diff --git a/crates/server/migrations/2026-11-09-000001_module_snapshot/down.sql b/crates/server/migrations/2026-11-09-000001_module_snapshot/down.sql new file mode 100644 index 000000000..7621baebf --- /dev/null +++ b/crates/server/migrations/2026-11-09-000001_module_snapshot/down.sql @@ -0,0 +1,2 @@ +DROP FUNCTION IF EXISTS guardian_module_snapshot(TEXT, BIGINT); +DROP INDEX IF EXISTS module_params_history_account_idx; diff --git a/crates/server/migrations/2026-11-09-000001_module_snapshot/up.sql b/crates/server/migrations/2026-11-09-000001_module_snapshot/up.sql new file mode 100644 index 000000000..dae9fe1d5 --- /dev/null +++ b/crates/server/migrations/2026-11-09-000001_module_snapshot/up.sql @@ -0,0 +1,57 @@ +-- Default copies at registration look for an account's history under the module +-- state lock; without this index that lookup scanned the whole history. +CREATE INDEX module_params_history_account_idx + ON module_params_history (account_id) + WHERE account_id IS NOT NULL; + +-- Everything one module evaluation reads, in one call: the params version, the +-- account's layers and assignments and, unless the caller's cached version is +-- current, the instance rows. STABLE, so every statement below sees the snapshot +-- of the calling statement: the rows belong to the returned version without the +-- caller re-reading the version. +CREATE FUNCTION guardian_module_snapshot( + p_account_id TEXT, + p_cached_version BIGINT +) +RETURNS TABLE ( + version BIGINT, + instances JSONB, + account_params JSONB +) +LANGUAGE plpgsql STABLE AS $$ +DECLARE + v_version BIGINT; + v_instances JSONB; + v_account JSONB; +BEGIN + SELECT s.version INTO v_version FROM module_state_version s; + + IF p_cached_version IS DISTINCT FROM v_version THEN + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'module_id', i.module_id, + 'enabled', i.enabled, + 'global_params', i.global_params, + 'seeded_params', i.seeded_params, + 'updated_at', i.updated_at, + 'updated_by', i.updated_by + ) ORDER BY i.module_id), '[]'::jsonb) + INTO v_instances + FROM module_instances i; + END IF; + + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'account_id', p.account_id, + 'module_id', p.module_id, + 'kind', p.kind, + 'position', p.position, + 'params', p.params, + 'updated_at', p.updated_at, + 'updated_by', p.updated_by + ) ORDER BY p.position, p.module_id), '[]'::jsonb) + INTO v_account + FROM module_account_params p + WHERE p.account_id = p_account_id; + + RETURN QUERY SELECT v_version, v_instances, v_account; +END; +$$; diff --git a/crates/server/migrations/2026-11-10-000001_module_seed_assignment/down.sql b/crates/server/migrations/2026-11-10-000001_module_seed_assignment/down.sql new file mode 100644 index 000000000..64b95e2b2 --- /dev/null +++ b/crates/server/migrations/2026-11-10-000001_module_seed_assignment/down.sql @@ -0,0 +1 @@ +DROP FUNCTION IF EXISTS guardian_module_seed_assignment(TEXT, JSONB, TEXT, TEXT, TIMESTAMPTZ); diff --git a/crates/server/migrations/2026-11-10-000001_module_seed_assignment/up.sql b/crates/server/migrations/2026-11-10-000001_module_seed_assignment/up.sql new file mode 100644 index 000000000..41c62079b --- /dev/null +++ b/crates/server/migrations/2026-11-10-000001_module_seed_assignment/up.sql @@ -0,0 +1,54 @@ +-- The default modules a first registration copies into its account, in one call. +-- Every module write takes the module_state_version row lock, so a registration +-- that held it across a round trip per row made every other registration and +-- operator write wait for all of them. Here the lock is taken, the account is +-- checked and its rows and history are written inside one statement, so the lock +-- is held for that statement and its commit only. +-- +-- p_modules is the assignment in evaluation order: +-- [{"module_id": "...", "params": {...}}, ...]. Writes only into an account with +-- no assignment and no history, so an operator's earlier write always wins. +-- Returns the version the copy committed as, or NULL when it wrote nothing (the +-- version does not move then). +CREATE FUNCTION guardian_module_seed_assignment( + p_account_id TEXT, + p_modules JSONB, + p_operator TEXT, + p_reason TEXT, + p_changed_at TIMESTAMPTZ +) +RETURNS BIGINT +LANGUAGE plpgsql AS $$ +DECLARE + v_version BIGINT; +BEGIN + PERFORM 1 FROM module_state_version FOR UPDATE; + + IF EXISTS (SELECT 1 FROM module_account_params + WHERE account_id = p_account_id AND kind = 'assignment') + OR EXISTS (SELECT 1 FROM module_params_history + WHERE account_id = p_account_id) THEN + RETURN NULL; + END IF; + + UPDATE module_state_version SET version = version + 1 + RETURNING version INTO v_version; + + INSERT INTO module_account_params + (account_id, module_id, kind, position, params, updated_at, updated_by) + SELECT p_account_id, m.value->>'module_id', 'assignment', + (m.ordinality - 1)::INTEGER, m.value->'params', p_changed_at, p_operator + FROM jsonb_array_elements(p_modules) WITH ORDINALITY AS m(value, ordinality); + + INSERT INTO module_params_history + (version, module_id, account_id, previous_params, new_params, operator, reason, + changed_at) + SELECT v_version, m.value->>'module_id', p_account_id, 'null'::jsonb, + m.value->'params', p_operator, p_reason, p_changed_at + FROM jsonb_array_elements(p_modules) AS m(value) + WHERE m.value->'params' <> 'null'::jsonb + ORDER BY m.value->>'module_id'; + + RETURN v_version; +END; +$$; diff --git a/crates/server/migrations/2026-11-10-000002_module_account_version/down.sql b/crates/server/migrations/2026-11-10-000002_module_account_version/down.sql new file mode 100644 index 000000000..77014a26b --- /dev/null +++ b/crates/server/migrations/2026-11-10-000002_module_account_version/down.sql @@ -0,0 +1,109 @@ +-- Back to one params version for every module write. Account writes made meanwhile committed +-- as their account's versions, which can be above the instance version, and a write that +-- changed nothing moved its account's version without a history row; the single version +-- continues above every one of them, so no later write reuses a number a delta recorded. +UPDATE module_state_version + SET version = GREATEST(version, + (SELECT COALESCE(MAX(version), 0) FROM module_params_history), + (SELECT COALESCE(MAX(version), 0) FROM module_account_version)); + +DROP INDEX module_params_history_module_idx; +CREATE INDEX module_params_history_module_idx ON module_params_history (module_id, version); + +DROP FUNCTION guardian_module_snapshot(TEXT, BIGINT); + +CREATE FUNCTION guardian_module_snapshot( + p_account_id TEXT, + p_cached_version BIGINT +) +RETURNS TABLE ( + version BIGINT, + instances JSONB, + account_params JSONB +) +LANGUAGE plpgsql STABLE AS $$ +DECLARE + v_version BIGINT; + v_instances JSONB; + v_account JSONB; +BEGIN + SELECT s.version INTO v_version FROM module_state_version s; + + IF p_cached_version IS DISTINCT FROM v_version THEN + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'module_id', i.module_id, + 'enabled', i.enabled, + 'global_params', i.global_params, + 'seeded_params', i.seeded_params, + 'updated_at', i.updated_at, + 'updated_by', i.updated_by + ) ORDER BY i.module_id), '[]'::jsonb) + INTO v_instances + FROM module_instances i; + END IF; + + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'account_id', p.account_id, + 'module_id', p.module_id, + 'kind', p.kind, + 'position', p.position, + 'params', p.params, + 'updated_at', p.updated_at, + 'updated_by', p.updated_by + ) ORDER BY p.position, p.module_id), '[]'::jsonb) + INTO v_account + FROM module_account_params p + WHERE p.account_id = p_account_id; + + RETURN QUERY SELECT v_version, v_instances, v_account; +END; +$$; + +CREATE OR REPLACE FUNCTION guardian_module_seed_assignment( + p_account_id TEXT, + p_modules JSONB, + p_operator TEXT, + p_reason TEXT, + p_changed_at TIMESTAMPTZ +) +RETURNS BIGINT +LANGUAGE plpgsql AS $$ +DECLARE + v_version BIGINT; +BEGIN + PERFORM 1 FROM module_state_version FOR UPDATE; + + IF EXISTS (SELECT 1 FROM module_account_params + WHERE account_id = p_account_id AND kind = 'assignment') + OR EXISTS (SELECT 1 FROM module_params_history + WHERE account_id = p_account_id) THEN + RETURN NULL; + END IF; + + UPDATE module_state_version SET version = version + 1 + RETURNING version INTO v_version; + + INSERT INTO module_account_params + (account_id, module_id, kind, position, params, updated_at, updated_by) + SELECT p_account_id, m.value->>'module_id', 'assignment', + (m.ordinality - 1)::INTEGER, m.value->'params', p_changed_at, p_operator + FROM jsonb_array_elements(p_modules) WITH ORDINALITY AS m(value, ordinality); + + INSERT INTO module_params_history + (version, module_id, account_id, previous_params, new_params, operator, reason, + changed_at) + SELECT v_version, m.value->>'module_id', p_account_id, 'null'::jsonb, + m.value->'params', p_operator, p_reason, p_changed_at + FROM jsonb_array_elements(p_modules) AS m(value) + WHERE m.value->'params' <> 'null'::jsonb + ORDER BY m.value->>'module_id'; + + RETURN v_version; +END; +$$; + +CREATE INDEX module_params_history_account_idx + ON module_params_history (account_id) + WHERE account_id IS NOT NULL; + +DROP TABLE module_account_version; diff --git a/crates/server/migrations/2026-11-10-000002_module_account_version/up.sql b/crates/server/migrations/2026-11-10-000002_module_account_version/up.sql new file mode 100644 index 000000000..d2cab7bf6 --- /dev/null +++ b/crates/server/migrations/2026-11-10-000002_module_account_version/up.sql @@ -0,0 +1,144 @@ +-- Per-account params versions. module_state_version now moves only on writes to the +-- instance rows, so replicas rebuild their instance cache only when an instance changes. +-- A write to one account's layers or assignment, including the default copy at +-- registration, bumps that account's row here instead: it serializes with writes to the +-- same account only, and every other account and every replica's cache is untouched. +-- A signed delta records both versions. +CREATE TABLE module_account_version ( + account_id TEXT PRIMARY KEY, + version BIGINT NOT NULL +); + +-- History rows keep the version they were written with. An account's earlier rows carry +-- global numbers, increasing in that account's write order, so its next version continues +-- above the highest of them. +INSERT INTO module_account_version (account_id, version) +SELECT account_id, MAX(version) + FROM module_params_history + WHERE account_id IS NOT NULL + GROUP BY account_id; + +DROP FUNCTION guardian_module_snapshot(TEXT, BIGINT); + +-- Everything one module evaluation reads, in one call: the instance params version, the +-- account's params version and rows and, unless the caller's cached instance version is +-- current, the instance rows. STABLE, so every statement below sees the snapshot of the +-- calling statement: the rows belong to the returned versions. +CREATE FUNCTION guardian_module_snapshot( + p_account_id TEXT, + p_cached_version BIGINT +) +RETURNS TABLE ( + version BIGINT, + account_version BIGINT, + instances JSONB, + account_params JSONB +) +LANGUAGE plpgsql STABLE AS $$ +DECLARE + v_version BIGINT; + v_account_version BIGINT; + v_instances JSONB; + v_account JSONB; +BEGIN + SELECT s.version INTO v_version FROM module_state_version s; + + SELECT COALESCE(MAX(a.version), 0) INTO v_account_version + FROM module_account_version a + WHERE a.account_id = p_account_id; + + IF p_cached_version IS DISTINCT FROM v_version THEN + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'module_id', i.module_id, + 'enabled', i.enabled, + 'global_params', i.global_params, + 'seeded_params', i.seeded_params, + 'updated_at', i.updated_at, + 'updated_by', i.updated_by + ) ORDER BY i.module_id), '[]'::jsonb) + INTO v_instances + FROM module_instances i; + END IF; + + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'account_id', p.account_id, + 'module_id', p.module_id, + 'kind', p.kind, + 'position', p.position, + 'params', p.params, + 'updated_at', p.updated_at, + 'updated_by', p.updated_by + ) ORDER BY p.position, p.module_id), '[]'::jsonb) + INTO v_account + FROM module_account_params p + WHERE p.account_id = p_account_id; + + RETURN QUERY SELECT v_version, v_account_version, v_instances, v_account; +END; +$$; + +-- The default modules a first registration copies into its account, in one call. It locks +-- only this account's version row, so registrations of different accounts and operator +-- writes to other accounts or to instances never wait for it. +-- +-- p_modules is the assignment in evaluation order: +-- [{"module_id": "...", "params": {...}}, ...]. Writes only into an account no write has +-- touched yet (version 0, no assignment), so an operator's earlier write always wins. +-- Returns the account version the copy committed as, or NULL when it wrote nothing (the +-- version does not move then). +CREATE OR REPLACE FUNCTION guardian_module_seed_assignment( + p_account_id TEXT, + p_modules JSONB, + p_operator TEXT, + p_reason TEXT, + p_changed_at TIMESTAMPTZ +) +RETURNS BIGINT +LANGUAGE plpgsql AS $$ +DECLARE + v_version BIGINT; +BEGIN + INSERT INTO module_account_version (account_id, version) + VALUES (p_account_id, 0) + ON CONFLICT (account_id) DO NOTHING; + + SELECT a.version INTO v_version + FROM module_account_version a + WHERE a.account_id = p_account_id + FOR UPDATE; + + IF v_version <> 0 + OR EXISTS (SELECT 1 FROM module_account_params + WHERE account_id = p_account_id AND kind = 'assignment') THEN + RETURN NULL; + END IF; + + v_version := 1; + UPDATE module_account_version SET version = v_version WHERE account_id = p_account_id; + + INSERT INTO module_account_params + (account_id, module_id, kind, position, params, updated_at, updated_by) + SELECT p_account_id, m.value->>'module_id', 'assignment', + (m.ordinality - 1)::INTEGER, m.value->'params', p_changed_at, p_operator + FROM jsonb_array_elements(p_modules) WITH ORDINALITY AS m(value, ordinality); + + INSERT INTO module_params_history + (version, module_id, account_id, previous_params, new_params, operator, reason, + changed_at) + SELECT v_version, m.value->>'module_id', p_account_id, 'null'::jsonb, + m.value->'params', p_operator, p_reason, p_changed_at + FROM jsonb_array_elements(p_modules) AS m(value) + WHERE m.value->'params' <> 'null'::jsonb + ORDER BY m.value->>'module_id'; + + RETURN v_version; +END; +$$; + +-- The account history lookup the default copy made is gone; the version row answers it. +DROP INDEX IF EXISTS module_params_history_account_idx; + +-- A module's history is listed newest first by row id, since the versions of its global and +-- account entries come from different counters. +DROP INDEX module_params_history_module_idx; +CREATE INDEX module_params_history_module_idx ON module_params_history (module_id, id); diff --git a/crates/server/proto/guardian.proto b/crates/server/proto/guardian.proto index b67975508..bc8565b8c 100644 --- a/crates/server/proto/guardian.proto +++ b/crates/server/proto/guardian.proto @@ -87,6 +87,17 @@ service Guardian { // x-timestamp), raw or as EIP-712 typed data (`x-auth-format: eip712`). // Wallet-only. Mirror of HTTP POST /session/revoke-all. rpc RevokeAllSessions(RevokeAllSessionsRequest) returns (RevokeAllSessionsResponse); + + // The policy modules that apply to the account, as far as each instance's + // catalog entry discloses them (RFC 0002 section 2.7). Mirror of HTTP + // GET /policies. + rpc GetPolicies(GetPoliciesRequest) returns (GetPoliciesResponse); + + // Dry run of PushDeltaProposal: the same checks and proposal-creation + // modules, nothing stored, no proposal slot taken. Advisory; approval still + // decides. Rate limited per account and signer. Mirror of HTTP + // POST /delta/proposal/check. + rpc CheckDeltaProposal(CheckDeltaProposalRequest) returns (CheckDeltaProposalResponse); } // Auth configuration - one of the auth types @@ -360,6 +371,40 @@ message PushDeltaProposalResponse { string error_code = 5; } +message CheckDeltaProposalRequest { + string account_id = 1; + uint64 nonce = 2; + string delta_payload = 3; // JSON string, as for PushDeltaProposal +} + +message CheckDeltaProposalResponse { + bool success = 1; + string message = 2; + bool allowed = 3; // true on success; a refusal is returned as an error status + bool complete = 4; // false when an instance that opts out of dry runs was skipped + string error_code = 5; +} + +message GetPoliciesRequest { + string account_id = 1; +} + +message PolicyEntry { + string module_id = 1; + repeated string hooks = 2; + string description = 3; + optional string params = 4; // JSON object; only where the instance discloses params + optional string account_layer = 5; // JSON object; this account's layer, where disclosed +} + +message GetPoliciesResponse { + bool success = 1; + string message = 2; + string account_id = 3; + repeated PolicyEntry policies = 4; // evaluation order + string error_code = 5; +} + // Get delta proposals request message GetDeltaProposalsRequest { string account_id = 1; diff --git a/crates/server/src/api/dashboard_modules.rs b/crates/server/src/api/dashboard_modules.rs new file mode 100644 index 000000000..b747b5ed1 --- /dev/null +++ b/crates/server/src/api/dashboard_modules.rs @@ -0,0 +1,681 @@ +//! Operator endpoints for policy module parameters. + +use axum::Json; +use axum::extract::{Extension, Path, State}; +use serde::Deserialize; + +use crate::dashboard::AuthenticatedOperator; +use crate::error::{GuardianError, Result}; +use crate::modules::admin::{ + self, AccountModulesView, ModuleCatalogView, ModuleInstanceView, ParamsHistoryView, +}; +use crate::modules::store::Assigned; +use crate::state::AppState; + +const BODY_LIMIT: usize = 256 * 1024; + +#[derive(Debug, Deserialize, utoipa::ToSchema)] +pub struct ParamsBody { + #[schema(value_type = Object)] + pub params: serde_json::Value, + pub reason: String, + /// The params version the change was made against: `params_version` for a global write, + /// `account_params_version` for an account layer. Set, a write after another change is + /// refused with 409 `GUARDIAN_MODULE_PARAMS_STALE`. + #[serde(default)] + pub expected_version: Option, +} + +#[derive(Debug, Deserialize, utoipa::ToSchema)] +pub struct LayerRemovalBody { + pub reason: String, + /// The `account_params_version` the removal was made against; see [`ParamsBody`]. + #[serde(default)] + pub expected_version: Option, +} + +#[derive(Debug, Deserialize, utoipa::ToSchema)] +pub struct ReasonBody { + pub reason: String, +} + +#[derive(Debug, Deserialize, utoipa::ToSchema)] +pub struct AssignmentBody { + pub modules: Vec, + pub reason: String, + /// The `account_params_version` the assignment was made against; see [`ParamsBody`]. + #[serde(default)] + pub expected_version: Option, +} + +async fn body( + request: axum::extract::Request, +) -> Result<(T, Option)> { + let client_ip = crate::middleware::client_ip::extract_client_ip(&request); + let (_parts, body) = request.into_parts(); + let bytes = axum::body::to_bytes(body, BODY_LIMIT).await.map_err(|_| { + GuardianError::ModuleWriteRefused(format!( + "the request body could not be read or is over {BODY_LIMIT} bytes" + )) + })?; + let malformed = |e: serde_json::Error| { + GuardianError::ModuleWriteRefused(format!("malformed request body: {e}")) + }; + serde::de::DeserializeSeed::deserialize( + UniqueKeys, + &mut serde_json::Deserializer::from_slice(&bytes), + ) + .map_err(malformed)?; + let parsed = serde_json::from_slice(&bytes).map_err(malformed)?; + Ok((parsed, client_ip)) +} + +/// Walks a JSON document and fails on the first object that names a key twice. `serde_json` +/// keeps the last of two equal keys without a word, so `{"cap": "5", "cap": "50"}` would store +/// a cap of 50 that the operator may not have meant; params are refused instead. +struct UniqueKeys; + +impl<'de> serde::de::DeserializeSeed<'de> for UniqueKeys { + type Value = (); + + fn deserialize>( + self, + deserializer: D, + ) -> std::result::Result<(), D::Error> { + deserializer.deserialize_any(self) + } +} + +impl<'de> serde::de::Visitor<'de> for UniqueKeys { + type Value = (); + + fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + f.write_str("a JSON value") + } + + fn visit_bool(self, _: bool) -> std::result::Result<(), E> { + Ok(()) + } + + fn visit_i64(self, _: i64) -> std::result::Result<(), E> { + Ok(()) + } + + fn visit_u64(self, _: u64) -> std::result::Result<(), E> { + Ok(()) + } + + fn visit_f64(self, _: f64) -> std::result::Result<(), E> { + Ok(()) + } + + fn visit_str(self, _: &str) -> std::result::Result<(), E> { + Ok(()) + } + + fn visit_unit(self) -> std::result::Result<(), E> { + Ok(()) + } + + fn visit_seq>( + self, + mut seq: A, + ) -> std::result::Result<(), A::Error> { + while seq.next_element_seed(UniqueKeys)?.is_some() {} + Ok(()) + } + + fn visit_map>( + self, + mut map: A, + ) -> std::result::Result<(), A::Error> { + let mut seen = std::collections::HashSet::new(); + while let Some(key) = map.next_key::()? { + if !seen.insert(key.clone()) { + return Err(serde::de::Error::custom(format!( + "key {key:?} appears twice in one object" + ))); + } + map.next_value_seed(UniqueKeys)?; + } + Ok(()) + } +} + +#[utoipa::path( + get, + path = "/dashboard/modules", + tag = "dashboard", + security(("operator_session" = [])), + responses( + (status = 200, description = "Module instances with their runtime state", body = ModuleCatalogView), + (status = 400, description = "No policy modules are configured", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing dashboard:read permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn list_modules(State(state): State) -> Result> { + admin::catalog_view(&state).await.map(Json) +} + +#[utoipa::path( + get, + path = "/dashboard/accounts/{account_id}/modules", + tag = "dashboard", + security(("operator_session" = [])), + params(("account_id" = String, Path, description = "Account identifier")), + responses( + (status = 200, description = "The account's effective module set, in evaluation order", body = AccountModulesView), + (status = 400, description = "No policy modules are configured", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing dashboard:read permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn account_modules( + State(state): State, + Path(account_id): Path, +) -> Result> { + admin::account_view(&state, &account_id).await.map(Json) +} + +#[derive(Debug, Deserialize, utoipa::IntoParams)] +#[into_params(parameter_in = Query)] +pub struct HistoryQuery { + /// Only entries whose `id` is below this one, to page backwards. + before: Option, + /// At most this many entries (1 to 1,000; default 100). + limit: Option, +} + +#[utoipa::path( + get, + path = "/dashboard/modules/{module_id}/params/history", + tag = "dashboard", + security(("operator_session" = [])), + params(("module_id" = String, Path, description = "Module instance id"), HistoryQuery), + responses( + (status = 200, description = "Params changes, newest first", body = ParamsHistoryView), + (status = 400, description = "Invalid params, reason or assignment, or no policy modules are configured", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing dashboard:read permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn params_history( + State(state): State, + Path(module_id): Path, + axum::extract::Query(query): axum::extract::Query, +) -> Result> { + admin::history(&state, &module_id, query.before, query.limit) + .await + .map(Json) +} + +#[utoipa::path( + put, + path = "/dashboard/modules/{module_id}/params", + tag = "dashboard", + security(("operator_session" = [])), + params(("module_id" = String, Path, description = "Module instance id")), + request_body = ParamsBody, + responses( + (status = 200, description = "Global params stored", body = ModuleInstanceView), + (status = 400, description = "Invalid params, reason or assignment, or no policy modules are configured", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write_global permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), + (status = 409, description = "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn set_global_params( + State(state): State, + Extension(operator): Extension, + Path(module_id): Path, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (ParamsBody, _) = body(request).await?; + admin::set_global( + &state, + &operator, + &module_id, + body.params, + admin::Write { + reason: &body.reason, + expected_version: body.expected_version, + }, + client_ip, + ) + .await + .map(Json) +} + +#[utoipa::path( + post, + path = "/dashboard/modules/{module_id}/enable", + tag = "dashboard", + security(("operator_session" = [])), + params(("module_id" = String, Path, description = "Module instance id")), + request_body = ReasonBody, + responses( + (status = 200, description = "Instance enabled", body = ModuleInstanceView), + (status = 400, description = "Invalid params, reason or assignment, or no policy modules are configured", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), + (status = 503, description = "The module failed its startup checks; nothing changed", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn enable_module( + State(state): State, + Extension(operator): Extension, + Path(module_id): Path, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (ReasonBody, _) = body(request).await?; + admin::enable(&state, &operator, &module_id, &body.reason, client_ip) + .await + .map(Json) +} + +#[utoipa::path( + post, + path = "/dashboard/modules/{module_id}/disable", + tag = "dashboard", + security(("operator_session" = [])), + params(("module_id" = String, Path, description = "Module instance id")), + request_body = ReasonBody, + responses( + (status = 200, description = "Instance disabled", body = ModuleInstanceView), + (status = 400, description = "Invalid params, reason or assignment, or no policy modules are configured", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write or modules:disable permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), + (status = 409, description = "The catalog does not mark the instance operator_can_disable", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn disable_module( + State(state): State, + Extension(operator): Extension, + Path(module_id): Path, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (ReasonBody, _) = body(request).await?; + admin::disable(&state, &operator, &module_id, &body.reason, client_ip) + .await + .map(Json) +} + +#[utoipa::path( + put, + path = "/dashboard/accounts/{account_id}/modules/{module_id}/params", + tag = "dashboard", + security(("operator_session" = [])), + params(("account_id" = String, Path, description = "Account identifier"), ("module_id" = String, Path, description = "Module instance id")), + request_body = ParamsBody, + responses( + (status = 200, description = "Account layer stored", body = AccountModulesView), + (status = 400, description = "Invalid params, reason or assignment, or no policy modules are configured", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), + (status = 409, description = "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn set_account_layer( + State(state): State, + Extension(operator): Extension, + Path((account_id, module_id)): Path<(String, String)>, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (ParamsBody, _) = body(request).await?; + admin::set_layer( + &state, + &operator, + &account_id, + &module_id, + Some(body.params), + admin::Write { + reason: &body.reason, + expected_version: body.expected_version, + }, + client_ip, + ) + .await + .map(Json) +} + +#[utoipa::path( + delete, + path = "/dashboard/accounts/{account_id}/modules/{module_id}/params", + tag = "dashboard", + security(("operator_session" = [])), + params(("account_id" = String, Path, description = "Account identifier"), ("module_id" = String, Path, description = "Module instance id")), + request_body = LayerRemovalBody, + responses( + (status = 200, description = "Account layer removed", body = AccountModulesView), + (status = 400, description = "Invalid params, reason or assignment, or no policy modules are configured", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), + (status = 409, description = "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn remove_account_layer( + State(state): State, + Extension(operator): Extension, + Path((account_id, module_id)): Path<(String, String)>, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (LayerRemovalBody, _) = body(request).await?; + admin::set_layer( + &state, + &operator, + &account_id, + &module_id, + None, + admin::Write { + reason: &body.reason, + expected_version: body.expected_version, + }, + client_ip, + ) + .await + .map(Json) +} + +#[utoipa::path( + put, + path = "/dashboard/accounts/{account_id}/modules", + tag = "dashboard", + security(("operator_session" = [])), + params(("account_id" = String, Path, description = "Account identifier")), + request_body = AssignmentBody, + responses( + (status = 200, description = "Assignment stored", body = AccountModulesView), + (status = 400, description = "Invalid params, reason or assignment, or no policy modules are configured", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), + (status = 409, description = "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn set_assignment( + State(state): State, + Extension(operator): Extension, + Path(account_id): Path, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (AssignmentBody, _) = body(request).await?; + admin::set_assignment( + &state, + &operator, + &account_id, + body.modules, + admin::Write { + reason: &body.reason, + expected_version: body.expected_version, + }, + client_ip, + ) + .await + .map(Json) +} + +#[cfg(test)] +mod tests { + use std::collections::BTreeSet; + use std::sync::Arc; + + use axum::body::{Body, to_bytes}; + use axum::http::{Request, StatusCode, header}; + use guardian_module_sdk::policies::RecipientPolicy; + use guardian_shared::hex::FromHex; + use miden_protocol::Word; + use serde_json::json; + use tower::ServiceExt; + + use crate::dashboard::DashboardState; + use crate::dashboard::permissions::Permission; + use crate::modules::catalog::HookName; + use crate::modules::testing::{instance_with_params, pipeline}; + use crate::testing::helpers::{TestSigner, create_router, create_test_app_state}; + + use super::*; + + fn unique_keys(text: &str) -> std::result::Result<(), serde_json::Error> { + serde::de::DeserializeSeed::deserialize( + UniqueKeys, + &mut serde_json::Deserializer::from_str(text), + ) + } + + #[test] + fn a_body_naming_a_key_twice_is_refused_at_any_depth() { + assert!(unique_keys(r#"{"params":{"cap":"5"},"reason":"r"}"#).is_ok()); + assert!( + unique_keys( + r#"{"params":{"max_per_transaction":{"0xa":"5","0xa":"50"}},"reason":"r"}"# + ) + .unwrap_err() + .to_string() + .contains(r#"key "0xa" appears twice"#) + ); + assert!(unique_keys(r#"{"modules":[{"module_id":"a","module_id":"b"}]}"#).is_err()); + assert!(unique_keys(r#"{"reason":"r","reason":"s"}"#).is_err()); + assert!( + unique_keys(r#"{"params":{"cap":"5","\u0063ap":"50"}}"#).is_err(), + "an escaped spelling of the same key is the same key" + ); + assert!( + unique_keys(r#"{"a":{"k":1},"b":{"k":2}}"#).is_ok(), + "the same key in two objects is fine" + ); + } + + fn operator(signer: &TestSigner, permissions: &[Permission]) -> AuthenticatedOperator { + AuthenticatedOperator { + operator_id: signer.commitment_hex.clone(), + commitment: signer.commitment_hex.clone(), + effective_permissions: Arc::new(permissions.iter().copied().collect::>()), + } + } + + async fn send(app: &axum::Router, request: Request) -> (StatusCode, serde_json::Value) { + let response = app.clone().oneshot(request).await.unwrap(); + let status = response.status(); + let bytes = to_bytes(response.into_body(), usize::MAX).await.unwrap(); + ( + status, + serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null), + ) + } + + async fn login(app: &axum::Router, signer: &TestSigner) -> String { + let (_, challenge) = send( + app, + Request::get(format!( + "/auth/challenge?commitment={}", + signer.commitment_hex + )) + .body(Body::empty()) + .unwrap(), + ) + .await; + let digest = challenge["challenge"]["signing_digest"].as_str().unwrap(); + let signature = signer.sign_word(Word::from_hex(digest).unwrap()); + let response = app + .clone() + .oneshot( + Request::post("/auth/verify") + .header(header::CONTENT_TYPE, "application/json") + .body(Body::from( + json!({ "commitment": signer.commitment_hex, "signature": signature }) + .to_string(), + )) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(response.status(), StatusCode::OK); + response.headers()[header::SET_COOKIE] + .to_str() + .unwrap() + .split(';') + .next() + .unwrap() + .to_string() + } + + fn put(path: &str, cookie: &str, body: serde_json::Value) -> Request { + Request::put(path) + .header(header::COOKIE, cookie) + .header(header::CONTENT_TYPE, "application/json") + .body(Body::from(body.to_string())) + .unwrap() + } + + fn get(path: &str, cookie: &str) -> Request { + Request::get(path) + .header(header::COOKIE, cookie) + .body(Body::empty()) + .unwrap() + } + + #[tokio::test] + async fn global_params_need_their_own_permission_and_are_recorded() { + let support = TestSigner::new(); + let admin = TestSigner::new(); + let mut state = create_test_app_state().await; + state.dashboard = Arc::new(DashboardState::for_tests_with_permissions(vec![ + operator( + &support, + &[Permission::DashboardRead, Permission::PoliciesWrite], + ), + operator( + &admin, + &[Permission::DashboardRead, Permission::PoliciesWriteGlobal], + ), + ])); + state.modules = Some(pipeline(vec![instance_with_params( + "blocklist", + &[HookName::BeforeTransactionApproved], + Arc::new(RecipientPolicy), + json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + )])); + let app = create_router(state); + let support_cookie = login(&app, &support).await; + let admin_cookie = login(&app, &admin).await; + let body = json!({ "params": { "denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }, "reason": "OP-90" }); + + let (status, _) = send( + &app, + put( + "/dashboard/modules/blocklist/params", + &support_cookie, + body.clone(), + ), + ) + .await; + assert_eq!(status, StatusCode::FORBIDDEN); + + let (status, view) = send( + &app, + put("/dashboard/modules/blocklist/params", &admin_cookie, body), + ) + .await; + assert_eq!(status, StatusCode::OK, "{view}"); + assert_eq!( + view["params"]["denylist"][1], + "0x000000000000000000000000000ddd" + ); + + let (status, catalog) = send(&app, get("/dashboard/modules", &support_cookie)).await; + assert_eq!(status, StatusCode::OK); + assert_eq!(catalog["modules"][0]["params_drift"], true); + + let (status, history) = send( + &app, + get( + "/dashboard/modules/blocklist/params/history", + &support_cookie, + ), + ) + .await; + assert_eq!(status, StatusCode::OK); + assert_eq!(history["entries"][0]["reason"], "OP-90"); + assert_eq!(history["entries"][0]["operator"], admin.commitment_hex); + + let (status, _) = send( + &app, + put( + "/dashboard/accounts/0xmissing/modules/blocklist/params", + &support_cookie, + json!({ "params": {}, "reason": "r" }), + ), + ) + .await; + assert_eq!(status, StatusCode::NOT_FOUND); + } + + fn post(path: &str, cookie: &str, body: serde_json::Value) -> Request { + Request::post(path) + .header(header::COOKIE, cookie) + .header(header::CONTENT_TYPE, "application/json") + .body(Body::from(body.to_string())) + .unwrap() + } + + #[tokio::test] + async fn the_disable_permission_can_disable_but_not_enable() { + let on_call = TestSigner::new(); + let mut state = create_test_app_state().await; + state.dashboard = Arc::new(DashboardState::for_tests_with_permissions(vec![operator( + &on_call, + &[Permission::ModulesDisable], + )])); + state.modules = Some(pipeline(vec![instance_with_params( + "risk-scorer", + &[HookName::BeforeTransactionApproved], + Arc::new(RecipientPolicy), + json!({}), + )])); + state + .modules + .as_deref() + .unwrap() + .store() + .seed_instance( + "risk-scorer", + true, + &json!({}), + &json!({}), + "2026-10-15T00:00:00Z", + ) + .await + .unwrap(); + let app = create_router(state); + let cookie = login(&app, &on_call).await; + let reason = json!({ "reason": "scorer returning errors" }); + + let (status, view) = send( + &app, + post( + "/dashboard/modules/risk-scorer/disable", + &cookie, + reason.clone(), + ), + ) + .await; + assert_eq!(status, StatusCode::OK, "{view}"); + assert_eq!(view["enabled"], false); + + let (status, _) = send( + &app, + post("/dashboard/modules/risk-scorer/enable", &cookie, reason), + ) + .await; + assert_eq!(status, StatusCode::FORBIDDEN); + } +} diff --git a/crates/server/src/api/grpc.rs b/crates/server/src/api/grpc.rs index b42db2f63..f21f38ca6 100644 --- a/crates/server/src/api/grpc.rs +++ b/crates/server/src/api/grpc.rs @@ -334,6 +334,63 @@ impl Guardian for GuardianService { } } + async fn check_delta_proposal( + &self, + request: Request, + ) -> Result, Status> { + let credentials = authenticated_operation(&request, SignedOperation::CheckDeltaProposal)?; + let data = request.into_inner(); + let params = services::PushDeltaProposalParams { + account_id: data.account_id, + nonce: data.nonce, + delta_payload: serde_json::from_str(&data.delta_payload) + .map_err(|e| Status::invalid_argument(format!("Invalid delta payload: {e}")))?, + credentials, + }; + match services::check_proposal(&self.app_state, params).await { + Ok(result) => Ok(Response::new(CheckDeltaProposalResponse { + success: true, + message: "Proposal creation would pass".to_string(), + allowed: true, + complete: result.complete, + error_code: String::new(), + })), + Err(e) => Err(Status::from(e)), + } + } + + async fn get_policies( + &self, + request: Request, + ) -> Result, Status> { + let credentials = authenticated_request(&request)?; + let data = request.into_inner(); + let params = services::GetPoliciesParams { + account_id: data.account_id, + credentials, + }; + match services::get_policies(&self.app_state, params).await { + Ok(result) => Ok(Response::new(GetPoliciesResponse { + success: true, + message: "Policies retrieved successfully".to_string(), + account_id: result.account_id, + policies: result + .policies + .into_iter() + .map(|policy| PolicyEntry { + module_id: policy.module_id, + hooks: policy.hooks, + description: policy.description, + params: policy.params.map(|params| params.to_string()), + account_layer: policy.account_layer.map(|layer| layer.to_string()), + }) + .collect(), + error_code: String::new(), + })), + Err(e) => Err(Status::from(e)), + } + } + async fn get_delta_proposals( &self, request: Request, diff --git a/crates/server/src/api/http.rs b/crates/server/src/api/http.rs index 6eee85413..5c28eb801 100644 --- a/crates/server/src/api/http.rs +++ b/crates/server/src/api/http.rs @@ -245,7 +245,7 @@ pub async fn push_delta( }; let response = services::push_delta(&state, params).await?; - Ok(Json(response.delta)) + Ok(Json(response.delta.without_module_trace())) } /// Fetch the delta for an account at a specific nonce. @@ -276,7 +276,7 @@ pub async fn get_delta( }; let response = services::get_delta(&state, params).await?; - Ok(Json(response.delta)) + Ok(Json(response.delta.without_module_trace())) } /// Fetch the merged delta accumulating all changes for an account @@ -308,7 +308,7 @@ pub async fn get_delta_since( }; let response = services::get_delta_since(&state, params).await?; - Ok(Json(response.merged_delta)) + Ok(Json(response.merged_delta.without_module_trace())) } /// Paginated canonical delta history for an account (issue @@ -696,6 +696,20 @@ pub struct DeltaProposalResponse { pub commitment: String, } +#[derive(Deserialize, Serialize, utoipa::ToSchema)] +pub struct CheckProposalResponse { + /// Always true: a refusal is returned as an error. + pub allowed: bool, + /// False when a module that opts out of dry runs was skipped. + pub complete: bool, +} + +#[derive(Deserialize, Serialize, utoipa::ToSchema)] +pub struct PoliciesResponse { + pub account_id: String, + pub policies: Vec, +} + #[derive(Deserialize, Serialize, utoipa::ToSchema, utoipa::IntoParams)] #[into_params(parameter_in = Query)] pub struct PubkeyQuery { @@ -811,11 +825,93 @@ pub async fn push_delta_proposal( let response = services::push_delta_proposal(&state, params).await?; Ok(Json(DeltaProposalResponse { - delta: response.delta, + delta: response.delta.without_module_trace(), commitment: response.commitment, })) } +/// Dry run of `POST /delta/proposal`: the same checks and proposal-creation +/// policy modules, without storing a proposal or taking a slot. A refusal is +/// the same error proposal creation returns; `complete` is false when a module +/// that opts out of dry runs was skipped. Advisory: approval still decides. +/// Rate limited per account and signer (`GUARDIAN_MODULE_CHECK_RATE_PER_MIN`). +#[utoipa::path( + post, + path = "/delta/proposal/check", + tag = "client", + security(("x-pubkey" = [], "x-signature" = [], "x-timestamp" = [])), + params(("x-auth-format" = Option, Header, description = "Optional ECDSA request format: eip712; omitted for raw signatures")), + request_body = DeltaProposalRequest, + responses( + (status = 200, description = "Proposal creation would pass", body = CheckProposalResponse), + (status = 400, description = "Invalid proposal payload", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "Authentication failed or replay rejected", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "A policy module refused (GUARDIAN_MODULE_DENIED)", body = crate::openapi::ApiErrorResponse), + (status = 409, description = "Conflicting / too many pending proposals", body = crate::openapi::ApiErrorResponse), + (status = 429, description = "Too many checks for this account and signer", body = crate::openapi::ApiErrorResponse), + (status = 503, description = "A policy module is unavailable (GUARDIAN_MODULE_UNAVAILABLE)", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn check_delta_proposal( + State(state): State, + AuthHeader(credentials): AuthHeader, + Json(payload): Json, +) -> Result, GuardianError> { + let request_payload = request_payload_for_operation( + &payload, + guardian_shared::auth_request_payload::SignedOperation::CheckDeltaProposal, + ) + .map_err(GuardianError::InvalidInput)?; + let params = PushDeltaProposalParams { + account_id: payload.account_id, + nonce: payload.nonce, + delta_payload: payload.delta_payload, + credentials: request_payload.apply_to(credentials), + }; + let result = services::check_proposal(&state, params).await?; + Ok(Json(CheckProposalResponse { + allowed: true, + complete: result.complete, + })) +} + +/// The policy modules that apply to the account, as far as each module's +/// catalog entry discloses them (RFC 0002 section 2.7), in evaluation order. +/// Empty when the Guardian has no modules or discloses none. +#[utoipa::path( + get, + path = "/policies", + tag = "client", + security(("x-pubkey" = [], "x-signature" = [], "x-timestamp" = [])), + params(StateQuery, ("x-auth-format" = Option, Header, description = "Optional ECDSA request format: eip712; omitted for raw signatures")), + responses( + (status = 200, description = "Disclosed policies", body = PoliciesResponse), + (status = 400, description = "The account is not a Miden account (unsupported_for_network)", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "Authentication failed or replay rejected", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account not found", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn get_policies( + State(state): State, + AuthHeader(credentials): AuthHeader, + Query(query): Query, +) -> Result, GuardianError> { + let request_payload = + request_payload_from_serializable(&query).map_err(GuardianError::InvalidInput)?; + let result = services::get_policies( + &state, + services::GetPoliciesParams { + account_id: query.account_id, + credentials: request_payload.apply_to(credentials), + }, + ) + .await?; + Ok(Json(PoliciesResponse { + account_id: result.account_id, + policies: result.policies, + })) +} + /// Request abandonment of a pending canonicalization candidate whose /// transaction will never land on-chain (issue #319). /// @@ -1041,7 +1137,11 @@ pub async fn get_delta_proposals( let response = services::get_delta_proposals(&state, params).await?; Ok(Json(ProposalsResponse { - proposals: response.proposals, + proposals: response + .proposals + .into_iter() + .map(DeltaObject::without_module_trace) + .collect(), })) } @@ -1073,7 +1173,7 @@ pub async fn get_delta_proposal( }; let response = services::get_delta_proposal(&state, params).await?; - Ok(Json(response.proposal)) + Ok(Json(response.proposal.without_module_trace())) } /// Add a cosigner signature to an existing multisig proposal. The approval @@ -1112,7 +1212,7 @@ pub async fn sign_delta_proposal( }; let response = services::sign_delta_proposal(&state, params).await?; - Ok(Json(response.delta)) + Ok(Json(response.delta.without_module_trace())) } struct RequestPayloadParts { diff --git a/crates/server/src/api/mod.rs b/crates/server/src/api/mod.rs index 5f94faddb..ca622a084 100644 --- a/crates/server/src/api/mod.rs +++ b/crates/server/src/api/mod.rs @@ -1,5 +1,6 @@ pub mod dashboard; pub mod dashboard_feeds; +pub mod dashboard_modules; #[cfg(feature = "evm")] pub mod evm; #[cfg(test)] diff --git a/crates/server/src/audit/kinds.rs b/crates/server/src/audit/kinds.rs index 17d9ac48a..ce961f0b8 100644 --- a/crates/server/src/audit/kinds.rs +++ b/crates/server/src/audit/kinds.rs @@ -52,6 +52,30 @@ pub const ACCOUNTS_RELEASE: &str = "accounts.release"; /// request outcome (`queued` / `in_progress` / `cooldown`). pub const STATS_REFRESH: &str = "stats.refresh"; +/// An operator changed a policy module's global params. +pub const MODULES_PARAMS_GLOBAL: &str = "modules.params.global"; + +/// An operator set or removed an account's layer on a mandatory policy module. +pub const MODULES_PARAMS_ACCOUNT: &str = "modules.params.account"; + +/// An operator replaced an account's assigned policy modules. +pub const MODULES_ASSIGNMENT: &str = "modules.assignment"; + +/// An operator enabled a policy module instance. +pub const MODULES_ENABLE: &str = "modules.enable"; + +/// An operator disabled a policy module instance. +pub const MODULES_DISABLE: &str = "modules.disable"; + +/// A policy module evaluation at proposal creation or account registration let through a +/// module failure because the instance is `on_error = "allow"`. System-initiated +/// (`operator_identity` is `system`). `payload` carries `hook`, `submitter`, `catalog_hash`, +/// `params_version`, `account_params_version` and `failed_open` (`module_id`, `layer`, +/// `failure`), plus the +/// `proposal_id` at proposal creation. A transaction's skips are stored with its signed delta +/// instead (`modules.failed_open` on the dashboard delta detail). +pub const MODULES_FAILED_OPEN: &str = "modules.failed_open"; + /// All registered kinds in v1, for tests and introspection. Append /// new consts above and add them to this slice in the same commit. pub const ALL_KINDS: &[&str] = &[ @@ -61,6 +85,12 @@ pub const ALL_KINDS: &[&str] = &[ ACCOUNTS_UNPAUSE, ACCOUNTS_RELEASE, STATS_REFRESH, + MODULES_PARAMS_GLOBAL, + MODULES_PARAMS_ACCOUNT, + MODULES_ASSIGNMENT, + MODULES_ENABLE, + MODULES_DISABLE, + MODULES_FAILED_OPEN, ]; #[cfg(test)] @@ -78,6 +108,12 @@ mod tests { ACCOUNTS_UNPAUSE, ACCOUNTS_RELEASE, STATS_REFRESH, + MODULES_PARAMS_GLOBAL, + MODULES_PARAMS_ACCOUNT, + MODULES_ASSIGNMENT, + MODULES_ENABLE, + MODULES_DISABLE, + MODULES_FAILED_OPEN, ] ); } diff --git a/crates/server/src/builder/env.rs b/crates/server/src/builder/env.rs new file mode 100644 index 000000000..04d0ac371 --- /dev/null +++ b/crates/server/src/builder/env.rs @@ -0,0 +1,121 @@ +//! The server configured from the environment, as the official binary runs it. + +use std::path::PathBuf; + +use crate::ack::AckRegistry; +use crate::block_watch::BlockWatchConfig; +use crate::builder::storage::StorageMetadataBuilder; +use crate::builder::{BuildError, ServerBuilder}; +use crate::canonicalization::CanonicalizationConfig; +use crate::config::execution::ExecutionConfig; +use crate::config::stage::Stage; +use crate::logging::LoggingConfig; +use crate::middleware::{BodyLimitConfig, CorsConfig, RateLimitConfig}; +use crate::network::{NetworkType, RpcSettings}; +use crate::release_sweep::ReleaseSweepConfig; + +/// HTTP port of a server configured with [`ServerBuilder::from_env`]. +pub const DEFAULT_HTTP_PORT: u16 = 3000; +/// gRPC port of a server configured with [`ServerBuilder::from_env`]. +pub const DEFAULT_GRPC_PORT: u16 = 50051; + +fn invalid(what: &str) -> impl FnOnce(String) -> BuildError + '_ { + move |error| BuildError::from(format!("Invalid {what}: {error}")) +} + +impl ServerBuilder { + /// The server the official `server` binary runs, configured from the `GUARDIAN_*` + /// environment variables documented in `docs/CONFIGURATION.md`: storage and metadata, the + /// acknowledgement keys, network and RPC, canonicalization, Guardian execution, the release + /// sweep and block watch, rate and body limits, CORS, logging, HTTP on port 3000 and gRPC + /// on port 50051. Policy modules are read from `GUARDIAN_MODULES_CONFIG` when the server is + /// built. + /// + /// A custom build starts here, so it configures exactly as the official binary does, and + /// adds its own module kinds; any builder method called afterwards overrides what the + /// environment set. Loading a `.env` file is left to the binary. + /// + /// ```no_run + /// use std::sync::Arc; + /// use server::builder::{BuildError, ServerBuilder}; + /// # fn factory() -> Arc { unimplemented!() } + /// + /// # async fn example() -> Result<(), BuildError> { + /// ServerBuilder::from_env() + /// .await? + /// .with_module_kind("acme-sanctions", factory()) + /// .build() + /// .await? + /// .run() + /// .await; + /// # Ok(()) + /// # } + /// ``` + /// + /// # Errors + /// Returns the first setting that is invalid, or a storage backend or acknowledgement key + /// store that cannot be opened. + pub async fn from_env() -> Result { + let keystore_path: PathBuf = std::env::var("GUARDIAN_KEYSTORE_PATH") + .unwrap_or_else(|_| "/var/guardian/keystore".to_string()) + .into(); + + let (storage, metadata, auditor, coordination) = StorageMetadataBuilder::from_env() + .build() + .await + .map_err(|error| format!("Failed to initialize storage backends: {error}"))?; + + let ack = AckRegistry::new(keystore_path) + .await + .map_err(|error| format!("Failed to initialize ack registry: {error}"))?; + + let cors = CorsConfig::from_env() + .map_err(|error| format!("Failed to initialize CORS config: {error}"))?; + let network = NetworkType::from_env("GUARDIAN_NETWORK_TYPE") + .map_err(|error| format!("Failed to resolve network type: {error}"))?; + let stage = Stage::from_env() + .map_err(|error| error.to_string()) + .map_err(invalid("GUARDIAN_ENV"))?; + let rpc = RpcSettings::from_env(network).map_err(invalid("RPC configuration"))?; + let canonicalization = CanonicalizationConfig::new(10, 48) + .with_stage_defaults(stage) + .with_submission_grace_period_seconds(600) + .with_fast_promotion_enabled_from_env() + .map_err(invalid("fast promotion configuration"))? + .with_max_concurrent_accounts_from_env() + .map_err(invalid("canonicalization concurrency configuration"))? + .with_retained_ttl_seconds_from_env() + .map_err(invalid("retained TTL configuration"))? + .with_reconcile_interval_seconds_from_env() + .map_err(invalid("reconcile interval configuration"))? + .with_max_pending_candidates_per_account_from_env() + .map_err(invalid("pending-candidate queue depth configuration"))? + .with_rebuild_admission_from_env() + .map_err(invalid("canonicalization rebuild admission configuration"))?; + let execution = + ExecutionConfig::from_env().map_err(invalid("Guardian execution configuration"))?; + let release_sweep = + ReleaseSweepConfig::from_env().map_err(invalid("release sweep configuration"))?; + let block_watch = BlockWatchConfig::from_env_following(release_sweep.enabled) + .map_err(invalid("block watch configuration"))?; + + Ok(Self::new() + .with_logging(LoggingConfig::default()) + .network(network) + .with_rpc(rpc) + .with_canonicalization(Some(canonicalization)) + .with_execution(execution) + .with_release_sweep(Some(release_sweep)) + .with_block_watch(Some(block_watch)) + .with_rate_limit(RateLimitConfig::from_env()) + .with_body_limit(BodyLimitConfig::from_env()) + .storage(storage) + .metadata(metadata) + .auditor(auditor) + .coordination(coordination) + .ack(ack) + .http(true, DEFAULT_HTTP_PORT) + .grpc(true, DEFAULT_GRPC_PORT) + .cors(cors.layer())) + } +} diff --git a/crates/server/src/builder/handle.rs b/crates/server/src/builder/handle.rs index a486739e6..aab4a73ed 100644 --- a/crates/server/src/builder/handle.rs +++ b/crates/server/src/builder/handle.rs @@ -25,11 +25,11 @@ use crate::api::grpc::GuardianService; use crate::api::grpc::guardian::FILE_DESCRIPTOR_SET; use crate::api::grpc::guardian::guardian_server::GuardianServer; use crate::api::http::{ - abandon_candidate, configure, create_session, execute_delta_proposal, get_canonical_nonce, - get_current_execution, get_delta, get_delta_history, get_delta_proposal, - get_delta_proposal_execution, get_delta_proposals, get_delta_since, get_pubkey, get_state, - get_state_tail, lookup, push_delta, push_delta_proposal, revoke_all_sessions, revoke_session, - sign_delta_proposal, status, status_root, + abandon_candidate, check_delta_proposal, configure, create_session, execute_delta_proposal, + get_canonical_nonce, get_current_execution, get_delta, get_delta_history, get_delta_proposal, + get_delta_proposal_execution, get_delta_proposals, get_delta_since, get_policies, get_pubkey, + get_state, get_state_tail, lookup, push_delta, push_delta_proposal, revoke_all_sessions, + revoke_session, sign_delta_proposal, status, status_root, }; use crate::builder::startup::StartupInfo; use crate::config::execution::RecordRetention; @@ -126,6 +126,10 @@ impl ServerHandle { } } + if let Some(modules) = self.app_state.modules.clone() { + tasks.push(modules.spawn_probe()); + } + // Start background jobs based on canonicalization config if let Some(config) = &self.app_state.canonicalization { let admission = crate::network::reconstructor() @@ -462,6 +466,70 @@ pub(crate) fn build_http_router(state: AppState, config: HttpRouterConfig) -> Ro dashboard_routes.merge(pause_router) }; + // Policy modules: reads under `dashboard:read`, per-account writes under `policies:write`, + // global params under their own `policies:write_global`. + let dashboard_routes = { + use crate::api::dashboard_modules as modules; + use axum::routing::{delete, put}; + let read_authz = AuthzState::new(state.clone(), &[Permission::DashboardRead]); + let write_authz = AuthzState::new(state.clone(), &[Permission::PoliciesWrite]); + let global_authz = AuthzState::new(state.clone(), &[Permission::PoliciesWriteGlobal]); + let read = Router::new() + .route("/modules", get(modules::list_modules)) + .route( + "/modules/{module_id}/params/history", + get(modules::params_history), + ) + .route( + "/accounts/{account_id}/modules", + get(modules::account_modules), + ) + .route_layer(from_fn_with_state(read_authz, enforce_authz)) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + let write = Router::new() + .route( + "/accounts/{account_id}/modules", + put(modules::set_assignment), + ) + .route( + "/accounts/{account_id}/modules/{module_id}/params", + put(modules::set_account_layer).merge(delete(modules::remove_account_layer)), + ) + .route_layer(from_fn_with_state(write_authz, enforce_authz)) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + let disable_authz = AuthzState::any_of( + state.clone(), + &[Permission::PoliciesWrite, Permission::ModulesDisable], + ); + let enable = Router::new() + .route("/modules/{module_id}/enable", post(modules::enable_module)) + .route_layer(from_fn_with_state( + AuthzState::new(state.clone(), &[Permission::PoliciesWrite]), + enforce_authz, + )) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + let disable = Router::new() + .route( + "/modules/{module_id}/disable", + post(modules::disable_module), + ) + .route_layer(from_fn_with_state(disable_authz, enforce_authz)) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + let global = Router::new() + .route( + "/modules/{module_id}/params", + put(modules::set_global_params), + ) + .route_layer(from_fn_with_state(global_authz, enforce_authz)) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + dashboard_routes + .merge(read) + .merge(write) + .merge(global) + .merge(enable) + .merge(disable) + }; + // Issue #371: operator-triggered refresh of the /dashboard/stats // aggregate, gated by its own `stats:refresh` permission. let dashboard_routes = { @@ -504,6 +572,8 @@ pub(crate) fn build_http_router(state: AppState, config: HttpRouterConfig) -> Ro .route("/delta/proposal", post(push_delta_proposal)) .route("/delta/proposal", get(get_delta_proposals)) .route("/delta/proposal/single", get(get_delta_proposal)) + .route("/delta/proposal/check", post(check_delta_proposal)) + .route("/policies", get(get_policies)) .route("/delta/proposal", put(sign_delta_proposal)) .route("/delta/candidate/abandon", post(abandon_candidate)) .route("/delta/proposal/execution", post(execute_delta_proposal)) diff --git a/crates/server/src/builder/mod.rs b/crates/server/src/builder/mod.rs index 4891c869e..271757572 100644 --- a/crates/server/src/builder/mod.rs +++ b/crates/server/src/builder/mod.rs @@ -9,6 +9,7 @@ pub mod block_watch; pub mod canonicalization; pub mod clock; +pub mod env; pub mod handle; pub mod logging; pub mod release_sweep; @@ -35,6 +36,18 @@ use crate::storage::StorageBackend; use guardian_shared::SignatureScheme; use std::sync::Arc; +/// Why a server could not be configured from the environment or built: a missing component, +/// an invalid setting, or a backend that could not be opened. The message names which. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +#[error("{0}")] +pub struct BuildError(String); + +impl From for BuildError { + fn from(message: String) -> Self { + Self(message) + } +} + /// Builder for configuring and creating a server instance pub struct ServerBuilder { network_type: Option, @@ -54,6 +67,7 @@ pub struct ServerBuilder { rate_limit_config: Option, body_limit_config: Option, metrics_config: Option, + module_kinds: Vec<(String, Arc)>, http_enabled: bool, http_port: u16, grpc_enabled: bool, @@ -81,6 +95,7 @@ impl ServerBuilder { rate_limit_config: None, body_limit_config: None, metrics_config: None, + module_kinds: Vec::new(), http_enabled: true, http_port: 3000, grpc_enabled: true, @@ -440,6 +455,26 @@ impl ServerBuilder { self } + /// Registers a policy module kind that runs in this process, so catalog entries + /// (`GUARDIAN_MODULES_CONFIG`) can name it in `kind`. The module shares the process that + /// holds the acknowledgement keys, so register only code you have reviewed. `build` fails + /// if the name is already taken, including by the first-party policies (`spending-limit`, + /// `recipient-policy`, `signer-policy`, `code-policy`) and `grpc`. + /// + /// # Example + /// ```ignore + /// let builder = ServerBuilder::new() + /// .with_module_kind("note-policy", Arc::new(NotePolicyFactory)); + /// ``` + pub fn with_module_kind( + mut self, + kind: impl Into, + factory: Arc, + ) -> Self { + self.module_kinds.push((kind.into(), factory)); + self + } + /// Build the server handle /// /// Validates that all required components are configured and returns @@ -458,7 +493,7 @@ impl ServerBuilder { /// use std::sync::Arc; /// use std::path::PathBuf; /// - /// # async fn example() -> Result<(), String> { + /// # async fn example() -> Result<(), server::builder::BuildError> { /// let storage = FilesystemService::new(PathBuf::from("/var/guardian/storage")).await?; /// let metadata = FilesystemMetadataStore::new(PathBuf::from("/var/guardian/metadata")).await?; /// @@ -473,7 +508,11 @@ impl ServerBuilder { /// # Ok(()) /// # } /// ``` - pub async fn build(self) -> Result { + pub async fn build(self) -> Result { + self.assemble().await.map_err(BuildError) + } + + async fn assemble(self) -> Result { if let Some(ref config) = self.logging_config { config.init(); } @@ -506,6 +545,9 @@ impl ServerBuilder { let ack = self.ack.ok_or("AckRegistry not set. Use .ack(...)")?; let coordination = self.coordination; + let module_store = coordination + .as_ref() + .and_then(|handles| handles.module_store.clone()); // Fail closed before anything else: the Postgres backend must never fall // back to per-process coordination (AlwaysLeader + in-memory sessions), // which would let every replica run canonicalization and split auth @@ -768,6 +810,20 @@ impl ServerBuilder { ); } + crate::modules::check_limit::init_from_env()?; + let mut module_registry = crate::modules::Registry::first_party(); + for (kind, factory) in self.module_kinds { + module_registry.register(kind, factory)?; + } + let modules = crate::modules::from_env( + chrono::Utc::now().to_rfc3339(), + module_store, + &module_registry, + self.execution.lease, + network_type, + ) + .await?; + let app_state = AppState { storage, metadata, @@ -781,6 +837,7 @@ impl ServerBuilder { auditor, execution, miden_sessions, + modules, #[cfg(feature = "evm")] evm, }; diff --git a/crates/server/src/builder/state.rs b/crates/server/src/builder/state.rs index 15f14fdb2..2b1c3e0fb 100644 --- a/crates/server/src/builder/state.rs +++ b/crates/server/src/builder/state.rs @@ -39,6 +39,8 @@ pub struct AppState { pub execution: crate::services::execute_proposal::ExecutionState, /// Miden account sessions. pub miden_sessions: Arc, + /// Policy modules consulted before approval; `None` when no catalog is configured. + pub modules: Option>, #[cfg(feature = "evm")] pub evm: Arc, } diff --git a/crates/server/src/coordination/mod.rs b/crates/server/src/coordination/mod.rs index 236a7dff7..5c5800290 100644 --- a/crates/server/src/coordination/mod.rs +++ b/crates/server/src/coordination/mod.rs @@ -81,6 +81,8 @@ pub struct CoordinationHandles { pub block_watch_store: Arc, /// Miden account sessions. pub miden_sessions: Arc, + /// Policy module tables on the shared database; `None` keeps them as files. + pub module_store: Option>, /// Record of accepted session reads (`unique` read replay policy). pub read_records: Arc, #[cfg(feature = "evm")] @@ -116,6 +118,7 @@ impl CoordinationHandles { stats_store: Arc::new(InMemoryStatsStore::new()), block_watch_store: Arc::new(InMemoryBlockWatchStore::new()), miden_sessions: Arc::new(InMemorySessionStore::new()), + module_store: None, read_records: Arc::new(InMemoryReadRecords::new()), #[cfg(feature = "evm")] evm_sessions: Arc::new(InMemorySessionStore::new()), @@ -162,6 +165,9 @@ impl CoordinationHandles { read_records: Arc::new(PgReadRecords::new(pool.clone())), block_watch_store: Arc::new(PgBlockWatchStore::new(pool.clone())), miden_sessions: Arc::new(PgSessionStore::new(pool.clone(), Realm::Miden)), + module_store: Some(Arc::new( + crate::modules::postgres_store::PgModuleStore::new(pool.clone()), + )), #[cfg(feature = "evm")] evm_sessions: Arc::new(PgSessionStore::new(pool.clone(), Realm::Evm)), #[cfg(feature = "evm")] diff --git a/crates/server/src/dashboard/authz.rs b/crates/server/src/dashboard/authz.rs index 158784921..596075b1c 100644 --- a/crates/server/src/dashboard/authz.rs +++ b/crates/server/src/dashboard/authz.rs @@ -36,6 +36,8 @@ pub type RequiredPermissions = &'static [Permission]; pub struct AuthzState { pub app_state: AppState, pub required: RequiredPermissions, + /// When true, holding any one of `required` is enough. + pub any_of: bool, } impl AuthzState { @@ -43,6 +45,16 @@ impl AuthzState { Self { app_state, required, + any_of: false, + } + } + + /// The route accepts an operator holding at least one of `required`. + pub fn any_of(app_state: AppState, required: RequiredPermissions) -> Self { + Self { + app_state, + required, + any_of: true, } } } @@ -64,6 +76,7 @@ pub async fn enforce( let AuthzState { app_state: state, required, + any_of, } = state; // The session middleware (`require_dashboard_session`) runs first, // so `AuthenticatedOperator` MUST be present. If it's missing we @@ -81,7 +94,12 @@ pub async fn enforce( })?; let missing = missing_permissions(&operator.effective_permissions, required); - if missing.is_empty() { + let satisfied = if any_of { + missing.len() < required.len() + } else { + missing.is_empty() + }; + if satisfied { return Ok(next.run(request).await); } @@ -143,6 +161,16 @@ mod tests { Arc::new(perms.iter().copied().collect()) } + #[test] + fn any_of_is_satisfied_by_one_held_permission() { + let required: RequiredPermissions = + &[Permission::PoliciesWrite, Permission::ModulesDisable]; + let missing = missing_permissions(&held(&[Permission::ModulesDisable]), required); + assert!(missing.len() < required.len()); + let missing = missing_permissions(&held(&[Permission::DashboardRead]), required); + assert_eq!(missing.len(), required.len()); + } + #[test] fn missing_permissions_returns_empty_when_all_held() { let result = missing_permissions( diff --git a/crates/server/src/dashboard/permissions.rs b/crates/server/src/dashboard/permissions.rs index 1b6c884c3..a7b60973c 100644 --- a/crates/server/src/dashboard/permissions.rs +++ b/crates/server/src/dashboard/permissions.rs @@ -25,6 +25,8 @@ pub enum Permission { DashboardRead, AccountsPause, PoliciesWrite, + PoliciesWriteGlobal, + ModulesDisable, StatsRefresh, } @@ -39,6 +41,14 @@ pub const ACCOUNTS_PAUSE: &str = "accounts:pause"; /// Wire string for [`Permission::PoliciesWrite`]. pub const POLICIES_WRITE: &str = "policies:write"; +/// Wire string for [`Permission::PoliciesWriteGlobal`]: may change the global params of a policy +/// module, which apply to every account. +pub const POLICIES_WRITE_GLOBAL: &str = "policies:write_global"; + +/// Wire string for [`Permission::ModulesDisable`]: may disable a policy module instance the +/// catalog marks `operator_can_disable`, and nothing else. +pub const MODULES_DISABLE: &str = "modules:disable"; + /// Wire string for [`Permission::StatsRefresh`]: may request an /// out-of-cycle refresh of the `/dashboard/stats` aggregate /// (`POST /dashboard/stats/refresh`). @@ -66,6 +76,8 @@ impl Permission { Self::DashboardRead => DASHBOARD_READ, Self::AccountsPause => ACCOUNTS_PAUSE, Self::PoliciesWrite => POLICIES_WRITE, + Self::PoliciesWriteGlobal => POLICIES_WRITE_GLOBAL, + Self::ModulesDisable => MODULES_DISABLE, Self::StatsRefresh => STATS_REFRESH, } } @@ -88,6 +100,8 @@ impl std::str::FromStr for Permission { DASHBOARD_READ => Ok(Self::DashboardRead), ACCOUNTS_PAUSE => Ok(Self::AccountsPause), POLICIES_WRITE => Ok(Self::PoliciesWrite), + POLICIES_WRITE_GLOBAL => Ok(Self::PoliciesWriteGlobal), + MODULES_DISABLE => Ok(Self::ModulesDisable), STATS_REFRESH => Ok(Self::StatsRefresh), other => Err(UnknownPermission(other.to_owned())), } diff --git a/crates/server/src/dashboard/stats.rs b/crates/server/src/dashboard/stats.rs index 24b0e4f26..14ae47dab 100644 --- a/crates/server/src/dashboard/stats.rs +++ b/crates/server/src/dashboard/stats.rs @@ -1396,6 +1396,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -2866,6 +2867,7 @@ mod postgres_tests { std::fs::create_dir_all(&keystore_dir).expect("keystore dir"); let ack = AckRegistry::new(keystore_dir).await.expect("ack"); AppState { + modules: None, execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), storage: Arc::new(MockStorageBackend::new()), diff --git a/crates/server/src/delta_object.rs b/crates/server/src/delta_object.rs index faac90a31..b8fc3fdf6 100644 --- a/crates/server/src/delta_object.rs +++ b/crates/server/src/delta_object.rs @@ -412,6 +412,16 @@ pub struct DeltaObject { } impl DeltaObject { + /// The delta as a client may see it: the policy module evaluation trace + /// (`metadata.modules`) is for operators only, since it names instances an + /// account's cosigners may not be told about. + pub fn without_module_trace(mut self) -> Self { + if let Some(metadata) = self.metadata.as_mut() { + metadata.modules = None; + } + self + } + /// Return the multisig proposal type tag carried by this delta. /// /// Reads from the typed `metadata.proposal` block when present. @@ -666,6 +676,7 @@ mod tests { proposal_type: "p2id".to_string(), ..ProposalMetadata::default() }), + modules: None, }), ..Default::default() }; @@ -710,6 +721,7 @@ mod tests { proposal_type: "p2id".to_string(), ..ProposalMetadata::default() }), + modules: None, }), delta_payload: serde_json::json!({ "metadata": { "proposal_type": "add_signer" } @@ -874,6 +886,36 @@ mod tests { assert_eq!(delta.status.timestamp(), ""); } + #[test] + fn clients_get_deltas_without_the_module_trace() { + let delta: DeltaObject = serde_json::from_value(serde_json::json!({ + "account_id": "0x123", + "nonce": 1, + "prev_commitment": "0xabc", + "new_commitment": "0xdef", + "delta_payload": {}, + "ack_sig": null, + "metadata": { + "category": "asset_transfer", + "proposal": { "proposal_type": "p2id" }, + "modules": { + "catalog_hash": "0xc1", + "params_version": 3, + "account_params_version": 1, + "failed_open": [{ "module_id": "screening", "layer": "global", "failure": "timeout" }], + "signed_at": "2026-11-09T00:00:00Z", + "submitter": "0xs1", + "proposer": "" + } + } + })) + .unwrap(); + assert!(delta.metadata.as_ref().unwrap().modules.is_some()); + let shown = serde_json::to_value(delta.without_module_trace()).unwrap(); + assert!(shown["metadata"].get("modules").is_none(), "{shown}"); + assert_eq!(shown["metadata"]["proposal"]["proposal_type"], "p2id"); + } + #[test] fn test_cosigner_signature() { let sig = CosignerSignature { diff --git a/crates/server/src/delta_summary/build.rs b/crates/server/src/delta_summary/build.rs index 4741f8be7..362ae25bc 100644 --- a/crates/server/src/delta_summary/build.rs +++ b/crates/server/src/delta_summary/build.rs @@ -47,6 +47,7 @@ pub fn build_metadata( counterparty: counterparty_from_proposal(&proposal), note_counts: Default::default(), proposal: Some(proposal), + modules: None, }) } } @@ -96,6 +97,7 @@ fn assemble(summary: &TransactionSummary, proposal: Option) -> counterparty, note_counts, proposal, + modules: None, } } @@ -409,6 +411,7 @@ mod tests { amount: Some("100".to_string()), ..ProposalMetadata::default() }), + modules: None, }; let value = metadata_to_value(&original); let round_tripped = metadata_from_value(value).expect("metadata parses"); diff --git a/crates/server/src/delta_summary/decode.rs b/crates/server/src/delta_summary/decode.rs index fdd39511c..37517d7ee 100644 --- a/crates/server/src/delta_summary/decode.rs +++ b/crates/server/src/delta_summary/decode.rs @@ -10,10 +10,15 @@ use super::ProposalMetadata; /// Decode a [`TransactionSummary`] from a persisted `delta_payload`. /// /// Handles both shapes: the multisig wrapper `{ tx_summary: {data}, -/// metadata, signatures? }` and the raw `{ data: base64 }`. Returns a -/// short stable token string on failure. +/// metadata, signatures? }` and the raw `{ data: base64 }`. A top-level +/// `data` wins, as it does where the delta is verified and acked, so an +/// extra `tx_summary` key cannot change what is shown. Returns a short +/// stable token string on failure. pub fn decode_transaction_summary(payload: &Value) -> Result { - let candidate = payload.get("tx_summary").unwrap_or(payload); + let candidate = match payload.get("data") { + Some(_) => payload, + None => payload.get("tx_summary").unwrap_or(payload), + }; TransactionSummary::from_json(candidate).map_err(classify_decode_error) } diff --git a/crates/server/src/delta_summary/mod.rs b/crates/server/src/delta_summary/mod.rs index eca9784e3..b4e4eddc3 100644 --- a/crates/server/src/delta_summary/mod.rs +++ b/crates/server/src/delta_summary/mod.rs @@ -55,6 +55,43 @@ pub struct DeltaMetadata { /// `push_delta`, EVM deltas, and pushes where no proposal matched. #[serde(default, skip_serializing_if = "Option::is_none")] pub proposal: Option, + + /// The policy module configuration that approved this delta, for operators: absent when no + /// module ran, never included in client API responses, and served to operators on the + /// dashboard delta detail. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub modules: Option, +} + +/// The policy modules' approval of a signed delta: the configuration they ran with, when and for +/// whom. Allowed evaluations are not listed: the catalog, the two params versions and the account determine +/// which modules ran, so only failures let through by `on_error = allow` are kept. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct ModuleApproval { + /// SHA-256 of the catalog file the approving replica loaded. + pub catalog_hash: String, + /// The instance params version: every instance's global params and enabled flag. + pub params_version: u64, + /// The account's params version: its layers and assignment. + pub account_params_version: u64, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub failed_open: Vec, + /// RFC 3339 time the Guardian signed, the accounting time the modules evaluated with. + pub signed_at: String, + /// The cosigner the acknowledgment was evaluated for. + pub submitter: String, + /// The matching proposal's creator; empty when no stored proposal matched. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub proposer: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct FailedOpen { + pub module_id: String, + pub layer: String, + /// `timeout`, `error`, `invalid_decision` or `circuit_open`; the + /// detail is logged. + pub failure: String, } /// Closed, stable enumeration of action categories. Adding a value is diff --git a/crates/server/src/error.rs b/crates/server/src/error.rs index 2a8948df2..b323296c7 100644 --- a/crates/server/src/error.rs +++ b/crates/server/src/error.rs @@ -5,6 +5,9 @@ use chrono::{DateTime, Utc}; use serde::Serialize; use std::fmt; +/// The reason code a generic denial reports, whichever module refused. +pub const GENERIC_REASON_CODE: &str = "policy_denied"; + use guardian_shared::execution::refusal_codes; /// Why Guardian refuses to execute a proposal and leaves it to local execution. @@ -156,6 +159,43 @@ pub enum GuardianError { paused_at: DateTime, paused_reason: Option, }, + /// A policy module refused the request. Stable code `GUARDIAN_MODULE_DENIED`, HTTP 403, + /// gRPC `PERMISSION_DENIED`; `module` is the operator-chosen instance id. + ModuleDenied { + module: String, + reason_code: String, + layer: String, + /// The module's text for the requester, already checked; only for instances with + /// `client_reason = "full"`. + client_message: Option, + }, + /// A denial from an instance with `client_reason = "generic"`: same code and status as + /// [`GuardianError::ModuleDenied`], but nothing about which module refused or why. + ModuleDeniedGeneric, + /// A fail-closed policy module could not decide. Stable code + /// `GUARDIAN_MODULE_UNAVAILABLE`, HTTP 503, gRPC `UNAVAILABLE`, retryable. `module` is absent + /// for an instance whose denials are generic, so a failure names no more than a denial would. + ModuleUnavailable { + module: Option, + }, + /// No policy module instance with this id. Stable code `GUARDIAN_MODULE_NOT_FOUND`, HTTP 404. + ModuleNotFound { + module: String, + }, + /// The instance's catalog entry does not allow operators to disable it. Stable code + /// `GUARDIAN_MODULE_NOT_DISABLEABLE`, HTTP 409. + ModuleNotDisableable { + module: String, + }, + /// An operator params write named the params version it was made against, and the params + /// have changed since. Stable code `GUARDIAN_MODULE_PARAMS_STALE`, HTTP 409. Read them + /// again and reapply the change. + ModuleParamsStale, + /// An operator's policy module write was refused: invalid params, a reason too long, a + /// module the write cannot apply to, the evaluation budget. Stable code `invalid_input`, + /// HTTP 400. Only operators reach it, so unlike other errors the reason goes back to them, + /// in `meta.detail`. + ModuleWriteRefused(String), /// A new account asked to register with a signature scheme this Guardian /// does not accept (`GUARDIAN_ALLOWED_ACCOUNT_SCHEMES`). Stable code /// `signature_scheme_not_allowed`, HTTP 403 Forbidden, gRPC @@ -302,6 +342,14 @@ impl GuardianError { GuardianError::DataUnavailable(_) => StatusCode::SERVICE_UNAVAILABLE, GuardianError::AccountPaused { .. } => StatusCode::CONFLICT, GuardianError::SignatureSchemeNotAllowed { .. } => StatusCode::FORBIDDEN, + GuardianError::ModuleDenied { .. } | GuardianError::ModuleDeniedGeneric => { + StatusCode::FORBIDDEN + } + GuardianError::ModuleUnavailable { .. } => StatusCode::SERVICE_UNAVAILABLE, + GuardianError::ModuleNotFound { .. } => StatusCode::NOT_FOUND, + GuardianError::ModuleNotDisableable { .. } => StatusCode::CONFLICT, + GuardianError::ModuleParamsStale => StatusCode::CONFLICT, + GuardianError::ModuleWriteRefused(_) => StatusCode::BAD_REQUEST, GuardianError::AccountReleased { .. } => StatusCode::CONFLICT, GuardianError::CandidateLanded { .. } => StatusCode::CONFLICT, GuardianError::ProvingUnavailable => StatusCode::CONFLICT, @@ -367,6 +415,14 @@ impl GuardianError { GuardianError::DataUnavailable(_) => tonic::Code::Unavailable, GuardianError::AccountPaused { .. } => tonic::Code::FailedPrecondition, GuardianError::SignatureSchemeNotAllowed { .. } => tonic::Code::PermissionDenied, + GuardianError::ModuleDenied { .. } | GuardianError::ModuleDeniedGeneric => { + tonic::Code::PermissionDenied + } + GuardianError::ModuleUnavailable { .. } => tonic::Code::Unavailable, + GuardianError::ModuleNotFound { .. } => tonic::Code::NotFound, + GuardianError::ModuleNotDisableable { .. } => tonic::Code::FailedPrecondition, + GuardianError::ModuleParamsStale => tonic::Code::Aborted, + GuardianError::ModuleWriteRefused(_) => tonic::Code::InvalidArgument, GuardianError::AccountReleased { .. } => tonic::Code::FailedPrecondition, GuardianError::CandidateLanded { .. } => tonic::Code::FailedPrecondition, GuardianError::ProvingUnavailable => tonic::Code::FailedPrecondition, @@ -431,6 +487,14 @@ impl GuardianError { GuardianError::DataUnavailable(_) => "data_unavailable", GuardianError::AccountPaused { .. } => "GUARDIAN_ACCOUNT_PAUSED", GuardianError::SignatureSchemeNotAllowed { .. } => "signature_scheme_not_allowed", + GuardianError::ModuleDenied { .. } | GuardianError::ModuleDeniedGeneric => { + "GUARDIAN_MODULE_DENIED" + } + GuardianError::ModuleUnavailable { .. } => "GUARDIAN_MODULE_UNAVAILABLE", + GuardianError::ModuleNotFound { .. } => "GUARDIAN_MODULE_NOT_FOUND", + GuardianError::ModuleNotDisableable { .. } => "GUARDIAN_MODULE_NOT_DISABLEABLE", + GuardianError::ModuleParamsStale => "GUARDIAN_MODULE_PARAMS_STALE", + GuardianError::ModuleWriteRefused(_) => "invalid_input", GuardianError::AccountReleased { .. } => "GUARDIAN_ACCOUNT_RELEASED", GuardianError::CandidateLanded { .. } => "GUARDIAN_CANDIDATE_LANDED", GuardianError::ProvingUnavailable => refusal_codes::PROVING_UNAVAILABLE, @@ -543,6 +607,22 @@ impl GuardianError { GuardianError::AccountPaused { .. } => { "This account is paused and can't approve transactions right now." } + GuardianError::ModuleDenied { .. } | GuardianError::ModuleDeniedGeneric => { + "This Guardian's policy doesn't allow this request." + } + GuardianError::ModuleUnavailable { .. } => { + "A policy check is unavailable right now. Please try again shortly." + } + GuardianError::ModuleNotFound { .. } => "That policy module doesn't exist.", + GuardianError::ModuleNotDisableable { .. } => { + "That policy module can't be switched off from the dashboard." + } + GuardianError::ModuleParamsStale => { + "Those policy settings changed since you loaded them. Reload and apply your change again." + } + GuardianError::ModuleWriteRefused(_) => { + "Guardian refused that policy module request; the details say why." + } GuardianError::SignatureSchemeNotAllowed { .. } => { "This Guardian doesn't accept new accounts with that signature scheme." } @@ -620,6 +700,7 @@ impl GuardianError { | GuardianError::StateNotOnChain { .. } | GuardianError::RateLimitExceeded { .. } | GuardianError::DataUnavailable(_) + | GuardianError::ModuleUnavailable { .. } | GuardianError::ExecutionBusy ) } @@ -751,6 +832,42 @@ impl fmt::Display for GuardianError { Some(reason) => write!(f, "Account is paused: {reason}"), None => write!(f, "Account is paused"), }, + GuardianError::ModuleDenied { + module, + reason_code, + layer, + .. + } => write!( + f, + "Policy module '{module}' denied the request ({layer} layer): {reason_code}" + ), + GuardianError::ModuleDeniedGeneric => { + write!(f, "A policy module denied the request (generic denial)") + } + GuardianError::ModuleUnavailable { + module: Some(module), + } => { + write!(f, "Policy module '{module}' is unavailable") + } + GuardianError::ModuleUnavailable { module: None } => { + write!(f, "A policy module is unavailable") + } + GuardianError::ModuleNotFound { module } => { + write!(f, "Policy module '{module}' not found") + } + GuardianError::ModuleWriteRefused(detail) => { + write!(f, "Policy module write refused: {detail}") + } + GuardianError::ModuleParamsStale => write!( + f, + "Module params changed since the version this write was made against" + ), + GuardianError::ModuleNotDisableable { module } => { + write!( + f, + "Policy module '{module}' cannot be disabled by an operator" + ) + } GuardianError::SignatureSchemeNotAllowed { scheme, allowed_schemes, @@ -876,6 +993,19 @@ struct ErrorMeta { /// `signature_scheme_not_allowed`. #[serde(skip_serializing_if = "Option::is_none")] allowed_schemes: Option>, + /// Policy module instance id. Populated only for `GUARDIAN_MODULE_DENIED` and + /// `GUARDIAN_MODULE_UNAVAILABLE`. + #[serde(skip_serializing_if = "Option::is_none")] + module: Option, + /// Machine-readable denial reason. Populated only for `GUARDIAN_MODULE_DENIED`. + #[serde(skip_serializing_if = "Option::is_none")] + reason_code: Option, + /// `global` or `account`: which parameter layer denied. Only for `GUARDIAN_MODULE_DENIED`. + #[serde(skip_serializing_if = "Option::is_none")] + layer: Option, + /// The denying module's text for the requester. Only for a full `GUARDIAN_MODULE_DENIED`. + #[serde(skip_serializing_if = "Option::is_none")] + client_message: Option, /// RFC 3339 UTC timestamp of the guardian-switch release. Populated /// only for `GUARDIAN_ACCOUNT_RELEASED`. #[serde(skip_serializing_if = "Option::is_none")] @@ -892,8 +1022,16 @@ struct ErrorMeta { /// `GUARDIAN_PROPOSAL_EXECUTES_LOCALLY`. Absent for every other error. #[serde(skip_serializing_if = "Option::is_none")] reason: Option<&'static str>, + /// Why an operator's policy module write was refused. Populated only for that refusal + /// (`invalid_input` from a module route). + #[serde(skip_serializing_if = "Option::is_none")] + detail: Option, } +/// Longest `meta.detail` a module write refusal carries. The reason can include a module's own +/// validation message, which a third-party module controls. +const MODULE_WRITE_DETAIL_MAX_CHARS: usize = 1000; + /// The single error object on the wire: `{ code, message, meta }`. Identical /// shape on the HTTP error body and the gRPC `Status.details` (feature /// `009-human-readable-errors`). The legacy `success`/`error` fields are @@ -951,6 +1089,27 @@ impl GuardianError { } => (Some(scheme.clone()), Some(allowed_schemes.clone())), _ => (None, None), }; + let client_message = match self { + GuardianError::ModuleDenied { client_message, .. } => client_message.clone(), + _ => None, + }; + let (module, reason_code, layer) = match self { + GuardianError::ModuleDenied { + module, + reason_code, + layer, + .. + } => ( + Some(module.clone()), + Some(reason_code.clone()), + Some(layer.clone()), + ), + GuardianError::ModuleDeniedGeneric => (None, Some(GENERIC_REASON_CODE.into()), None), + GuardianError::ModuleUnavailable { module } => (module.clone(), None, None), + GuardianError::ModuleNotFound { module } => (Some(module.clone()), None, None), + GuardianError::ModuleNotDisableable { module } => (Some(module.clone()), None, None), + _ => (None, None, None), + }; let blocking_proposal_id = match self { GuardianError::ExecutionConflict { blocking_proposal_id, @@ -973,9 +1132,19 @@ impl GuardianError { scheme, allowed_schemes, released_at, + module, + reason_code, + layer, + client_message, blocking_proposal_id, proposal_type, reason, + detail: match self { + GuardianError::ModuleWriteRefused(detail) => { + Some(detail.chars().take(MODULE_WRITE_DETAIL_MAX_CHARS).collect()) + } + _ => None, + }, } } @@ -995,7 +1164,9 @@ impl IntoResponse for GuardianError { fn into_response(self) -> Response { let status = self.http_status(); // FR-003: the diagnostic Display string is logged for operators, never - // returned on the wire (removes the disclosure risk by construction). + // returned on the wire (removes the disclosure risk by construction). The one + // exception is `ModuleWriteRefused`, which only operators reach: its reason goes + // out in `meta.detail`, capped, never through Display. if status.is_server_error() { tracing::error!(code = self.code(), detail = %self, "guardian error (HTTP 5xx)"); } else { @@ -1301,6 +1472,30 @@ mod tests { assert!(!err.user_message().contains("falcon")); } + #[test] + fn a_generic_module_denial_names_nothing_but_the_generic_reason() { + let body = serde_json::to_value(GuardianError::ModuleDeniedGeneric.error_body()).unwrap(); + assert_eq!(body["code"], "GUARDIAN_MODULE_DENIED"); + assert_eq!( + body["meta"], + serde_json::json!({ "retryable": false, "reason_code": "policy_denied" }) + ); + assert_eq!( + GuardianError::ModuleDeniedGeneric.http_status(), + StatusCode::FORBIDDEN + ); + + let full = GuardianError::ModuleDenied { + module: "caps".into(), + reason_code: "amount_cap_exceeded".into(), + layer: "account".into(), + client_message: Some("Ask your treasury admin.".into()), + }; + let body = serde_json::to_value(full.error_body()).unwrap(); + assert_eq!(body["meta"]["module"], "caps"); + assert_eq!(body["meta"]["client_message"], "Ask your treasury admin."); + } + #[test] fn signature_scheme_not_allowed_meta_names_the_scheme_and_allowed_set() { let body = serde_json::to_value(scheme_not_allowed().error_body()).unwrap(); @@ -1518,6 +1713,29 @@ mod tests { // --- IntoResponse / tonic::Status --- + #[test] + fn a_module_write_refusal_tells_the_operator_why_in_meta_only() { + let refusal = GuardianError::ModuleWriteRefused("module caps: cap is not a number".into()); + let body = serde_json::to_value(refusal.error_body()).unwrap(); + assert_eq!(body["code"], "invalid_input"); + assert_eq!(body["meta"]["detail"], "module caps: cap is not a number"); + assert!(!body["message"].as_str().unwrap().contains("caps")); + let other = + serde_json::to_value(GuardianError::InvalidInput("/var/secret".into()).error_body()) + .unwrap(); + assert!( + other["meta"].get("detail").is_none(), + "no other error carries a detail" + ); + let long = GuardianError::ModuleWriteRefused("x".repeat(5_000)); + let body = serde_json::to_value(long.error_body()).unwrap(); + assert_eq!( + body["meta"]["detail"].as_str().unwrap().chars().count(), + MODULE_WRITE_DETAIL_MAX_CHARS, + "a module's message cannot make the response arbitrarily large" + ); + } + #[test] fn into_response_returns_correct_status() { let err = GuardianError::AccountNotFound("x".into()); diff --git a/crates/server/src/jobs/execution_reconcile/mod.rs b/crates/server/src/jobs/execution_reconcile/mod.rs index 6bee4c0df..7644ec7e2 100644 --- a/crates/server/src/jobs/execution_reconcile/mod.rs +++ b/crates/server/src/jobs/execution_reconcile/mod.rs @@ -23,7 +23,7 @@ pub enum PassKind { } /// What one pass did with one execution. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[derive(Debug, Clone, PartialEq, Eq)] pub enum Reconciled { /// A live worker still owns the attempt, or another reconciler does. Owned, @@ -43,7 +43,7 @@ pub enum Reconciled { } impl Reconciled { - fn label(self) -> &'static str { + fn label(&self) -> &'static str { match self { Reconciled::Owned => "owned", Reconciled::Released(_) => "released", @@ -162,7 +162,7 @@ impl Reconciler { PassKind::Steady => ExecutionFailureCode::LeaseExpired, }; let failure = ExecutionFailure { - code, + code: code.clone(), message: "the attempt stopped renewing its lease before the no-retry boundary" .to_string(), }; @@ -233,7 +233,10 @@ impl Reconciler { Reconciled::Waiting } Observed::Settles(code, message) => { - let failure = ExecutionFailure { code, message }; + let failure = ExecutionFailure { + code: code.clone(), + message, + }; match state .storage .resolve_execution(state.metadata.as_ref(), resolution(record, &fence, failure)) diff --git a/crates/server/src/lib.rs b/crates/server/src/lib.rs index eea83b8e1..0e1a00eff 100644 --- a/crates/server/src/lib.rs +++ b/crates/server/src/lib.rs @@ -26,6 +26,7 @@ pub mod evm; pub mod jobs; pub mod metadata; pub mod metrics; +pub mod modules; pub mod network; pub mod openapi; pub(crate) mod secret; diff --git a/crates/server/src/main.rs b/crates/server/src/main.rs index d609e5133..42131c2cd 100644 --- a/crates/server/src/main.rs +++ b/crates/server/src/main.rs @@ -1,87 +1,17 @@ pub use guardian_shared::{FromJson, ToJson}; -use server::ack::AckRegistry; -use server::builder::{ServerBuilder, storage::StorageMetadataBuilder}; -use server::canonicalization::CanonicalizationConfig; -use server::config::stage::Stage; -use server::logging::LoggingConfig; -use server::middleware::{BodyLimitConfig, CorsConfig, RateLimitConfig}; -use server::network::{NetworkType, RpcSettings}; -use std::env; -use std::path::PathBuf; +use server::builder::ServerBuilder; #[tokio::main] async fn main() { dotenvy::dotenv().ok(); - let keystore_path: PathBuf = env::var("GUARDIAN_KEYSTORE_PATH") - .unwrap_or_else(|_| "/var/guardian/keystore".to_string()) - .into(); - - let (storage_backend, metadata, auditor, coordination) = StorageMetadataBuilder::from_env() - .build() - .await - .expect("Failed to initialize storage backends"); - - // Initialize acknowledger registry (supports both Falcon and ECDSA) - let ack = AckRegistry::new(keystore_path) + ServerBuilder::from_env() .await - .expect("Failed to initialize ack registry"); - - let cors_layer = CorsConfig::from_env() - .expect("Failed to initialize CORS config") - .layer(); - - let network_type = - NetworkType::from_env("GUARDIAN_NETWORK_TYPE").expect("Failed to resolve network type"); - - let stage = Stage::from_env().expect("Invalid GUARDIAN_ENV"); - - let release_sweep = server::release_sweep::ReleaseSweepConfig::from_env() - .expect("Invalid release sweep configuration"); - ServerBuilder::new() - .with_logging(LoggingConfig::default()) - .network(network_type) - .with_rpc(RpcSettings::from_env(network_type).expect("Invalid RPC configuration")) - .with_canonicalization(Some( - CanonicalizationConfig::new(10, 48) - .with_stage_defaults(stage) - .with_submission_grace_period_seconds(600) - .with_fast_promotion_enabled_from_env() - .expect("Invalid fast promotion configuration") - .with_max_concurrent_accounts_from_env() - .expect("Invalid canonicalization concurrency configuration") - .with_retained_ttl_seconds_from_env() - .expect("Invalid retained TTL configuration") - .with_reconcile_interval_seconds_from_env() - .expect("Invalid reconcile interval configuration") - .with_max_pending_candidates_per_account_from_env() - .expect("Invalid pending-candidate queue depth configuration") - .with_rebuild_admission_from_env() - .expect("Invalid canonicalization rebuild admission configuration"), - )) - .with_execution( - server::config::execution::ExecutionConfig::from_env() - .expect("Invalid Guardian execution configuration"), - ) - .with_release_sweep(Some(release_sweep.clone())) - .with_block_watch(Some( - server::block_watch::BlockWatchConfig::from_env_following(release_sweep.enabled) - .expect("Invalid block watch configuration"), - )) - .with_rate_limit(RateLimitConfig::from_env()) - .with_body_limit(BodyLimitConfig::from_env()) - .storage(storage_backend) - .metadata(metadata) - .auditor(auditor) - .coordination(coordination) - .ack(ack) - .http(true, 3000) - .grpc(true, 50051) - .cors(cors_layer) + .unwrap_or_else(|error| panic!("Failed to configure server: {error}")) .build() .await - .expect("Failed to build server") + .unwrap_or_else(|error| panic!("Failed to build server: {error}")) .run() .await; } diff --git a/crates/server/src/metadata/network.rs b/crates/server/src/metadata/network.rs index 509f0d7e5..634eae37d 100644 --- a/crates/server/src/metadata/network.rs +++ b/crates/server/src/metadata/network.rs @@ -27,6 +27,17 @@ pub enum MidenNetworkType { } impl MidenNetworkType { + /// The network's name as stored and as policy modules receive it in `network_id`. + pub fn as_str(self) -> &'static str { + match self { + MidenNetworkType::Local => "local", + MidenNetworkType::Devnet => "devnet", + MidenNetworkType::Testnet => "testnet", + MidenNetworkType::Cedar => "cedar", + MidenNetworkType::Mainnet => "mainnet", + } + } + /// Bech32 human-readable prefix of Cedar addresses. Today the same string /// as the protocol's mainnet prefix, kept separate so Cedar stays on `mm` /// if mainnet moves. diff --git a/crates/server/src/metrics/names.rs b/crates/server/src/metrics/names.rs index 9695bf408..cb07f4a76 100644 --- a/crates/server/src/metrics/names.rs +++ b/crates/server/src/metrics/names.rs @@ -159,6 +159,19 @@ pub const DASHBOARD_STATS_REFRESH_FAILURES_TOTAL: &str = pub const DASHBOARD_STATS_REFRESH_DURATION_SECONDS: &str = "guardian_dashboard_stats_refresh_duration_seconds"; +// --- Policy modules ------------------------------------------------------- + +pub const MODULE_EVALUATE_DURATION_SECONDS: &str = "guardian_module_evaluate_duration_seconds"; +pub const MODULE_FAIL_OPEN_TOTAL: &str = "guardian_module_fail_open_total"; +pub const MODULE_REQUEST_REFUSED_TOTAL: &str = "guardian_module_request_refused_total"; +pub const MODULE_UP: &str = "guardian_module_up"; +pub const MODULE_CIRCUIT_OPEN: &str = "guardian_module_circuit_open"; +pub const MODULE_ENABLED: &str = "guardian_module_enabled"; +pub const MODULE_CONFIG_DRIFT: &str = "guardian_module_config_drift"; +pub const MODULE_CATALOG_INFO: &str = "guardian_module_catalog_info"; +pub const MODULE_OVER_BUDGET_ACCOUNTS: &str = "guardian_module_over_budget_accounts"; +pub const MODULE_ORPHANED_ASSIGNMENTS: &str = "guardian_module_orphaned_assignments"; + // --- Build identity ------------------------------------------------------ pub const BUILD_INFO: &str = "guardian_build_info"; @@ -183,6 +196,10 @@ pub const LABEL_PROFILE: &str = "profile"; pub const LABEL_PHASE: &str = "phase"; pub const LABEL_CREDENTIAL: &str = "credential"; pub const LABEL_REASON: &str = "reason"; +/// A policy module instance id; bounded by the operator's catalog. +pub const LABEL_MODULE: &str = "module"; +/// The loaded module catalog's hash; one value per deploy. +pub const LABEL_CATALOG_HASH: &str = "catalog_hash"; /// The closed value set for `LABEL_TRANSPORT`: the request transports, /// and the block transports of block watch (`stream`, `poll`). @@ -211,6 +228,8 @@ pub const LABEL_ALLOWLIST: &[&str] = &[ LABEL_PHASE, LABEL_CREDENTIAL, LABEL_REASON, + LABEL_MODULE, + LABEL_CATALOG_HASH, ]; /// Metric type, mirroring the Prometheus instrument kinds in use. @@ -742,6 +761,66 @@ pub const REGISTRY: &[MetricDef] = &[ help: "Wall-clock duration of one /dashboard/stats aggregate refresh \ (metadata walk, batched state reads, vault decoding).", }, + MetricDef { + name: MODULE_EVALUATE_DURATION_SECONDS, + kind: MetricKind::Histogram, + labels: &[LABEL_MODULE, LABEL_OUTCOME], + help: "Policy module evaluations in seconds, by instance and outcome (allow, deny, error, skipped).", + }, + MetricDef { + name: MODULE_FAIL_OPEN_TOTAL, + kind: MetricKind::Counter, + labels: &[LABEL_MODULE], + help: "Policy module failures a fail-open instance let through, by instance.", + }, + MetricDef { + name: MODULE_REQUEST_REFUSED_TOTAL, + kind: MetricKind::Counter, + labels: &[LABEL_MODULE, LABEL_REASON], + help: "Requests refused without calling a policy module, whatever its on_error, because the Guardian could not build them (reason unavailable) or they exceed the size cap (reason too_large), by instance.", + }, + MetricDef { + name: MODULE_UP, + kind: MetricKind::Gauge, + labels: &[LABEL_MODULE], + help: "1 when the instance's last health probe succeeded, 0 when it failed.", + }, + MetricDef { + name: MODULE_CIRCUIT_OPEN, + kind: MetricKind::Gauge, + labels: &[LABEL_MODULE], + help: "1 while the instance's circuit breaker is open on this replica.", + }, + MetricDef { + name: MODULE_ENABLED, + kind: MetricKind::Gauge, + labels: &[LABEL_MODULE], + help: "1 when the instance is enabled, 0 when an operator disabled it.", + }, + MetricDef { + name: MODULE_CONFIG_DRIFT, + kind: MetricKind::Gauge, + labels: &[LABEL_MODULE], + help: "1 when the catalog's enabled flag or params differ from the stored runtime values.", + }, + MetricDef { + name: MODULE_CATALOG_INFO, + kind: MetricKind::Gauge, + labels: &[LABEL_CATALOG_HASH], + help: "The module catalog this replica loaded (constant 1).", + }, + MetricDef { + name: MODULE_OVER_BUDGET_ACCOUNTS, + kind: MetricKind::Gauge, + labels: &[], + help: "Accounts whose stored modules could exceed the evaluation budget, found at startup.", + }, + MetricDef { + name: MODULE_ORPHANED_ASSIGNMENTS, + kind: MetricKind::Gauge, + labels: &[], + help: "Stored account module rows naming an instance the catalog no longer declares, found at startup.", + }, ]; /// Bound the `route` label to the axum route template. Templates like @@ -797,6 +876,8 @@ const KNOWN_GRPC_METHODS: &[(&str, &str)] = &[ ("guardian.Guardian", "CreateSession"), ("guardian.Guardian", "RevokeSession"), ("guardian.Guardian", "RevokeAllSessions"), + ("guardian.Guardian", "GetPolicies"), + ("guardian.Guardian", "CheckDeltaProposal"), // Served alongside Guardian via tonic-reflection (v1 and v1alpha). ( "grpc.reflection.v1.ServerReflection", @@ -946,16 +1027,16 @@ mod tests { } /// The CloudWatch export re-lists the metric inventory by hand - /// (`infra/observability.tf`); a block watch metric missing there + /// (`infra/observability.tf`); a block watch or module metric missing there /// would never reach CloudWatch, and its histogram would be exported /// with lifetime totals unless it is delta-converted too. #[test] - fn block_watch_metrics_are_exported_to_cloudwatch() { + fn block_watch_and_module_metrics_are_exported_to_cloudwatch() { let terraform = include_str!("../../../../infra/observability.tf"); - for def in REGISTRY - .iter() - .filter(|def| def.name.starts_with("guardian_block_watch_")) - { + for def in REGISTRY.iter().filter(|def| { + def.name.starts_with("guardian_block_watch_") + || def.name.starts_with("guardian_module_") + }) { assert!( terraform.contains(&format!("\"^{}$\"", def.name)), "{} is not selected by an ADOT metric declaration", diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs new file mode 100644 index 000000000..c6afb4004 --- /dev/null +++ b/crates/server/src/modules/admin.rs @@ -0,0 +1,1749 @@ +//! Operator management of module parameters: global params, account layers, assignments. + +use serde::Serialize; + +use super::catalog::{ClientReason, Disclosure, Scope, contains_secret_reference}; +use super::pipeline::ModulePipeline; +use super::registry::{Instance, Unhealthy, validate_params}; +use super::store::{Assigned, Change, HistoryEntry, ParamsKind, WriteError}; +use crate::audit::{AuditEvent, AuditOutcome, kinds}; +use crate::dashboard::AuthenticatedOperator; +use crate::error::{GuardianError, Result}; +use crate::state::AppState; + +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] +pub struct ModuleInstanceView { + pub module_id: String, + pub kind: String, + #[schema(value_type = String)] + pub scope: &'static str, + pub hooks: Vec, + pub enabled: bool, + pub catalog_enabled: bool, + pub enabled_drift: bool, + pub operator_can_disable: bool, + #[schema(value_type = Object)] + pub params: serde_json::Value, + pub params_drift: bool, + pub file_managed_params: bool, + /// `name version` from `describe` at startup; absent when the startup checks failed. + pub build: Option, + pub disclosure: Disclosure, + #[serde(skip_serializing_if = "Option::is_none")] + pub description: Option, + pub client_reason: ClientReason, + pub dry_run: bool, + /// The instance's circuit breaker on the replica that answered: `closed`, `open` or + /// `half_open`. + #[schema(value_type = String)] + pub circuit: &'static str, +} + +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] +pub struct ModuleCatalogView { + pub catalog_hash: String, + pub params_version: u64, + pub modules: Vec, + /// Stored instances the catalog no longer declares: kept, never evaluated, active again if + /// the catalog brings the id back. + pub undeclared: Vec, +} + +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] +pub struct UndeclaredInstanceView { + pub module_id: String, + pub enabled: bool, + #[schema(value_type = Object)] + pub params: serde_json::Value, +} + +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] +pub struct AccountModuleEntry { + pub module_id: String, + #[schema(value_type = String)] + pub scope: &'static str, + pub enabled: bool, + /// A stored entry naming an instance the catalog no longer declares; skipped at evaluation. + pub orphaned: bool, + #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] + pub global_params: Option, + #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] + pub account_layer: Option, + #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] + pub params: Option, +} + +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] +pub struct AccountModulesView { + pub account_id: String, + /// The account's params version: moves with every write to its layers or assignment, and + /// is recorded with each delta the account's modules approve. + pub account_params_version: u64, + pub modules: Vec, +} + +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] +pub struct ParamsHistoryView { + pub module_id: String, + pub entries: Vec, +} + +fn scope_name(scope: Scope) -> &'static str { + match scope { + Scope::All => "all", + Scope::Default => "default", + Scope::Assigned => "assigned", + } +} + +fn pipeline(state: &AppState) -> Result<&ModulePipeline> { + state + .modules + .as_deref() + .ok_or_else(|| GuardianError::ModuleWriteRefused("no policy modules are configured".into())) +} + +fn instance<'a>(pipeline: &'a ModulePipeline, module_id: &str) -> Result<&'a Instance> { + pipeline + .instance(module_id) + .ok_or_else(|| GuardianError::ModuleNotFound { + module: module_id.to_string(), + }) +} + +const MAX_REASON_CHARS: usize = 512; + +fn require_reason(reason: &str) -> Result<()> { + if reason.trim().is_empty() { + return Err(GuardianError::ModuleWriteRefused( + "reason is required".into(), + )); + } + if reason.chars().count() > MAX_REASON_CHARS { + return Err(GuardianError::ModuleWriteRefused(format!( + "reason exceeds {MAX_REASON_CHARS} character limit" + ))); + } + Ok(()) +} + +/// Validates operator-supplied params and returns what to store: the module's normalized form +/// when it sent one. +async fn validated( + pipeline: &ModulePipeline, + instance: &Instance, + params: &serde_json::Value, +) -> Result { + if !params.is_object() { + return Err(GuardianError::ModuleWriteRefused( + "params must be a JSON object".into(), + )); + } + pipeline.limits().check_params_size(params).map_err(|e| { + GuardianError::ModuleWriteRefused(format!("module {}: {e}", instance.config.id)) + })?; + if contains_secret_reference(params) { + return Err(GuardianError::ModuleWriteRefused( + "secret references cannot be set through the operator API".into(), + )); + } + let stored = validate_params(&instance.module, params, instance.config.timeout) + .await + .map_err(|e| match e { + Unhealthy::InvalidParams(_) => { + GuardianError::ModuleWriteRefused(format!("module {}: {e}", instance.config.id)) + } + Unhealthy::Unreachable(_) | Unhealthy::Incompatible(_) => { + tracing::warn!(module = %instance.config.id, error = %e, "Policy module could not validate operator params"); + GuardianError::ModuleUnavailable { + module: Some(instance.config.id.clone()), + } + } + })?; + pipeline.storable_normalization(&stored).map_err(|e| { + GuardianError::ModuleWriteRefused(format!("module {}: {e}", instance.config.id)) + })?; + Ok(stored) +} + +/// The key the account's module rows use: its id lowercased, as evaluation looks them up. +/// Registration stores the id as the client sent it, so the account is looked up as given and +/// then lowercased. +async fn existing_account(state: &AppState, account_id: &str) -> Result { + let key = account_id.to_ascii_lowercase(); + for candidate in [account_id, key.as_str()] { + match state.metadata.get(candidate).await { + Ok(Some(_)) => return Ok(key.clone()), + Ok(None) => continue, + Err(e) => { + return Err(GuardianError::StorageError(format!( + "account lookup failed: {e}" + ))); + } + } + } + Err(GuardianError::AccountNotFound(account_id.to_string())) +} + +async fn version(pipeline: &ModulePipeline) -> Result { + pipeline + .store() + .instance_version() + .await + .map_err(GuardianError::StorageError) +} + +fn audit( + state: &AppState, + operator: &AuthenticatedOperator, + kind: &'static str, + account_id: Option<&str>, + payload: serde_json::Value, + client_ip: Option, +) { + state.auditor.record(AuditEvent { + operator_identity: operator.operator_id.clone(), + action_kind: kind, + target_account_id: account_id.map(str::to_string), + payload, + outcome: AuditOutcome::Success, + error_code: None, + client_ip, + }); +} + +fn change<'a>( + state: &AppState, + operator: &'a AuthenticatedOperator, + reason: &'a str, +) -> Change<'a> { + Change { + operator: &operator.operator_id, + reason, + at: state.clock.now_rfc3339(), + expected_version: None, + } +} + +/// An operator's params write: its reason and, optionally, the params version it was made +/// against (the instance params version for a global write, the account's for a layer or an +/// assignment), so a write from a stale read is refused instead of dropping a newer change. +#[derive(Debug, Clone, Copy)] +pub struct Write<'a> { + pub reason: &'a str, + pub expected_version: Option, +} + +impl<'a> From<&'a str> for Write<'a> { + fn from(reason: &'a str) -> Self { + Write { + reason, + expected_version: None, + } + } +} + +impl<'a> From<&'a String> for Write<'a> { + fn from(reason: &'a String) -> Self { + Write::from(reason.as_str()) + } +} + +fn change_for<'a>( + state: &AppState, + operator: &'a AuthenticatedOperator, + write: Write<'a>, +) -> Change<'a> { + Change { + expected_version: write.expected_version, + ..change(state, operator, write.reason) + } +} + +fn write_error(error: WriteError) -> GuardianError { + match error { + WriteError::Stale { .. } => GuardianError::ModuleParamsStale, + WriteError::Storage(message) => GuardianError::StorageError(message), + } +} + +async fn instance_view( + pipeline: &ModulePipeline, + instance: &Instance, +) -> Result { + let params = pipeline.global_params(instance).await?; + let enabled = pipeline.enabled(instance).await?; + let seeded = pipeline + .store() + .instances() + .await + .map_err(GuardianError::StorageError)? + .into_iter() + .find(|row| row.module_id == instance.config.id) + .map(|row| row.seeded_params); + Ok(ModuleInstanceView { + module_id: instance.config.id.clone(), + kind: instance.config.kind.clone(), + scope: scope_name(instance.config.scope), + hooks: instance + .config + .hooks + .iter() + .map(|hook| hook.as_str().to_string()) + .collect(), + enabled, + catalog_enabled: instance.config.catalog_enabled, + enabled_drift: enabled != instance.config.catalog_enabled, + operator_can_disable: instance.config.operator_can_disable, + params_drift: !instance.config.file_managed_params + && seeded.is_some_and(|seeded| seeded != instance.config.params), + params, + file_managed_params: instance.config.file_managed_params, + build: instance.build.clone(), + disclosure: instance.config.disclosure, + description: instance.config.description.clone(), + client_reason: instance.config.client_reason, + dry_run: instance.config.dry_run, + circuit: pipeline.breakers().state(&instance.config.id).as_str(), + }) +} + +pub async fn catalog_view(state: &AppState) -> Result { + let pipeline = pipeline(state)?; + let mut modules = Vec::with_capacity(pipeline.instances().len()); + for instance in pipeline.instances() { + modules.push(instance_view(pipeline, instance).await?); + } + let undeclared = pipeline + .store() + .instances() + .await + .map_err(GuardianError::StorageError)? + .into_iter() + .filter(|row| pipeline.instance(&row.module_id).is_none()) + .map(|row| UndeclaredInstanceView { + module_id: row.module_id, + enabled: row.enabled, + params: row.global_params, + }) + .collect(); + Ok(ModuleCatalogView { + catalog_hash: pipeline.catalog_hash.clone(), + params_version: version(pipeline).await?, + modules, + undeclared, + }) +} + +pub async fn account_view(state: &AppState, account_id: &str) -> Result { + let account_id = existing_account(state, account_id).await?; + view_of(state, &account_id).await +} + +/// The modules of the account whose module rows are keyed `account_id`. +async fn view_of(state: &AppState, account_id: &str) -> Result { + let pipeline = pipeline(state)?; + let super::pipeline::Snapshot { + account_params_version, + rows: instance_rows, + account_rows: rows, + .. + } = pipeline.snapshot(account_id).await?; + let mut modules = Vec::new(); + for instance in pipeline + .instances() + .iter() + .filter(|instance| instance.config.scope == Scope::All) + { + modules.push(AccountModuleEntry { + module_id: instance.config.id.clone(), + scope: "all", + enabled: ModulePipeline::enabled_in(&instance_rows, instance), + orphaned: false, + global_params: Some(ModulePipeline::global_params_in(&instance_rows, instance)), + account_layer: rows + .iter() + .find(|row| row.kind == ParamsKind::Layer && row.module_id == instance.config.id) + .map(|row| row.params.clone()), + params: None, + }); + } + for row in rows.iter().filter(|row| { + row.kind == ParamsKind::Layer && !pipeline.row_applies(&row.module_id, row.kind) + }) { + modules.push(AccountModuleEntry { + module_id: row.module_id.clone(), + scope: pipeline + .instance(&row.module_id) + .map_or("all", |instance| scope_name(instance.config.scope)), + enabled: false, + orphaned: true, + global_params: None, + account_layer: Some(row.params.clone()), + params: None, + }); + } + for row in rows + .into_iter() + .filter(|row| row.kind == ParamsKind::Assignment) + { + let instance = pipeline.instance(&row.module_id); + modules.push(AccountModuleEntry { + scope: instance.map_or("assigned", |instance| scope_name(instance.config.scope)), + enabled: match instance { + Some(instance) => ModulePipeline::enabled_in(&instance_rows, instance), + None => false, + }, + orphaned: !pipeline.row_applies(&row.module_id, ParamsKind::Assignment), + module_id: row.module_id, + global_params: None, + account_layer: None, + params: Some(row.params), + }); + } + Ok(AccountModulesView { + account_id: account_id.to_string(), + account_params_version, + modules, + }) +} + +const HISTORY_PAGE_DEFAULT: usize = 100; +const HISTORY_PAGE_MAX: usize = 1_000; + +/// The instance's params changes, global and per account, newest first: those whose `id` is +/// below `before` when set, at most `limit` (default 100, at most 1,000). +pub async fn history( + state: &AppState, + module_id: &str, + before: Option, + limit: Option, +) -> Result { + let pipeline = pipeline(state)?; + instance(pipeline, module_id)?; + let limit = limit.unwrap_or(HISTORY_PAGE_DEFAULT); + if limit == 0 || limit > HISTORY_PAGE_MAX { + return Err(GuardianError::ModuleWriteRefused(format!( + "limit must be between 1 and {HISTORY_PAGE_MAX}" + ))); + } + let entries = pipeline + .store() + .history(module_id, before, limit) + .await + .map_err(GuardianError::StorageError)?; + Ok(ParamsHistoryView { + module_id: module_id.to_string(), + entries, + }) +} + +/// Switches an instance on for every account, after re-running its startup checks. +/// Idempotent: enabling an enabled instance changes nothing but is still audited. +pub async fn enable( + state: &AppState, + operator: &AuthenticatedOperator, + module_id: &str, + reason: &str, + client_ip: Option, +) -> Result { + require_reason(reason)?; + let pipeline = pipeline(state)?; + let instance = instance(pipeline, module_id)?; + let mut committed = None; + if !pipeline.enabled(instance).await? { + let params = pipeline.global_params(instance).await?; + let checked = super::registry::check(&instance.config, &instance.module, ¶ms) + .await + .map_err(|error| { + tracing::warn!(module = %module_id, %error, "Module failed its checks; not enabled"); + GuardianError::ModuleUnavailable { + module: Some(module_id.to_string()), + } + })?; + let storable = pipeline + .storable_normalization(&checked.params) + .inspect_err(|error| { + tracing::warn!(module = %module_id, %error, "Module's normalized params break the params rules; kept the stored params"); + }) + .is_ok(); + if checked.params != params && !instance.config.file_managed_params && storable { + let migrator = format!( + "module:{}", + instance.build.as_deref().unwrap_or(&instance.config.kind) + ); + let migrated = pipeline + .store() + .set_global_if( + module_id, + ¶ms, + checked.params, + &Change { + operator: &migrator, + reason: "params migrated by the module", + at: state.clock.now_rfc3339(), + expected_version: None, + }, + ) + .await + .map_err(GuardianError::StorageError)?; + if migrated.is_none() { + tracing::warn!(module = %module_id, "Global params changed while the module migrated them; kept the newer value"); + } + } + committed = Some( + pipeline + .store() + .set_enabled(module_id, true, &change(state, operator, reason)) + .await + .map_err(GuardianError::StorageError)?, + ); + super::metrics::enabled(module_id, true); + } + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": committed }); + audit( + state, + operator, + kinds::MODULES_ENABLE, + None, + payload, + client_ip, + ); + instance_view(pipeline, instance).await +} + +/// Switches an instance off for every account, only if its catalog entry allows it. +pub async fn disable( + state: &AppState, + operator: &AuthenticatedOperator, + module_id: &str, + reason: &str, + client_ip: Option, +) -> Result { + require_reason(reason)?; + let pipeline = pipeline(state)?; + let instance = instance(pipeline, module_id)?; + if !instance.config.operator_can_disable { + return Err(GuardianError::ModuleNotDisableable { + module: module_id.to_string(), + }); + } + let mut committed = None; + if pipeline.enabled(instance).await? { + committed = Some( + pipeline + .store() + .set_enabled(module_id, false, &change(state, operator, reason)) + .await + .map_err(GuardianError::StorageError)?, + ); + super::metrics::enabled(module_id, false); + } + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": committed }); + audit( + state, + operator, + kinds::MODULES_DISABLE, + None, + payload, + client_ip, + ); + instance_view(pipeline, instance).await +} + +pub async fn set_global<'a>( + state: &AppState, + operator: &'a AuthenticatedOperator, + module_id: &str, + params: serde_json::Value, + write: impl Into>, + client_ip: Option, +) -> Result { + let write = write.into(); + let reason = write.reason; + require_reason(reason)?; + let pipeline = pipeline(state)?; + let instance = instance(pipeline, module_id)?; + if instance.config.file_managed_params { + return Err(GuardianError::ModuleWriteRefused(format!( + "module {module_id}: params with secret references are managed in the catalog file" + ))); + } + let params = validated(pipeline, instance, ¶ms).await?; + let committed = pipeline + .store() + .set_global(module_id, params, &change_for(state, operator, write)) + .await + .map_err(write_error)?; + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": committed }); + audit( + state, + operator, + kinds::MODULES_PARAMS_GLOBAL, + None, + payload, + client_ip, + ); + instance_view(pipeline, instance).await +} + +pub async fn set_layer<'a>( + state: &AppState, + operator: &'a AuthenticatedOperator, + account_id: &str, + module_id: &str, + params: Option, + write: impl Into>, + client_ip: Option, +) -> Result { + let write = write.into(); + let reason = write.reason; + require_reason(reason)?; + let pipeline = pipeline(state)?; + let account_id = existing_account(state, account_id).await?; + let instance = instance(pipeline, module_id)?; + if params.is_some() && instance.config.scope != Scope::All { + return Err(GuardianError::ModuleWriteRefused(format!( + "module {module_id}: account layers apply only to scope = \"all\" instances; assign it instead" + ))); + } + let params = match params { + Some(params) => Some(validated(pipeline, instance, ¶ms).await?), + None => None, + }; + let current = pipeline + .store() + .account_params(&account_id) + .await + .map_err(GuardianError::StorageError)?; + if params.is_some() + && current + .iter() + .any(|row| row.kind == ParamsKind::Assignment && row.module_id == module_id) + { + return Err(GuardianError::ModuleWriteRefused(format!( + "module {module_id}: the account still has it assigned from when it applied only to assigned accounts; remove it from the account's assignment first" + ))); + } + let mut rows = current.clone(); + rows.retain(|row| !(row.kind == ParamsKind::Layer && row.module_id == module_id)); + if let Some(params) = ¶ms { + rows.push(proposed_row( + &account_id, + module_id, + ParamsKind::Layer, + params, + )); + } + pipeline.check_budget(¤t, &rows)?; + let committed = pipeline + .store() + .set_layer( + &account_id, + module_id, + params, + &change_for(state, operator, write), + ) + .await + .map_err(write_error)?; + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "account_params_version": committed }); + audit( + state, + operator, + kinds::MODULES_PARAMS_ACCOUNT, + Some(&account_id), + payload, + client_ip, + ); + view_of(state, &account_id).await +} + +/// A row as a pending write would store it, for the budget check before the write. +fn proposed_row( + account_id: &str, + module_id: &str, + kind: ParamsKind, + params: &serde_json::Value, +) -> super::store::AccountParamsRow { + super::store::AccountParamsRow { + account_id: account_id.to_string(), + module_id: module_id.to_string(), + kind, + position: 0, + params: params.clone(), + updated_at: String::new(), + updated_by: String::new(), + } +} + +pub async fn set_assignment<'a>( + state: &AppState, + operator: &'a AuthenticatedOperator, + account_id: &str, + modules: Vec, + write: impl Into>, + client_ip: Option, +) -> Result { + let write = write.into(); + let reason = write.reason; + require_reason(reason)?; + let pipeline = pipeline(state)?; + let account_id = existing_account(state, account_id).await?; + let current = pipeline + .store() + .account_params(&account_id) + .await + .map_err(GuardianError::StorageError)?; + let mut to_store = Vec::with_capacity(modules.len()); + for (index, assigned) in modules.iter().enumerate() { + let instance = instance(pipeline, &assigned.module_id)?; + if instance.config.scope == Scope::All { + return Err(GuardianError::ModuleWriteRefused(format!( + "module {}: scope = \"all\" applies to every account; set an account layer instead", + assigned.module_id + ))); + } + if modules[..index] + .iter() + .any(|earlier| earlier.module_id == assigned.module_id) + { + return Err(GuardianError::ModuleWriteRefused(format!( + "module {} listed twice", + assigned.module_id + ))); + } + let kept = current.iter().any(|row| { + row.kind == ParamsKind::Assignment + && row.module_id == assigned.module_id + && row.params == assigned.params + }); + let params = if kept { + assigned.params.clone() + } else { + validated(pipeline, instance, &assigned.params).await? + }; + to_store.push(Assigned { + module_id: assigned.module_id.clone(), + params, + }); + } + if let Some(layer) = current.iter().find(|row| { + row.kind == ParamsKind::Layer + && to_store + .iter() + .any(|assigned| assigned.module_id == row.module_id) + }) { + return Err(GuardianError::ModuleWriteRefused(format!( + "module {}: the account still has a layer on it from when it applied to every account; delete the layer first", + layer.module_id + ))); + } + // Rows naming an instance the catalog no longer declares are kept as they are: they apply + // again if the instance comes back, and the operator cannot list them in the request. + to_store.extend( + current + .iter() + .filter(|row| { + row.kind == ParamsKind::Assignment && pipeline.instance(&row.module_id).is_none() + }) + .map(|row| Assigned { + module_id: row.module_id.clone(), + params: row.params.clone(), + }), + ); + let mut rows = current.clone(); + rows.retain(|row| row.kind == ParamsKind::Layer); + rows.extend(to_store.iter().map(|assigned| { + proposed_row( + &account_id, + &assigned.module_id, + ParamsKind::Assignment, + &assigned.params, + ) + })); + pipeline.check_budget(¤t, &rows)?; + let assigned: Vec = to_store + .iter() + .map(|assigned| assigned.module_id.clone()) + .collect(); + let committed = pipeline + .store() + .set_assignment(&account_id, to_store, &change_for(state, operator, write)) + .await + .map_err(write_error)?; + let payload = serde_json::json!({ "reason": reason, "modules": assigned, "account_params_version": committed }); + audit( + state, + operator, + kinds::MODULES_ASSIGNMENT, + Some(&account_id), + payload, + client_ip, + ); + view_of(state, &account_id).await +} + +#[cfg(test)] +mod tests { + use std::collections::BTreeSet; + use std::sync::Arc; + + use guardian_module_sdk::policies::RecipientPolicy; + use serde_json::json; + + use super::*; + use crate::metadata::AccountMetadata; + use crate::metadata::auth::Auth; + use crate::modules::catalog::{HookName, OnError}; + use crate::modules::testing::{instance, instance_with_params, pipeline}; + use crate::testing::helpers::create_test_app_state_with_mocks; + use crate::testing::mocks::{MockMetadataStore, MockNetworkClient, MockStorageBackend}; + + const ACCOUNT: &str = "0xacc"; + + fn operator() -> AuthenticatedOperator { + AuthenticatedOperator { + operator_id: "0xop".into(), + commitment: "0xop".into(), + effective_permissions: Arc::new(BTreeSet::new()), + } + } + + fn state() -> AppState { + let metadata = MockMetadataStore::new().with_row(AccountMetadata { + account_id: ACCOUNT.into(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec!["0xs1".into()], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + created_at: "2026-10-15T00:00:00Z".into(), + updated_at: "2026-10-15T00:00:00Z".into(), + has_pending_candidate: false, + paused_at: None, + paused_reason: None, + released_at: None, + }); + let mut state = create_test_app_state_with_mocks( + Arc::new(MockStorageBackend::new()), + Arc::new(MockNetworkClient::new()), + Arc::new(metadata), + ); + let hooks = [HookName::BeforeTransactionApproved]; + let mut optional = instance("optional", &hooks, OnError::Deny, Arc::new(RecipientPolicy)); + optional.config.scope = Scope::Assigned; + let mut secret = instance("vendor", &hooks, OnError::Deny, Arc::new(RecipientPolicy)); + secret.config.file_managed_params = true; + secret.config.operator_can_disable = false; + state.modules = Some(pipeline(vec![ + instance_with_params( + "blocklist", + &hooks, + Arc::new(RecipientPolicy), + json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + ), + optional, + secret, + ])); + state + } + + /// A catalog that changes an instance's `scope` leaves rows evaluation no longer reads: they + /// show as orphaned in the account view and count in the orphaned-rows report. + #[tokio::test] + async fn rows_left_by_a_scope_change_are_reported_as_orphaned() { + let store: Arc = + Arc::new(super::super::store::FsModuleStore::in_memory()); + let hooks = [HookName::BeforeTransactionApproved]; + let mut state = state(); + state.modules = Some(Arc::new(ModulePipeline::from_instances_with_store( + vec![instance( + "caps", + &hooks, + OnError::Deny, + Arc::new(RecipientPolicy), + )], + store.clone(), + ))); + set_layer( + &state, + &operator(), + ACCOUNT, + "caps", + Some(json!({ "denylist": ["0x000000000000000000000000000aaa"] })), + "OP-1", + None, + ) + .await + .unwrap(); + + let mut now_assigned = instance("caps", &hooks, OnError::Deny, Arc::new(RecipientPolicy)); + now_assigned.config.scope = Scope::Assigned; + let pipeline = Arc::new(ModulePipeline::from_instances_with_store( + vec![now_assigned], + store, + )); + state.modules = Some(pipeline.clone()); + let view = account_view(&state, ACCOUNT).await.unwrap(); + let layer = view + .modules + .iter() + .find(|entry| entry.module_id == "caps") + .expect("the left-over layer is shown"); + assert!(layer.orphaned, "{layer:?}"); + assert_eq!(layer.scope, "assigned"); + assert_eq!(pipeline.report_stored_assignments().await.unwrap().1, 1); + } + + /// One module being down must not freeze every assignment that keeps it: an entry stored + /// unchanged is not sent to the module again, and a change it cannot validate is refused + /// as unavailable, not as invalid params. + #[tokio::test] + async fn an_assignment_keeping_a_down_module_unchanged_can_still_be_edited() { + let vendor = crate::modules::testing::Outage::new(false); + let mut down = instance( + "vendor-assigned", + &[HookName::BeforeTransactionApproved], + OnError::Deny, + vendor.clone(), + ); + down.config.scope = Scope::Assigned; + let mut optional = instance( + "optional", + &[HookName::BeforeTransactionApproved], + OnError::Deny, + Arc::new(RecipientPolicy), + ); + optional.config.scope = Scope::Assigned; + let mut state = state(); + state.modules = Some(pipeline(vec![down, optional])); + let operator = operator(); + let kept = Assigned { + module_id: "vendor-assigned".into(), + params: json!({ "tier": 1 }), + }; + set_assignment(&state, &operator, ACCOUNT, vec![kept.clone()], "OP-1", None) + .await + .unwrap(); + vendor.set_down(true); + + let added = Assigned { + module_id: "optional".into(), + params: json!({}), + }; + let edited = set_assignment( + &state, + &operator, + ACCOUNT, + vec![kept.clone(), added], + "OP-2", + None, + ) + .await; + assert!(edited.is_ok(), "{edited:?}"); + + let changed = Assigned { + module_id: "vendor-assigned".into(), + params: json!({ "tier": 2 }), + }; + let refused = set_assignment(&state, &operator, ACCOUNT, vec![changed], "OP-3", None).await; + assert!( + matches!( + refused, + Err(GuardianError::ModuleUnavailable { module: Some(ref module) }) if module == "vendor-assigned" + ), + "{refused:?}" + ); + } + + #[tokio::test] + async fn operator_writes_store_the_shape_the_module_normalized() { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.normalized = Some(json!({ "new_name": 5 })); + let mut state = state(); + state.modules = Some(pipeline(vec![instance( + "migrating", + &[HookName::BeforeTransactionApproved], + OnError::Deny, + Arc::new(stub), + )])); + let view = set_global( + &state, + &operator(), + "migrating", + json!({ "old_name": 5 }), + "OP-93", + None, + ) + .await + .unwrap(); + assert_eq!(view.params, json!({ "new_name": 5 })); + let view = set_layer( + &state, + &operator(), + ACCOUNT, + "migrating", + Some(json!({ "old_name": 1 })), + "OP-94", + None, + ) + .await + .unwrap(); + assert_eq!( + view.modules[0].account_layer, + Some(json!({ "new_name": 5 })) + ); + } + + /// `state()`'s instances (50 ms each; `blocklist` and `vendor` on every account) under a + /// 120 ms budget: 100 ms before any account write. + fn tight_budget(state: &mut AppState) { + let instances = state.modules.as_ref().unwrap().instances().to_vec(); + state.modules = Some(Arc::new( + ModulePipeline::from_instances(instances).with_limits(crate::modules::limits::Limits { + budget: std::time::Duration::from_millis(120), + ..Default::default() + }), + )); + } + + #[tokio::test] + async fn views_report_real_scopes_orphaned_rows_and_undeclared_instances() { + let mut state = state(); + let store = state.modules.as_ref().unwrap().store_handle(); + let mut instances = state.modules.as_ref().unwrap().instances().to_vec(); + let mut screening = instance( + "screening", + &[HookName::BeforeTransactionApproved], + OnError::Deny, + Arc::new(RecipientPolicy), + ); + screening.config.scope = Scope::Default; + instances.push(screening); + store + .seed_instance( + "retired", + true, + &json!({ "old": true }), + &json!({ "old": true }), + "t0", + ) + .await + .unwrap(); + store + .set_assignment( + ACCOUNT, + vec![ + Assigned { + module_id: "screening".into(), + params: json!({}), + }, + Assigned { + module_id: "retired".into(), + params: json!({}), + }, + ], + &Change { + operator: "0xop", + reason: "setup", + at: "t1".into(), + expected_version: None, + }, + ) + .await + .unwrap(); + state.modules = Some(Arc::new(ModulePipeline::from_instances_with_store( + instances, store, + ))); + + let account = account_view(&state, ACCOUNT).await.unwrap(); + let entry = |id: &str| { + account + .modules + .iter() + .find(|entry| entry.module_id == id) + .unwrap() + .clone() + }; + assert_eq!(entry("screening").scope, "default"); + assert!(!entry("screening").orphaned); + assert!(entry("retired").orphaned); + assert!(!entry("retired").enabled); + + let catalog = catalog_view(&state).await.unwrap(); + assert_eq!(catalog.undeclared.len(), 1); + assert_eq!(catalog.undeclared[0].module_id, "retired"); + + let after = set_assignment(&state, &operator(), ACCOUNT, Vec::new(), "OP-9", None) + .await + .unwrap(); + let kept: Vec<_> = after + .modules + .iter() + .filter(|entry| entry.orphaned) + .map(|entry| entry.module_id.as_str()) + .collect(); + assert_eq!(kept, ["retired"], "an assignment write keeps orphaned rows"); + } + + #[tokio::test] + async fn the_catalog_view_shows_each_instance_circuit_on_this_replica() { + let state = state(); + let pipeline = state.modules.as_ref().unwrap(); + for _ in 0..crate::modules::limits::Limits::default().breaker_failures { + pipeline.breakers().failed("blocklist"); + } + let view = catalog_view(&state).await.unwrap(); + let circuit = |id: &str| { + view.modules + .iter() + .find(|module| module.module_id == id) + .unwrap() + .circuit + }; + assert_eq!(circuit("blocklist"), "open"); + assert_eq!(circuit("optional"), "closed"); + } + + #[tokio::test] + async fn an_account_write_that_could_exceed_the_budget_is_refused_and_stores_nothing() { + let mut state = state(); + tight_budget(&mut state); + let layer = set_layer( + &state, + &operator(), + ACCOUNT, + "blocklist", + Some(json!({ "denylist": ["0x000000000000000000000000000bbb"] })), + "OP-1", + None, + ) + .await; + assert!( + matches!(&layer, Err(GuardianError::ModuleWriteRefused(message)) if message.contains("budget")), + "{layer:?}" + ); + let assignment = set_assignment( + &state, + &operator(), + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }], + "OP-2", + None, + ) + .await; + assert!(matches!( + assignment, + Err(GuardianError::ModuleWriteRefused(_)) + )); + let pipeline = state.modules.as_ref().unwrap(); + assert!( + pipeline + .store() + .account_params(ACCOUNT) + .await + .unwrap() + .is_empty() + ); + } + + #[tokio::test] + async fn accounts_stored_over_the_budget_are_reported_at_startup() { + let mut state = state(); + set_assignment( + &state, + &operator(), + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }], + "OP-3", + None, + ) + .await + .unwrap(); + let store = state.modules.as_ref().unwrap().store_handle(); + let instances = state.modules.as_ref().unwrap().instances().to_vec(); + state.modules = Some(Arc::new( + ModulePipeline::from_instances_with_store(instances, store).with_limits( + crate::modules::limits::Limits { + budget: std::time::Duration::from_millis(120), + ..Default::default() + }, + ), + )); + assert_eq!( + state + .modules + .as_ref() + .unwrap() + .report_stored_assignments() + .await + .unwrap(), + (1, 0) + ); + + set_assignment(&state, &operator(), ACCOUNT, Vec::new(), "OP-2", None) + .await + .expect("removing the assignment brings the account back under the budget"); + let modules = state.modules.as_ref().unwrap(); + assert_eq!(modules.assignment_report(), (1, 0), "not recounted yet"); + modules.refresh_assignment_report().await; + assert_eq!( + modules.assignment_report(), + (0, 0), + "the recount follows the operator's fix, so the alarm clears" + ); + } + + #[tokio::test] + async fn an_account_registered_with_a_mixed_case_id_takes_layers_and_assignments() { + let mut state = state(); + state.metadata = Arc::new(MockMetadataStore::new().with_row(AccountMetadata { + account_id: "0xAcC".into(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec!["0xs1".into()], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + created_at: "2026-10-15T00:00:00Z".into(), + updated_at: "2026-10-15T00:00:00Z".into(), + has_pending_candidate: false, + paused_at: None, + paused_reason: None, + released_at: None, + })); + set_layer( + &state, + &operator(), + "0xAcC", + "blocklist", + Some(json!({ "denylist": ["0x000000000000000000000000000bbb"] })), + "OP-1", + None, + ) + .await + .expect("the id as registered is found"); + let rows = state + .modules + .as_ref() + .unwrap() + .store() + .account_params("0xacc") + .await + .unwrap(); + assert_eq!(rows.len(), 1, "stored under the key evaluation reads"); + assert!(matches!( + set_layer( + &state, + &operator(), + "0xBbB", + "blocklist", + None, + "OP-2", + None + ) + .await, + Err(GuardianError::AccountNotFound(_)) + )); + } + + #[tokio::test] + async fn a_layer_left_by_a_scope_change_can_be_deleted_before_the_module_is_assigned() { + let state = state(); + let store = state.modules.as_ref().unwrap().store_handle(); + store + .set_layer( + ACCOUNT, + "optional", + Some(json!({ "denylist": ["0x000000000000000000000000000bbb"] })), + &Change { + operator: "0xop", + reason: "written while optional applied to every account", + at: "t0".into(), + expected_version: None, + }, + ) + .await + .unwrap(); + let operator = operator(); + let assign = || { + set_assignment( + &state, + &operator, + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }], + "OP-1", + None, + ) + }; + assert!( + matches!(assign().await, Err(GuardianError::ModuleWriteRefused(message)) if message.contains("delete the layer first")) + ); + set_layer(&state, &operator, ACCOUNT, "optional", None, "OP-2", None) + .await + .expect("a stale layer can be deleted whatever the instance's scope is now"); + assign().await.expect("then the module can be assigned"); + } + + #[tokio::test] + async fn a_layer_is_refused_while_the_module_is_still_assigned_to_the_account() { + let mut state = state(); + let operator = operator(); + set_assignment( + &state, + &operator, + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }], + "OP-1", + None, + ) + .await + .unwrap(); + let hooks = [HookName::BeforeTransactionApproved]; + let store = state.modules.as_ref().unwrap().store_handle(); + state.modules = Some(Arc::new(ModulePipeline::from_instances_with_store( + vec![instance( + "optional", + &hooks, + OnError::Deny, + Arc::new(RecipientPolicy), + )], + store, + ))); + let layer = set_layer( + &state, + &operator, + ACCOUNT, + "optional", + Some(json!({})), + "OP-2", + None, + ) + .await; + assert!( + matches!(layer, Err(GuardianError::ModuleWriteRefused(message)) if message.contains("remove it from the account's assignment first")), + "the scope change left an assignment row for the module" + ); + } + + #[tokio::test] + async fn a_reason_longer_than_the_limit_is_refused() { + let state = state(); + let refused = set_layer( + &state, + &operator(), + ACCOUNT, + "blocklist", + Some(json!({})), + &"r".repeat(MAX_REASON_CHARS + 1), + None, + ) + .await; + assert!( + matches!(refused, Err(GuardianError::ModuleWriteRefused(message)) if message.contains("character limit")) + ); + } + + #[tokio::test] + async fn an_account_already_over_the_budget_can_be_brought_back_under_it() { + let mut state = state(); + let optional = || { + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }] + }; + set_assignment(&state, &operator(), ACCOUNT, optional(), "OP-1", None) + .await + .unwrap(); + let store = state.modules.as_ref().unwrap().store_handle(); + let instances = state.modules.as_ref().unwrap().instances().to_vec(); + state.modules = Some(Arc::new( + ModulePipeline::from_instances_with_store(instances, store).with_limits( + crate::modules::limits::Limits { + budget: std::time::Duration::from_millis(120), + ..Default::default() + }, + ), + )); + + let more = set_layer( + &state, + &operator(), + ACCOUNT, + "blocklist", + Some(json!({ "denylist": ["0x000000000000000000000000000bbb"] })), + "OP-2", + None, + ) + .await; + assert!( + matches!(&more, Err(GuardianError::ModuleWriteRefused(message)) if message.contains("budget")), + "a write that adds cost to an account over the budget: {more:?}" + ); + set_assignment(&state, &operator(), ACCOUNT, optional(), "OP-3", None) + .await + .expect("the same cost is not refused"); + set_assignment(&state, &operator(), ACCOUNT, Vec::new(), "OP-4", None) + .await + .expect("removing the assignment brings the account back under the budget"); + } + + #[tokio::test] + async fn global_and_account_writes_are_validated_recorded_and_visible() { + let state = state(); + let operator = operator(); + set_global( + &state, + &operator, + "blocklist", + json!({ "denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }), + "OP-90", + None, + ) + .await + .unwrap(); + let view = set_layer( + &state, + &operator, + ACCOUNT, + "blocklist", + Some(json!({ "denylist": ["0x000000000000000000000000000ccc"] })), + "OP-91", + None, + ) + .await + .unwrap(); + let entry = &view.modules[0]; + assert_eq!( + entry.global_params, + Some( + json!({ "denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }) + ) + ); + assert_eq!( + entry.account_layer, + Some(json!({ "denylist": ["0x000000000000000000000000000ccc"] })) + ); + + let history = history(&state, "blocklist", None, None) + .await + .unwrap() + .entries; + assert_eq!(history.len(), 2); + assert_eq!( + history[0].account_id.as_deref(), + Some(ACCOUNT), + "newest first" + ); + assert_eq!(history[1].reason, "OP-90"); + } + + #[tokio::test] + async fn a_write_made_against_a_version_that_moved_is_refused() { + let state = state(); + let operator = operator(); + set_global(&state, &operator, "blocklist", json!({}), "OP-1", None) + .await + .unwrap(); + let read = state + .modules + .as_ref() + .unwrap() + .store() + .instance_version() + .await + .unwrap(); + let against = |reason| Write { + reason, + expected_version: Some(read), + }; + set_global( + &state, + &operator, + "blocklist", + json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + against("first editor"), + None, + ) + .await + .expect("the version it read is current"); + let second = set_global( + &state, + &operator, + "blocklist", + json!({ "denylist": ["0x000000000000000000000000000bbb"] }), + against("second editor, same read"), + None, + ) + .await; + assert!( + matches!(second, Err(GuardianError::ModuleParamsStale)), + "{second:?}" + ); + + let account_read = set_layer( + &state, + &operator, + ACCOUNT, + "blocklist", + Some(json!({})), + "OP-2", + None, + ) + .await + .unwrap() + .account_params_version; + let stale_removal = set_layer( + &state, + &operator, + ACCOUNT, + "blocklist", + None, + Write { + reason: "removal from an older read", + expected_version: Some(account_read - 1), + }, + None, + ) + .await; + assert!(matches!( + stale_removal, + Err(GuardianError::ModuleParamsStale) + )); + let removal = set_layer( + &state, + &operator, + ACCOUNT, + "blocklist", + None, + Write { + reason: "removal from the current read", + expected_version: Some(account_read), + }, + None, + ) + .await; + assert!(removal.is_ok(), "{removal:?}"); + + let history = history(&state, "blocklist", None, None) + .await + .unwrap() + .entries; + assert!( + history + .iter() + .all(|entry| !entry.reason.starts_with("second editor") + && entry.reason != "removal from an older read"), + "a refused write leaves no history" + ); + } + + #[tokio::test] + async fn history_pages_newest_first_by_version() { + let state = state(); + for n in 0..3 { + set_global( + &state, + &operator(), + "blocklist", + json!({ "denylist": [format!("0x{n:030x}")] }), + &format!("OP-{n}"), + None, + ) + .await + .unwrap(); + } + let first = history(&state, "blocklist", None, Some(2)) + .await + .unwrap() + .entries; + assert_eq!( + first + .iter() + .map(|entry| entry.reason.as_str()) + .collect::>(), + ["OP-2", "OP-1"] + ); + let next = history(&state, "blocklist", Some(first[1].version), Some(2)) + .await + .unwrap() + .entries; + assert_eq!( + next.iter() + .map(|entry| entry.reason.as_str()) + .collect::>(), + ["OP-0"] + ); + assert!(history(&state, "blocklist", None, Some(0)).await.is_err()); + } + + #[tokio::test] + async fn params_over_the_size_cap_are_refused_before_the_module_is_called() { + let state = state(); + let huge = json!({ "denylist": vec!["0x".repeat(40); 4_000] }); + let refused = set_global(&state, &operator(), "blocklist", huge, "OP-9", None).await; + assert!( + matches!(&refused, Err(GuardianError::ModuleWriteRefused(message)) if message.contains("GUARDIAN_MODULE_PARAMS_MAX_BYTES")), + "{refused:?}" + ); + } + + #[tokio::test] + async fn invalid_writes_are_refused() { + let state = state(); + let operator = operator(); + let cases = [ + set_global( + &state, + &operator, + "blocklist", + json!({ "unknown": 1 }), + "r", + None, + ) + .await + .err(), + set_global( + &state, + &operator, + "blocklist", + json!({ "k": { "$secret": "x" } }), + "r", + None, + ) + .await + .err(), + set_global(&state, &operator, "blocklist", json!({}), " ", None) + .await + .err(), + set_global(&state, &operator, "vendor", json!({}), "r", None) + .await + .err(), + set_layer( + &state, + &operator, + ACCOUNT, + "optional", + Some(json!({})), + "r", + None, + ) + .await + .err(), + set_layer( + &state, + &operator, + "0xmissing", + "blocklist", + Some(json!({})), + "r", + None, + ) + .await + .err(), + set_assignment( + &state, + &operator, + ACCOUNT, + vec![Assigned { + module_id: "blocklist".into(), + params: json!({}), + }], + "r", + None, + ) + .await + .err(), + ]; + for (index, case) in cases.into_iter().enumerate() { + assert!(case.is_some(), "case {index} should be refused"); + } + assert!(matches!( + set_global(&state, &operator, "nope", json!({}), "r", None).await, + Err(GuardianError::ModuleNotFound { .. }) + )); + } + + #[tokio::test] + async fn disable_and_enable_follow_the_catalog_rules() { + let state = state(); + let operator = operator(); + let pipeline = state.modules.as_deref().unwrap(); + pipeline + .store() + .seed_instance( + "blocklist", + true, + &json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + &json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + "t0", + ) + .await + .unwrap(); + + let view = disable(&state, &operator, "blocklist", "faulty vendor", None) + .await + .unwrap(); + assert!(!view.enabled); + assert!(view.enabled_drift); + let view = enable(&state, &operator, "blocklist", "vendor fixed", None) + .await + .unwrap(); + assert!(view.enabled); + let history = history(&state, "blocklist", None, None) + .await + .unwrap() + .entries; + assert_eq!(history[0].new, json!({ "enabled": true }), "newest first"); + } + + #[tokio::test] + async fn an_instance_the_catalog_protects_cannot_be_disabled() { + let state = state(); + let pipeline = state.modules.as_deref().unwrap(); + assert!(pipeline.instance("vendor").is_some()); + let result = disable(&state, &operator(), "protected", "r", None).await; + assert!(matches!(result, Err(GuardianError::ModuleNotFound { .. }))); + let result = disable(&state, &operator(), "vendor", "r", None).await; + assert!(matches!( + result, + Err(GuardianError::ModuleNotDisableable { .. }) + )); + } + + #[tokio::test] + async fn optional_modules_are_assigned_per_account() { + let state = state(); + let view = set_assignment( + &state, + &operator(), + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({ "denylist": ["0x000000000000000000000000000eee"] }), + }], + "customer request", + None, + ) + .await + .unwrap(); + assert!( + view.modules + .iter() + .any(|m| m.module_id == "optional" && m.params.is_some()) + ); + } +} diff --git a/crates/server/src/modules/breaker.rs b/crates/server/src/modules/breaker.rs new file mode 100644 index 000000000..7d6b32159 --- /dev/null +++ b/crates/server/src/modules/breaker.rs @@ -0,0 +1,261 @@ +//! Per-instance circuit breakers and the `Describe` health probe. Breaker state is per replica and +//! in memory; nothing about it is stored. + +use std::collections::HashMap; +use std::sync::Mutex; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum CircuitState { + Closed, + Open, + HalfOpen, +} + +impl CircuitState { + pub fn as_str(self) -> &'static str { + match self { + CircuitState::Closed => "closed", + CircuitState::Open => "open", + CircuitState::HalfOpen => "half_open", + } + } +} + +#[derive(Debug, Clone, Copy)] +struct Breaker { + state: CircuitState, + consecutive_failures: u32, + /// A half-open breaker's one trial call is out and has not reported back. + trial_in_flight: bool, +} + +impl Default for Breaker { + fn default() -> Self { + Self { + state: CircuitState::Closed, + consecutive_failures: 0, + trial_in_flight: false, + } + } +} + +/// Who is asking to call a module. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Caller { + /// A request that leads to a signature or a stored proposal. + Request, + /// A policy check: it neither tests a recovering module nor changes a breaker. + DryRun, +} + +/// One breaker per instance id. A closed breaker opens after `threshold` consecutive failures; an +/// open one skips the module until a successful probe moves it to half-open, where one real call +/// at a time is let through: it closes the breaker on an answer or opens it again on a failure. +pub struct Breakers { + threshold: u32, + by_instance: Mutex>, +} + +impl Breakers { + pub fn new(threshold: u32) -> Self { + Self { + threshold: threshold.max(1), + by_instance: Mutex::default(), + } + } + + pub fn state(&self, instance: &str) -> CircuitState { + self.by_instance + .lock() + .ok() + .and_then(|breakers| breakers.get(instance).map(|breaker| breaker.state)) + .unwrap_or(CircuitState::Closed) + } + + /// Whether the module may be called now; when not, the instance's `on_error` applies at + /// once instead. A half-open breaker admits one request at a time as its trial, and a caller + /// admitted that way must report back with [`Self::answered`] or [`Self::failed`]. + pub fn admit(&self, instance: &str, caller: Caller) -> bool { + let Ok(mut breakers) = self.by_instance.lock() else { + return false; + }; + let Some(breaker) = breakers.get_mut(instance) else { + return true; + }; + match (breaker.state, caller) { + (CircuitState::Closed, _) => true, + (CircuitState::Open, _) | (CircuitState::HalfOpen, Caller::DryRun) => false, + (CircuitState::HalfOpen, Caller::Request) => { + !std::mem::replace(&mut breaker.trial_in_flight, true) + } + } + } + + /// The module answered, allow or deny: a deny is an answer, not a failure. A closed breaker's failure count resets and a half-open one closes + /// (its trial answered). An open breaker stays open: the answer is to a call admitted before + /// it opened, or before a probe found the module unusable, and says nothing a probe has not + /// decided since, so only a passing probe and its trial close it. + pub fn answered(&self, instance: &str) { + self.update(instance, |breaker| match breaker.state { + CircuitState::Closed | CircuitState::HalfOpen => *breaker = Breaker::default(), + CircuitState::Open => {} + }); + } + + /// The module timed out, failed to respond or returned a malformed decision. + pub fn failed(&self, instance: &str) { + let threshold = self.threshold; + self.update(instance, |breaker| match breaker.state { + CircuitState::Closed => { + breaker.consecutive_failures = breaker.consecutive_failures.saturating_add(1); + if breaker.consecutive_failures >= threshold { + breaker.state = CircuitState::Open; + } + } + CircuitState::HalfOpen | CircuitState::Open => { + breaker.state = CircuitState::Open; + breaker.trial_in_flight = false; + } + }); + } + + /// Opens the breaker at once, whatever the module answered before, and keeps it open until + /// a probe passes: for a module that did not answer its startup checks, and for one a + /// health probe finds answering with a protocol version, a required capability, a hook set + /// or params this Guardian cannot work with. Its decisions are not trusted meanwhile. + pub fn hold_open(&self, instance: &str) { + self.update(instance, |breaker| { + breaker.state = CircuitState::Open; + breaker.trial_in_flight = false; + }); + } + + /// A health probe succeeded: an open breaker lets the next real call through, and a + /// half-open one whose trial never reported back (its request was dropped) lets another. + pub fn probe_succeeded(&self, instance: &str) { + self.update(instance, |breaker| match breaker.state { + CircuitState::Open => breaker.state = CircuitState::HalfOpen, + CircuitState::HalfOpen => breaker.trial_in_flight = false, + CircuitState::Closed => {} + }); + } + + /// Applies `change` and reports a transition while still holding the lock, so concurrent + /// transitions reach the gauge and the log in the order they happened. + fn update(&self, instance: &str, change: impl FnOnce(&mut Breaker)) { + let Ok(mut breakers) = self.by_instance.lock() else { + return; + }; + let breaker = breakers.entry(instance.to_string()).or_default(); + let previous = breaker.state; + change(breaker); + let current = breaker.state; + if previous != current { + super::metrics::circuit_open(instance, current == CircuitState::Open); + tracing::warn!( + module = instance, + from = previous.as_str(), + to = current.as_str(), + "Policy module circuit changed" + ); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn consecutive_failures_open_the_breaker_and_an_answer_resets_the_count() { + let breakers = Breakers::new(3); + breakers.failed("m"); + breakers.failed("m"); + breakers.answered("m"); + breakers.failed("m"); + breakers.failed("m"); + assert!( + breakers.admit("m", Caller::Request), + "an answer reset the count" + ); + breakers.failed("m"); + assert_eq!(breakers.state("m"), CircuitState::Open); + assert!(!breakers.admit("m", Caller::Request)); + } + + #[test] + fn a_late_answer_does_not_close_an_open_breaker() { + let breakers = Breakers::new(5); + assert!(breakers.admit("m", Caller::Request)); + breakers.hold_open("m"); + breakers.answered("m"); + assert_eq!( + breakers.state("m"), + CircuitState::Open, + "an answer to a call admitted before the breaker opened" + ); + breakers.probe_succeeded("m"); + assert!(breakers.admit("m", Caller::Request)); + breakers.answered("m"); + assert_eq!( + breakers.state("m"), + CircuitState::Closed, + "the trial answered" + ); + } + + #[test] + fn a_half_open_breaker_admits_one_trial_at_a_time_and_no_dry_run() { + let breakers = Breakers::new(1); + breakers.failed("m"); + breakers.probe_succeeded("m"); + assert!(!breakers.admit("m", Caller::DryRun)); + assert!(breakers.admit("m", Caller::Request)); + assert!( + !breakers.admit("m", Caller::Request), + "the trial is still out" + ); + breakers.probe_succeeded("m"); + assert!( + breakers.admit("m", Caller::Request), + "a later probe replaces a trial that never reported back" + ); + breakers.answered("m"); + assert!(breakers.admit("m", Caller::Request)); + assert!(breakers.admit("m", Caller::DryRun)); + } + + #[test] + fn a_probe_half_opens_and_the_next_call_decides() { + let breakers = Breakers::new(1); + breakers.failed("m"); + breakers.probe_succeeded("m"); + assert_eq!(breakers.state("m"), CircuitState::HalfOpen); + assert!(breakers.admit("m", Caller::Request)); + breakers.failed("m"); + assert_eq!(breakers.state("m"), CircuitState::Open); + breakers.probe_succeeded("m"); + breakers.answered("m"); + assert_eq!(breakers.state("m"), CircuitState::Closed); + } + + #[test] + fn an_incompatible_probe_opens_a_closed_breaker_until_a_probe_passes() { + let breakers = Breakers::new(5); + breakers.hold_open("m"); + assert_eq!(breakers.state("m"), CircuitState::Open); + assert!(!breakers.admit("m", Caller::Request)); + breakers.probe_succeeded("m"); + assert!(breakers.admit("m", Caller::Request)); + } + + #[test] + fn a_probe_does_not_touch_a_closed_breaker_and_instances_are_independent() { + let breakers = Breakers::new(1); + breakers.probe_succeeded("a"); + assert_eq!(breakers.state("a"), CircuitState::Closed); + breakers.failed("a"); + assert!(!breakers.admit("a", Caller::Request)); + assert!(breakers.admit("b", Caller::Request)); + } +} diff --git a/crates/server/src/modules/catalog.rs b/crates/server/src/modules/catalog.rs new file mode 100644 index 000000000..f306506b7 --- /dev/null +++ b/crates/server/src/modules/catalog.rs @@ -0,0 +1,862 @@ +//! The module catalog: instances declared in the file at `GUARDIAN_MODULES_CONFIG`. + +use std::collections::{BTreeMap, BTreeSet, HashSet}; +use std::path::{Path, PathBuf}; +use std::time::Duration; + +use guardian_module_sdk::Hook; +use serde::Deserialize; +use sha2::{Digest, Sha256}; + +pub const CONFIG_ENV: &str = "GUARDIAN_MODULES_CONFIG"; +const TIMEOUT_MAX_MS: u64 = 1000; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Scope { + /// Every account, always; an account layer can only add restrictions. + All, + /// Copied into an account's assignment when it first registers; replaceable per account. + Default, + /// Only accounts an operator assigns it to. + Assigned, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum OnError { + #[default] + Deny, + Allow, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum HookName { + BeforeTransactionApproved, + BeforeProposalCreated, + BeforeAccountRegistered, +} + +impl HookName { + pub const GATES: [HookName; 3] = [ + HookName::BeforeTransactionApproved, + HookName::BeforeProposalCreated, + HookName::BeforeAccountRegistered, + ]; + + /// The catalog spelling, for example `before_transaction_approved`. + pub fn as_str(self) -> &'static str { + match self { + HookName::BeforeTransactionApproved => "before_transaction_approved", + HookName::BeforeProposalCreated => "before_proposal_created", + HookName::BeforeAccountRegistered => "before_account_registered", + } + } + + pub fn proto(self) -> Hook { + match self { + HookName::BeforeTransactionApproved => Hook::BeforeTransactionApproved, + HookName::BeforeProposalCreated => Hook::BeforeProposalCreated, + HookName::BeforeAccountRegistered => Hook::BeforeAccountRegistered, + } + } +} + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct AuthEntry { + token_secret: String, +} + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct TlsEntry { + ca_file: Option, + client_cert_secret: Option, + client_key_secret: Option, +} + +/// The secrets an instance names, resolved through the secrets backend before it is created. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct SecretRefs { + pub token: Option, + pub tls: Option, + /// Names of the `$secret` references in the catalog params of an in-process instance. + pub params: BTreeSet, +} + +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct TlsRefs { + pub ca_file: Option, + pub client_cert: Option, + pub client_key: Option, +} + +impl SecretRefs { + pub fn is_empty(&self) -> bool { + self.token.is_none() && self.tls.is_none() && self.params.is_empty() + } + + pub fn names_secrets(&self) -> bool { + self.token.is_some() + || !self.params.is_empty() + || self + .tls + .as_ref() + .is_some_and(|tls| tls.client_cert.is_some()) + } +} + +/// What an instance's [`SecretRefs`] resolved to. +#[derive(Debug, Clone, Default)] +pub struct Credentials { + pub auth_token: Option, + pub tls: Option, + pub params: BTreeMap, +} + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct InstanceEntry { + id: String, + kind: String, + endpoint: Option, + scope: Scope, + hooks: Vec, + timeout_ms: u64, + #[serde(default)] + on_error: OnError, + #[serde(default = "enabled_default")] + enabled: bool, + #[serde(default)] + operator_can_disable: bool, + #[serde(default)] + disclosure: Disclosure, + description: Option, + #[serde(default)] + client_reason: ClientReason, + #[serde(default = "enabled_default")] + dry_run: bool, + auth: Option, + tls: Option, + #[serde(default)] + params: Option, +} + +fn enabled_default() -> bool { + true +} + +/// What an account's cosigners may learn about an instance (RFC 0002 section 2.7). +#[derive( + Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, serde::Serialize, utoipa::ToSchema, +)] +#[serde(rename_all = "snake_case")] +pub enum Disclosure { + #[default] + None, + Summary, + Params, +} + +/// How a denial from an instance reaches the client (RFC 0002 section 4.1). +#[derive( + Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, serde::Serialize, utoipa::ToSchema, +)] +#[serde(rename_all = "snake_case")] +pub enum ClientReason { + #[default] + Full, + Generic, +} + +const DESCRIPTION_MAX_CHARS: usize = 500; +const INSTANCE_ID_MAX_CHARS: usize = 64; + +/// An instance id is a metric label, a log field and a path segment of the operator routes. +fn valid_instance_id(id: &str) -> bool { + (1..=INSTANCE_ID_MAX_CHARS).contains(&id.len()) + && id + .bytes() + .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_' || b == b'-') +} + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct CatalogFile { + #[serde(default, rename = "module")] + modules: Vec, +} + +#[derive(Debug, Clone)] +pub struct InstanceConfig { + pub id: String, + pub kind: String, + pub endpoint: Option, + pub scope: Scope, + pub hooks: Vec, + pub timeout: Duration, + pub on_error: OnError, + /// The flag in force: the stored runtime flag once the instance has been seeded. + pub enabled: bool, + /// The catalog's `enabled`, a seed only; kept to report drift. + pub catalog_enabled: bool, + pub operator_can_disable: bool, + pub disclosure: Disclosure, + pub description: Option, + pub client_reason: ClientReason, + /// Whether the dry-run check may call the instance. + pub dry_run: bool, + pub secrets: SecretRefs, + /// What `secrets` resolved to, or why they did not; an instance is created only from a + /// resolution, so a missing secret fails it like any other creation error. + pub credentials: Result, + /// Seed for the instance's global params; operator-managed after the first start. + pub params: serde_json::Value, + /// Params holding secret references stay file-managed: the operator API cannot change them. + pub file_managed_params: bool, +} + +#[derive(Debug, Clone)] +pub struct Catalog { + pub instances: Vec, + pub hash: String, +} + +fn json_object(value: Option, what: &str) -> Result { + let value = match value { + Some(value) => serde_json::to_value(value).map_err(|e| format!("{what}: {e}"))?, + None => serde_json::Value::Object(Default::default()), + }; + if value.is_object() { + Ok(value) + } else { + Err(format!("{what} must be a table")) + } +} + +pub(crate) fn contains_secret_reference(value: &serde_json::Value) -> bool { + match value { + serde_json::Value::Object(map) => { + map.contains_key(SECRET_KEY) || map.values().any(contains_secret_reference) + } + serde_json::Value::Array(items) => items.iter().any(contains_secret_reference), + _ => false, + } +} + +const SECRET_KEY: &str = "$secret"; +const SECRET_NAME_MAX_CHARS: usize = 512; + +/// A secrets backend name: what AWS Secrets Manager accepts, which the file provider reads as a +/// path below its directory. +pub(crate) fn check_secret_name(name: &str) -> Result<(), String> { + let valid = (1..=SECRET_NAME_MAX_CHARS).contains(&name.len()) + && name + .bytes() + .all(|b| b.is_ascii_alphanumeric() || b"/_+=.@-".contains(&b)); + if valid { + Ok(()) + } else { + Err(format!( + "secret name {name:?} must be 1 to {SECRET_NAME_MAX_CHARS} characters of letters, digits and /_+=.@-" + )) + } +} + +/// Collects the names of the `$secret` references in `value`; a reference is an object whose +/// only key is `$secret`, with a secret name as its value. +fn secret_references( + value: &serde_json::Value, + names: &mut BTreeSet, +) -> Result<(), String> { + match value { + serde_json::Value::Object(map) => match map.get(SECRET_KEY) { + Some(serde_json::Value::String(name)) if map.len() == 1 => { + check_secret_name(name)?; + names.insert(name.clone()); + Ok(()) + } + Some(_) => Err(format!( + "a secret reference is {{ \"{SECRET_KEY}\" = \"\" }} and nothing else" + )), + None => map + .values() + .try_for_each(|value| secret_references(value, names)), + }, + serde_json::Value::Array(items) => items + .iter() + .try_for_each(|value| secret_references(value, names)), + _ => Ok(()), + } +} + +/// How the Guardian reaches a remote module. `grpc://` is TLS; plain text is the explicit +/// `grpc+insecure://` scheme and only for a loopback host. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Transport { + Tls, + PlaintextLoopback, +} + +impl Transport { + pub const TLS_SCHEME: &str = "grpc://"; + pub const PLAINTEXT_SCHEME: &str = "grpc+insecure://"; + + pub fn of(endpoint: &str, has_tls_settings: bool) -> Result { + if let Some(rest) = endpoint.strip_prefix(Self::PLAINTEXT_SCHEME) { + if has_tls_settings { + return Err("tls settings need a grpc:// endpoint".into()); + } + let uri: tonic::transport::Uri = format!("http://{rest}") + .parse() + .map_err(|e| format!("invalid endpoint: {e}"))?; + let host = uri.host().unwrap_or_default(); + let loopback = host.eq_ignore_ascii_case("localhost") + || host + .trim_start_matches('[') + .trim_end_matches(']') + .parse::() + .is_ok_and(|ip| ip.is_loopback()); + if !loopback { + return Err(format!( + "plain text is only allowed to a loopback host, not {host}; use grpc://" + )); + } + Ok(Self::PlaintextLoopback) + } else if endpoint.starts_with(Self::TLS_SCHEME) { + Ok(Self::Tls) + } else { + Err("endpoint must start with grpc:// (TLS) or grpc+insecure:// (loopback)".into()) + } + } +} + +impl Catalog { + /// Prod-stage rules: remote modules use TLS and authenticate with a bearer token. + pub fn check_production(&self) -> Result<(), String> { + for config in &self.instances { + let Some(endpoint) = &config.endpoint else { + continue; + }; + if Transport::of(endpoint, config.secrets.tls.is_some())? != Transport::Tls { + return Err(format!( + "module {}: plain text is not allowed in the prod stage", + config.id + )); + } + if config.secrets.token.is_none() { + return Err(format!( + "module {}: auth is mandatory for remote modules in the prod stage", + config.id + )); + } + } + Ok(()) + } + + /// Prod-stage budget checks: for every hook, the timeouts of the instances every new account + /// receives (all but `assigned`, enabled or not, since enabling needs no further check) fit + /// in `budget`, and `budget` is below the execution reservation `lease`. + pub fn check_budget(&self, budget: Duration, lease: Duration) -> Result<(), String> { + if budget >= lease { + return Err(format!( + "the module evaluation budget ({} ms) must be below the execution reservation \ + lease ({} ms)", + budget.as_millis(), + lease.as_millis() + )); + } + for hook in HookName::GATES { + let total: Duration = self + .instances + .iter() + .filter(|config| config.scope != Scope::Assigned && config.hooks.contains(&hook)) + .map(|config| config.timeout) + .sum(); + if total > budget { + return Err(format!( + "the timeouts of the modules every account receives at {} add up to {} ms, \ + over the evaluation budget of {} ms", + hook.as_str(), + total.as_millis(), + budget.as_millis() + )); + } + } + Ok(()) + } + + pub fn load(path: &Path) -> Result { + let text = std::fs::read_to_string(path) + .map_err(|e| format!("cannot read module catalog {}: {e}", path.display()))?; + Self::parse(&text, path.parent()) + } + + pub fn parse(text: &str, base_dir: Option<&Path>) -> Result { + let file: CatalogFile = + toml::from_str(text).map_err(|e| format!("invalid module catalog: {e}"))?; + + let mut seen = HashSet::new(); + let mut instances = Vec::with_capacity(file.modules.len()); + for entry in file.modules { + let id = entry.id; + if !valid_instance_id(&id) { + return Err(format!( + "module {id:?}: an id is 1 to {INSTANCE_ID_MAX_CHARS} characters of a-z, 0-9, '_' or '-'" + )); + } + if !seen.insert(id.clone()) { + return Err(format!("module {id}: duplicate id")); + } + if entry.hooks.is_empty() { + return Err(format!("module {id}: hooks must not be empty")); + } + if !(1..=TIMEOUT_MAX_MS).contains(&entry.timeout_ms) { + return Err(format!( + "module {id}: timeout_ms must be between 1 and {TIMEOUT_MAX_MS}" + )); + } + let remote = entry.kind == "grpc"; + if remote != entry.endpoint.is_some() { + return Err(format!( + "module {id}: endpoint is required for kind grpc and only allowed for it" + )); + } + let description = entry + .description + .map(|text| text.trim().to_string()) + .filter(|text| !text.is_empty()); + if entry.disclosure != Disclosure::None && description.is_none() { + return Err(format!( + "module {id}: a description is required unless disclosure = \"none\"" + )); + } + if description + .as_ref() + .is_some_and(|text| text.chars().count() > DESCRIPTION_MAX_CHARS) + { + return Err(format!( + "module {id}: description is longer than {DESCRIPTION_MAX_CHARS} characters" + )); + } + if !remote && (entry.auth.is_some() || entry.tls.is_some()) { + return Err(format!( + "module {id}: auth and tls are only allowed for remote kinds" + )); + } + if let Some(endpoint) = &entry.endpoint { + Transport::of(endpoint, entry.tls.is_some()) + .map_err(|e| format!("module {id}: {e}"))?; + } + let params = json_object(entry.params, &format!("module {id} params"))?; + if remote && contains_secret_reference(¶ms) { + return Err(format!( + "module {id}: secret references are not allowed in remote module params" + )); + } + if entry.scope == Scope::Default && contains_secret_reference(¶ms) { + return Err(format!( + "module {id}: scope = \"default\" copies its params into each new account, and secret references cannot be stored per account; use scope \"all\" or \"assigned\"" + )); + } + if entry.disclosure == Disclosure::Params && contains_secret_reference(¶ms) { + return Err(format!( + "module {id}: disclosure = \"params\" would show cosigners the secret references in its params; use \"summary\" or \"none\"" + )); + } + let mut param_secrets = BTreeSet::new(); + secret_references(¶ms, &mut param_secrets) + .map_err(|e| format!("module {id} params: {e}"))?; + let token = entry + .auth + .map(|auth| check_secret_name(&auth.token_secret).map(|()| auth.token_secret)) + .transpose() + .map_err(|e| format!("module {id} auth: {e}"))?; + let tls = entry + .tls + .map(|tls| { + if tls.client_cert_secret.is_some() != tls.client_key_secret.is_some() { + return Err( + "client_cert_secret and client_key_secret go together".to_string() + ); + } + for name in [&tls.client_cert_secret, &tls.client_key_secret] + .into_iter() + .flatten() + { + check_secret_name(name)?; + } + Ok(TlsRefs { + ca_file: tls.ca_file.map(|path| match base_dir { + Some(dir) if path.is_relative() => dir.join(path), + _ => path, + }), + client_cert: tls.client_cert_secret, + client_key: tls.client_key_secret, + }) + }) + .transpose() + .map_err(|e| format!("module {id} tls: {e}"))?; + let secrets = SecretRefs { + token, + tls, + params: param_secrets, + }; + let credentials = if secrets.is_empty() { + Ok(Credentials::default()) + } else { + Err("secrets not resolved".to_string()) + }; + instances.push(InstanceConfig { + id, + kind: entry.kind, + endpoint: entry.endpoint, + scope: entry.scope, + hooks: entry.hooks, + timeout: Duration::from_millis(entry.timeout_ms), + on_error: entry.on_error, + enabled: entry.enabled, + catalog_enabled: entry.enabled, + operator_can_disable: entry.operator_can_disable, + disclosure: entry.disclosure, + description, + client_reason: entry.client_reason, + dry_run: entry.dry_run, + secrets, + credentials, + file_managed_params: contains_secret_reference(¶ms), + params, + }); + } + + Ok(Self { + instances, + hash: format!("0x{}", hex::encode(Sha256::digest(text.as_bytes()))), + }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn parse(text: &str) -> Result { + Catalog::parse(text, None) + } + + const VALID: &str = r#" +[[module]] +id = "caps" +kind = "spending-limit" +scope = "all" +hooks = ["before_transaction_approved", "before_proposal_created"] +timeout_ms = 20 +params = { max_per_transaction = { "0x0000000000000000000000000000aa" = "1000" } } + +[[module]] +id = "signers" +kind = "signer-policy" +scope = "assigned" +hooks = ["before_account_registered"] +timeout_ms = 20 +on_error = "allow" +"#; + + fn timed(instances: &[(&str, &str, u64)]) -> Catalog { + let text: String = instances + .iter() + .map(|(id, scope, timeout_ms)| { + format!( + "[[module]]\nid = \"{id}\"\nkind = \"spending-limit\"\nscope = \"{scope}\"\n\ + hooks = [\"before_transaction_approved\"]\ntimeout_ms = {timeout_ms}\n\n" + ) + }) + .collect(); + parse(&text).unwrap() + } + + #[test] + fn the_modules_every_account_receives_must_fit_in_the_budget() { + let budget = Duration::from_millis(1_000); + let lease = Duration::from_secs(60); + assert!( + timed(&[("a", "all", 500), ("b", "all", 500)]) + .check_budget(budget, lease) + .is_ok() + ); + let over = timed(&[("a", "all", 600), ("b", "all", 600)]) + .check_budget(budget, lease) + .unwrap_err(); + assert!(over.contains("before_transaction_approved"), "{over}"); + assert!( + timed(&[("a", "all", 600), ("b", "assigned", 600)]) + .check_budget(budget, lease) + .is_ok(), + "assigned instances are checked per account, not at startup" + ); + } + + #[test] + fn the_budget_must_be_below_the_execution_lease() { + let catalog = timed(&[("a", "all", 10)]); + assert!( + catalog + .check_budget(Duration::from_secs(30), Duration::from_secs(30)) + .is_err() + ); + assert!( + catalog + .check_budget(Duration::from_secs(1), Duration::from_secs(30)) + .is_ok() + ); + } + + #[test] + fn parses_instances() { + let catalog = parse(VALID).unwrap(); + assert_eq!(catalog.instances.len(), 2); + assert_eq!(catalog.instances[1].on_error, OnError::Allow); + assert!(!catalog.instances[0].file_managed_params); + assert!(catalog.hash.starts_with("0x")); + } + + #[test] + fn rejects_invalid_catalogs() { + let cases = [ + ( + "empty hooks", + VALID.replacen(r#"hooks = ["before_account_registered"]"#, "hooks = []", 1), + ), + ( + "unknown hook", + VALID.replacen( + "before_account_registered", + "after_transaction_committed", + 1, + ), + ), + ( + "timeout", + VALID.replacen("timeout_ms = 20", "timeout_ms = 5000", 1), + ), + ( + "per-account params in the file", + VALID.replacen( + r#"on_error = "allow""#, + "on_error = \"allow\"\naccount_params = { \"0x1\" = {} }", + 1, + ), + ), + ( + "duplicate id", + VALID.replacen(r#"id = "signers""#, r#"id = "caps""#, 1), + ), + ( + "grpc without endpoint", + VALID.replacen(r#"kind = "spending-limit""#, r#"kind = "grpc""#, 1), + ), + ( + "empty id", + VALID.replacen(r#"id = "caps""#, r#"id = """#, 1), + ), + ( + "id that is not a path segment", + VALID.replacen(r#"id = "caps""#, r#"id = "Caps/v2""#, 1), + ), + ( + "id over the length limit", + VALID.replacen(r#"id = "caps""#, &format!("id = \"{}\"", "a".repeat(65)), 1), + ), + ]; + for (name, text) in cases { + assert!(parse(&text).is_err(), "{name} should be rejected"); + } + } + + #[test] + fn default_instances_cannot_hold_secret_references() { + let catalog = |scope: &str| { + format!( + r#" +[[module]] +id = "vendor" +kind = "vendor-screening" +scope = "{scope}" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +params = {{ api_key = {{ "$secret" = "vendor-key" }} }} +"# + ) + }; + assert!(parse(&catalog("all")).is_ok()); + let refused = parse(&catalog("default")).unwrap_err(); + assert!(refused.contains("copies its params"), "{refused}"); + } + + #[test] + fn params_with_secret_references_are_file_managed() { + let text = VALID.replacen( + r#"params = { max_per_transaction = { "0x0000000000000000000000000000aa" = "1000" } }"#, + r#"params = { api_key = { "$secret" = "x" } }"#, + 1, + ); + assert!(parse(&text).unwrap().instances[0].file_managed_params); + } + + #[test] + fn credentials_are_secret_names_resolved_later() { + let text = remote( + "grpc://127.0.0.1:7443", + r#"auth = { token_secret = "guardian/modules/risk-token" } +tls = { ca_file = "ca.pem", client_cert_secret = "risk-cert", client_key_secret = "risk-key" }"#, + ); + let catalog = Catalog::parse(&text, Some(Path::new("/etc/guardian"))).unwrap(); + let config = &catalog.instances[0]; + assert_eq!( + config.secrets, + SecretRefs { + token: Some("guardian/modules/risk-token".into()), + tls: Some(TlsRefs { + ca_file: Some(PathBuf::from("/etc/guardian/ca.pem")), + client_cert: Some("risk-cert".into()), + client_key: Some("risk-key".into()), + }), + params: BTreeSet::new(), + } + ); + assert!(config.credentials.is_err()); + let invalid = remote( + "grpc://127.0.0.1:7443", + r#"auth = { token_secret = "../token file" }"#, + ); + assert!(parse(&invalid).unwrap_err().contains("secret name")); + } + + fn remote(endpoint: &str, extra: &str) -> String { + format!( + r#" +[[module]] +id = "remote" +kind = "grpc" +endpoint = "{endpoint}" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +{extra} +"# + ) + } + + #[test] + fn plain_text_is_only_for_loopback_hosts() { + for endpoint in [ + "grpc+insecure://127.0.0.1:7443", + "grpc+insecure://localhost:7443", + "grpc+insecure://[::1]:7443", + ] { + assert!(parse(&remote(endpoint, "")).is_ok(), "{endpoint}"); + } + for endpoint in [ + "grpc+insecure://risk.internal:7443", + "grpc+insecure://10.0.0.5:7443", + "http://127.0.0.1:7443", + ] { + assert!(parse(&remote(endpoint, "")).is_err(), "{endpoint}"); + } + assert!( + parse(&remote( + "grpc+insecure://127.0.0.1:7443", + r#"tls = { ca_file = "ca.pem" }"# + )) + .is_err() + ); + } + + #[test] + fn prod_requires_tls_and_a_token_for_remote_modules() { + let auth = r#"auth = { token_secret = "token" }"#; + let check = |endpoint: &str, extra: &str| { + parse(&remote(endpoint, extra)).unwrap().check_production() + }; + assert!(check("grpc://risk.internal:7443", auth).is_ok()); + assert!(check("grpc://risk.internal:7443", "").is_err()); + assert!(check("grpc+insecure://127.0.0.1:7443", auth).is_err()); + } + + #[test] + fn a_client_certificate_needs_its_key() { + let text = remote( + "grpc://risk.internal:7443", + r#"tls = { client_cert_secret = "cert" }"#, + ); + assert!(parse(&text).unwrap_err().contains("go together")); + } + + #[test] + fn disclosure_defaults_to_nothing_and_needs_a_description_to_open_up() { + let base = remote("grpc+insecure://127.0.0.1:7443", ""); + let module = &parse(&base).unwrap().instances[0]; + assert_eq!(module.disclosure, Disclosure::None); + assert_eq!(module.client_reason, ClientReason::Full); + assert!(module.dry_run); + + let without = remote( + "grpc+insecure://127.0.0.1:7443", + r#"disclosure = "summary""#, + ); + assert!( + parse(&without) + .unwrap_err() + .contains("description is required") + ); + + let with = remote( + "grpc+insecure://127.0.0.1:7443", + "disclosure = \"params\"\ndescription = \"At most 5 per transaction\"\nclient_reason = \"generic\"\ndry_run = false", + ); + let module = &parse(&with).unwrap().instances[0]; + assert_eq!(module.disclosure, Disclosure::Params); + assert_eq!( + module.description.as_deref(), + Some("At most 5 per transaction") + ); + assert_eq!(module.client_reason, ClientReason::Generic); + assert!(!module.dry_run); + + let long = remote( + "grpc+insecure://127.0.0.1:7443", + &format!( + "disclosure = \"summary\"\ndescription = \"{}\"", + "x".repeat(501) + ), + ); + assert!(parse(&long).unwrap_err().contains("longer than")); + } + + #[test] + fn params_holding_secret_references_cannot_be_disclosed() { + let catalog = |disclosure: &str| { + format!( + r#" +[[module]] +id = "vendor" +kind = "vendor-screening" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +disclosure = "{disclosure}" +description = "Vendor screening" +params = {{ api_key = {{ "$secret" = "vendor-key" }} }} +"# + ) + }; + assert!( + parse(&catalog("params")) + .unwrap_err() + .contains("secret references") + ); + assert!(parse(&catalog("summary")).is_ok()); + } +} diff --git a/crates/server/src/modules/check_limit.rs b/crates/server/src/modules/check_limit.rs new file mode 100644 index 000000000..92ee7370e --- /dev/null +++ b/crates/server/src/modules/check_limit.rs @@ -0,0 +1,127 @@ +//! The rate limit on dry-run proposal checks, per account and signer. Process-wide and +//! independent of the module catalog: a check rebuilds and verifies the account's state even +//! when no module is configured. + +use std::collections::HashMap; +use std::sync::OnceLock; + +use crate::error::GuardianError; + +/// Env var for how many dry-run checks one signer may make for one account per minute. +pub const CHECK_RATE_ENV: &str = "GUARDIAN_MODULE_CHECK_RATE_PER_MIN"; +const CHECK_RATE_DEFAULT: usize = 30; +const CHECK_WINDOW: std::time::Duration = std::time::Duration::from_secs(60); + +/// Per account and signer sliding window for dry-run checks, so the check cannot be used to +/// enumerate a denylist or a model's thresholds. Per replica. +pub struct CheckLimiter { + per_minute: usize, + calls: + std::sync::Mutex>>, +} + +fn check_rate(raw: Result) -> Result { + match raw { + Err(std::env::VarError::NotPresent) => Ok(CHECK_RATE_DEFAULT), + Ok(value) => value + .trim() + .parse::() + .ok() + .filter(|limit| *limit > 0) + .ok_or_else(|| format!("{CHECK_RATE_ENV} must be a positive integer, got {value:?}")), + Err(std::env::VarError::NotUnicode(_)) => { + Err(format!("{CHECK_RATE_ENV} must contain valid UTF-8")) + } + } +} + +impl CheckLimiter { + pub fn with_limit(per_minute: usize) -> Self { + Self { + per_minute, + calls: Default::default(), + } + } + + /// The limit from `GUARDIAN_MODULE_CHECK_RATE_PER_MIN`, the default when unset; a value + /// that is not a positive integer refuses startup. + fn from_env() -> Result { + check_rate(std::env::var(CHECK_RATE_ENV)).map(Self::with_limit) + } + + pub fn admit(&self, account_id: &str, signer: &str) -> Result<(), GuardianError> { + let now = std::time::Instant::now(); + let mut calls = self + .calls + .lock() + .map_err(|_| GuardianError::StorageError("check limiter poisoned".into()))?; + calls.retain(|_, window| { + window.retain(|at| now.duration_since(*at) < CHECK_WINDOW); + !window.is_empty() + }); + let window = calls + .entry((account_id.to_ascii_lowercase(), signer.to_ascii_lowercase())) + .or_default(); + if window.len() >= self.per_minute { + let retry_after = window + .front() + .map(|oldest| CHECK_WINDOW.saturating_sub(now.duration_since(*oldest))) + .unwrap_or(CHECK_WINDOW); + return Err(GuardianError::RateLimitExceeded { + retry_after_secs: u32::try_from(retry_after.as_secs().max(1)).unwrap_or(60), + scope: "proposal_check".into(), + }); + } + window.push_back(now); + Ok(()) + } +} + +static LIMITER: OnceLock = OnceLock::new(); + +/// Installs the limiter from `GUARDIAN_MODULE_CHECK_RATE_PER_MIN`; a malformed value fails +/// startup. Called once by the server builder. +pub fn init_from_env() -> Result<(), String> { + let limiter = CheckLimiter::from_env()?; + let _ = LIMITER.set(limiter); + Ok(()) +} + +/// Counts one check by `signer` for `account_id`, or refuses it with `rate_limit_exceeded`. +pub fn admit(account_id: &str, signer: &str) -> Result<(), GuardianError> { + LIMITER + .get_or_init(|| CheckLimiter::with_limit(CHECK_RATE_DEFAULT)) + .admit(account_id, signer) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn the_check_rate_is_a_positive_integer_or_startup_fails() { + use std::env::VarError; + assert_eq!( + check_rate(Err(VarError::NotPresent)), + Ok(CHECK_RATE_DEFAULT) + ); + assert_eq!(check_rate(Ok(" 12 ".into())), Ok(12)); + for bad in ["0", "-3", "thirty", "1.5", ""] { + assert!(check_rate(Ok(bad.into())).is_err(), "{bad:?}"); + } + } + + #[test] + fn dry_runs_are_limited_per_account_and_signer() { + let limiter = CheckLimiter::with_limit(3); + for _ in 0..3 { + limiter.admit("0xacc", "0xsigner").unwrap(); + } + assert!(matches!( + limiter.admit("0xacc", "0xsigner"), + Err(GuardianError::RateLimitExceeded { .. }) + )); + assert!(limiter.admit("0xacc", "0xother").is_ok()); + assert!(limiter.admit("0xother", "0xsigner").is_ok()); + } +} diff --git a/crates/server/src/modules/disclosure.rs b/crates/server/src/modules/disclosure.rs new file mode 100644 index 000000000..b5f10ae73 --- /dev/null +++ b/crates/server/src/modules/disclosure.rs @@ -0,0 +1,186 @@ +//! What an account's cosigners may learn about the policies that apply to them (RFC 0002 +//! section 2.7). + +use serde::{Deserialize, Serialize}; + +use super::catalog::{Disclosure, Scope}; +use super::pipeline::ModulePipeline; +use super::store::ParamsKind; +use crate::error::GuardianError; + +/// One policy as the account's cosigners see it. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct PolicyEntry { + pub module_id: String, + pub hooks: Vec, + pub description: String, + /// `disclosure = "params"`: the instance's global params, or the account's own params for + /// an assigned instance. + #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] + pub params: Option, + /// `disclosure = "params"` on a `scope = all` instance: this account's layer, when set. + #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] + pub account_layer: Option, +} + +impl ModulePipeline { + /// The enabled instances that apply to the account, in evaluation order, without those + /// whose catalog entry discloses nothing. + pub async fn disclosed(&self, account_id: &str) -> Result, GuardianError> { + let account_id = account_id.to_ascii_lowercase(); + let super::pipeline::Snapshot { + rows, account_rows, .. + } = self.snapshot(&account_id).await?; + let entry = |instance: &super::registry::Instance, + params: Option, + account_layer: Option| { + let config = &instance.config; + let show_params = config.disclosure == Disclosure::Params; + PolicyEntry { + module_id: config.id.clone(), + hooks: config + .hooks + .iter() + .map(|hook| hook.as_str().to_string()) + .collect(), + description: config.description.clone().unwrap_or_default(), + params: params.filter(|_| show_params), + account_layer: account_layer.filter(|_| show_params), + } + }; + let visible = |instance: &super::registry::Instance| { + instance.config.disclosure != Disclosure::None && Self::enabled_in(&rows, instance) + }; + let mut policies = Vec::new(); + for instance in self + .instances() + .iter() + .filter(|instance| instance.config.scope == Scope::All && visible(instance)) + { + let layer = account_rows + .iter() + .find(|row| row.kind == ParamsKind::Layer && row.module_id == instance.config.id) + .map(|row| row.params.clone()); + policies.push(entry( + instance, + Some(Self::global_params_in(&rows, instance)), + layer, + )); + } + for row in account_rows + .iter() + .filter(|row| row.kind == ParamsKind::Assignment) + { + if let Some(instance) = self + .instance(&row.module_id) + .filter(|instance| instance.config.scope != Scope::All && visible(instance)) + { + policies.push(entry(instance, Some(row.params.clone()), None)); + } + } + Ok(policies) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::*; + use crate::modules::catalog::HookName; + use crate::modules::store::{Assigned, Change}; + use crate::modules::testing::{StubModule, instance_with_params, pipeline}; + + const ACCOUNT: &str = "0xacc"; + + fn change() -> Change<'static> { + Change { + operator: "0xop", + reason: "test", + at: "2026-10-16T00:00:00Z".into(), + expected_version: None, + } + } + + #[tokio::test] + async fn only_disclosed_enabled_policies_are_listed_with_what_they_allow() { + let hooks = [HookName::BeforeTransactionApproved]; + let module = || StubModule::allowing() as std::sync::Arc; + let with = |id: &str, disclosure: Disclosure, scope: Scope| { + let mut instance = instance_with_params(id, &hooks, module(), json!({ "cap": id })); + instance.config.disclosure = disclosure; + instance.config.scope = scope; + if disclosure != Disclosure::None { + instance.config.description = Some(format!("{id} rule")); + } + instance + }; + let pipeline = pipeline(vec![ + with("caps", Disclosure::Params, Scope::All), + with("screening", Disclosure::None, Scope::All), + with("summary", Disclosure::Summary, Scope::All), + with("paused", Disclosure::Summary, Scope::All), + with("treasury", Disclosure::Params, Scope::Assigned), + ]); + let store = pipeline.store(); + for id in ["caps", "screening", "summary", "paused", "treasury"] { + store + .seed_instance( + id, + true, + &json!({ "cap": id }), + &json!({ "cap": id }), + "2026-10-16T00:00:00Z", + ) + .await + .unwrap(); + } + store.set_enabled("paused", false, &change()).await.unwrap(); + store + .set_layer( + ACCOUNT, + "caps", + Some(json!({ "cap": "tighter" })), + &change(), + ) + .await + .unwrap(); + store + .set_layer( + ACCOUNT, + "summary", + Some(json!({ "cap": "secret" })), + &change(), + ) + .await + .unwrap(); + store + .set_assignment( + ACCOUNT, + vec![Assigned { + module_id: "treasury".into(), + params: json!({ "cap": "own" }), + }], + &change(), + ) + .await + .unwrap(); + + let policies = pipeline.disclosed(ACCOUNT).await.unwrap(); + let ids: Vec<_> = policies.iter().map(|p| p.module_id.as_str()).collect(); + assert_eq!( + ids, + ["caps", "summary", "treasury"], + "none and disabled are absent" + ); + assert_eq!(policies[0].params, Some(json!({ "cap": "caps" }))); + assert_eq!(policies[0].account_layer, Some(json!({ "cap": "tighter" }))); + assert_eq!(policies[1].description, "summary rule"); + assert_eq!(policies[1].params, None, "summary shows no params"); + assert_eq!(policies[1].account_layer, None, "nor the account layer"); + assert_eq!(policies[2].params, Some(json!({ "cap": "own" }))); + assert_eq!(policies[2].hooks, ["before_transaction_approved"]); + } +} diff --git a/crates/server/src/modules/grpc_kind.rs b/crates/server/src/modules/grpc_kind.rs new file mode 100644 index 000000000..624ac69dc --- /dev/null +++ b/crates/server/src/modules/grpc_kind.rs @@ -0,0 +1,156 @@ +//! The `grpc` kind: a module running as its own service. + +use std::sync::Arc; + +use async_trait::async_trait; +use guardian_module_sdk::proto::guardian_module_client::GuardianModuleClient; +use guardian_module_sdk::secrecy::ExposeSecret; +use guardian_module_sdk::{ + Decision, DescribeRequest, HookRequest, Module, ModuleError, ModuleFactory, ModuleInfo, + ModuleInstanceConfig, ParamsVerdict, ValidateParamsRequest, +}; +use tonic::metadata::MetadataValue; +use tonic::transport::{Certificate, Channel, ClientTlsConfig, Endpoint, Identity}; + +use super::catalog::Transport; + +/// Server authentication against the instance's CA, or the system roots without one; the +/// client identity, when set, adds mutual TLS. +fn tls_config( + tls: Option<&guardian_module_sdk::ModuleTls>, + handshake_timeout: std::time::Duration, +) -> ClientTlsConfig { + let config = ClientTlsConfig::new().timeout(handshake_timeout); + let Some(tls) = tls else { + return config.with_native_roots(); + }; + let config = match &tls.ca_pem { + Some(ca) => config.ca_certificate(Certificate::from_pem(ca)), + None => config.with_native_roots(), + }; + match &tls.client_identity { + Some(identity) => config.identity(Identity::from_pem( + &identity.cert_pem, + identity.key_pem.expose_secret(), + )), + None => config, + } +} + +/// A module host that vanishes without closing the connection is noticed within this interval +/// plus the timeout, instead of when the kernel gives up retransmitting. +const KEEP_ALIVE_INTERVAL: std::time::Duration = std::time::Duration::from_secs(10); +const KEEP_ALIVE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5); + +pub struct GrpcFactory; + +impl ModuleFactory for GrpcFactory { + fn create(&self, instance: &ModuleInstanceConfig) -> Result, ModuleError> { + let endpoint = instance + .endpoint + .as_deref() + .ok_or_else(|| ModuleError::InvalidRequest("grpc module needs an endpoint".into()))?; + let invalid = |e: String| ModuleError::InvalidRequest(e); + let transport = Transport::of(endpoint, instance.tls.is_some()).map_err(invalid)?; + let endpoint = match transport { + Transport::Tls => { + let uri = endpoint.replacen(Transport::TLS_SCHEME, "https://", 1); + Endpoint::from_shared(uri) + .map_err(|e| invalid(format!("invalid endpoint: {e}")))? + .tls_config(tls_config(instance.tls.as_ref(), instance.timeout)) + .map_err(|e| invalid(format!("invalid tls settings: {e}")))? + } + Transport::PlaintextLoopback => { + let uri = endpoint.replacen(Transport::PLAINTEXT_SCHEME, "http://", 1); + Endpoint::from_shared(uri).map_err(|e| invalid(format!("invalid endpoint: {e}")))? + } + }; + let channel = endpoint + .connect_timeout(instance.timeout) + .timeout(instance.timeout) + .http2_keep_alive_interval(KEEP_ALIVE_INTERVAL) + .keep_alive_timeout(KEEP_ALIVE_TIMEOUT) + .keep_alive_while_idle(true) + .tcp_keepalive(Some(KEEP_ALIVE_INTERVAL)) + .connect_lazy(); + let authorization = instance + .auth_token + .as_ref() + .map(|token| { + MetadataValue::try_from(format!("Bearer {}", token.expose_secret())).map( + |mut value| { + value.set_sensitive(true); + value + }, + ) + }) + .transpose() + .map_err(|_| ModuleError::InvalidRequest("token is not a valid header value".into()))?; + Ok(Arc::new(GrpcModule { + client: GuardianModuleClient::new(channel), + instance_id: instance.id.clone(), + authorization, + })) + } +} + +struct GrpcModule { + client: GuardianModuleClient, + instance_id: String, + authorization: Option>, +} + +impl GrpcModule { + fn request(&self, message: T) -> tonic::Request { + let mut request = tonic::Request::new(message); + if let Some(value) = &self.authorization { + request + .metadata_mut() + .insert("authorization", value.clone()); + } + request + } +} + +fn module_error(status: tonic::Status) -> ModuleError { + match status.code() { + tonic::Code::Unavailable | tonic::Code::DeadlineExceeded | tonic::Code::Unknown => { + ModuleError::Unavailable(status.message().to_string()) + } + tonic::Code::InvalidArgument => ModuleError::InvalidRequest(status.message().to_string()), + _ => ModuleError::Internal(format!("{}: {}", status.code(), status.message())), + } +} + +#[async_trait] +impl Module for GrpcModule { + async fn describe(&self, guardian: &DescribeRequest) -> Result { + self.client + .clone() + .describe(self.request(guardian.clone())) + .await + .map(tonic::Response::into_inner) + .map_err(module_error) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + self.client + .clone() + .validate_params(self.request(ValidateParamsRequest { + params: params.to_vec(), + instance_id: self.instance_id.clone(), + })) + .await + .map(tonic::Response::into_inner) + .map_err(module_error) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + self.client + .clone() + .evaluate(self.request(request.clone())) + .await + .map(tonic::Response::into_inner) + .map_err(module_error) + } +} diff --git a/crates/server/src/modules/limits.rs b/crates/server/src/modules/limits.rs new file mode 100644 index 000000000..01f5255ec --- /dev/null +++ b/crates/server/src/modules/limits.rs @@ -0,0 +1,138 @@ +//! Bounds on policy module evaluation: the per-invocation time budget, the request size cap, and +//! the circuit breaker and health probe settings. + +use std::time::Duration; + +pub const BUDGET_ENV: &str = "GUARDIAN_MODULE_EVALUATION_BUDGET_MS"; +pub const REQUEST_MAX_BYTES_ENV: &str = "GUARDIAN_MODULE_REQUEST_MAX_BYTES"; +pub const BREAKER_FAILURES_ENV: &str = "GUARDIAN_MODULE_BREAKER_FAILURES"; +pub const PROBE_INTERVAL_ENV: &str = "GUARDIAN_MODULE_PROBE_INTERVAL_MS"; +pub const PARAMS_MAX_BYTES_ENV: &str = "GUARDIAN_MODULE_PARAMS_MAX_BYTES"; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Limits { + /// Time spent in module calls for one hook invocation; request assembly is not charged. + pub budget: Duration, + /// Largest encoded request sent to a module; a larger one is a module failure, not sent. + pub request_max_bytes: usize, + /// Consecutive failures that open an instance's breaker. + pub breaker_failures: u32, + /// Interval of the `Describe` health probe per instance. + pub probe_interval: Duration, + /// Largest params value one write may store, as compact JSON with sorted keys. + pub params_max_bytes: usize, +} + +impl Limits { + /// Refuses `params` larger than [`Self::params_max_bytes`]. + pub fn check_params_size(&self, params: &serde_json::Value) -> Result<(), String> { + let size = serde_json::to_vec(params).map_or(usize::MAX, |bytes| bytes.len()); + if size > self.params_max_bytes { + return Err(format!( + "params of {size} bytes exceed {PARAMS_MAX_BYTES_ENV} ({} bytes)", + self.params_max_bytes + )); + } + Ok(()) + } +} + +impl Default for Limits { + fn default() -> Self { + Self { + budget: Duration::from_millis(1_000), + request_max_bytes: guardian_module_sdk::DEFAULT_REQUEST_MAX_BYTES, + breaker_failures: 5, + probe_interval: Duration::from_millis(5_000), + params_max_bytes: 64 * 1024, + } + } +} + +impl Limits { + /// The limits from the environment, each defaulting when unset; a value that is not a + /// positive integer refuses startup. + pub fn from_env() -> Result { + Self::from_vars(|name| std::env::var(name)) + } + + fn from_vars(var: impl Fn(&str) -> Result) -> Result { + let defaults = Self::default(); + Ok(Self { + budget: Duration::from_millis( + positive(&var, BUDGET_ENV)? + .unwrap_or(u64::try_from(defaults.budget.as_millis()).unwrap_or(u64::MAX)), + ), + request_max_bytes: positive(&var, REQUEST_MAX_BYTES_ENV)? + .map(|bytes| usize::try_from(bytes).unwrap_or(usize::MAX)) + .unwrap_or(defaults.request_max_bytes), + breaker_failures: positive(&var, BREAKER_FAILURES_ENV)? + .map(|failures| u32::try_from(failures).unwrap_or(u32::MAX)) + .unwrap_or(defaults.breaker_failures), + probe_interval: positive(&var, PROBE_INTERVAL_ENV)? + .map(Duration::from_millis) + .unwrap_or(defaults.probe_interval), + params_max_bytes: positive(&var, PARAMS_MAX_BYTES_ENV)? + .map(|bytes| usize::try_from(bytes).unwrap_or(usize::MAX)) + .unwrap_or(defaults.params_max_bytes), + }) + } +} + +fn positive( + var: &impl Fn(&str) -> Result, + name: &str, +) -> Result, String> { + match var(name) { + Err(std::env::VarError::NotPresent) => Ok(None), + Ok(value) => value + .trim() + .parse::() + .ok() + .filter(|value| *value > 0) + .map(Some) + .ok_or_else(|| format!("{name} must be a positive integer, got {value:?}")), + Err(std::env::VarError::NotUnicode(_)) => Err(format!("{name} must contain valid UTF-8")), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn vars(set: &[(&str, &str)]) -> impl Fn(&str) -> Result { + let set: Vec<(String, String)> = set + .iter() + .map(|(name, value)| (name.to_string(), value.to_string())) + .collect(); + move |name| { + set.iter() + .find(|(set_name, _)| set_name == name) + .map(|(_, value)| value.clone()) + .ok_or(std::env::VarError::NotPresent) + } + } + + #[test] + fn unset_variables_take_the_defaults() { + assert_eq!(Limits::from_vars(vars(&[])).unwrap(), Limits::default()); + } + + #[test] + fn set_variables_override_and_invalid_ones_refuse_startup() { + let limits = Limits::from_vars(vars(&[ + (BUDGET_ENV, "250"), + (REQUEST_MAX_BYTES_ENV, "4096"), + (BREAKER_FAILURES_ENV, "3"), + (PROBE_INTERVAL_ENV, "1000"), + ])) + .unwrap(); + assert_eq!(limits.budget, Duration::from_millis(250)); + assert_eq!(limits.request_max_bytes, 4096); + assert_eq!(limits.breaker_failures, 3); + assert_eq!(limits.probe_interval, Duration::from_millis(1000)); + for bad in ["0", "-1", "soon"] { + assert!(Limits::from_vars(vars(&[(BUDGET_ENV, bad)])).is_err()); + } + } +} diff --git a/crates/server/src/modules/metrics.rs b/crates/server/src/modules/metrics.rs new file mode 100644 index 000000000..f11fe3489 --- /dev/null +++ b/crates/server/src/modules/metrics.rs @@ -0,0 +1,84 @@ +//! Policy module metrics; names and help text are declared in `crate::metrics::names`. + +use std::time::Duration; + +use crate::metrics::names; + +#[derive(Debug, Clone, Copy)] +pub enum Outcome { + Allow, + Deny, + Error, + /// Not called: open circuit, oversized request or spent budget. + Skipped, +} + +impl Outcome { + fn as_str(self) -> &'static str { + match self { + Outcome::Allow => "allow", + Outcome::Deny => "deny", + Outcome::Error => "error", + Outcome::Skipped => "skipped", + } + } +} + +pub fn evaluated(module: &str, outcome: Outcome, took: Duration) { + metrics::histogram!( + names::MODULE_EVALUATE_DURATION_SECONDS, + names::LABEL_MODULE => module.to_string(), + names::LABEL_OUTCOME => outcome.as_str() + ) + .record(took.as_secs_f64()); +} + +/// A request refused before the module was called, because it could not be built or exceeds +/// the size cap. +pub fn request_refused(module: &str, reason: &'static str) { + metrics::counter!( + names::MODULE_REQUEST_REFUSED_TOTAL, + names::LABEL_MODULE => module.to_string(), + names::LABEL_REASON => reason + ) + .increment(1); +} + +pub fn failed_open(module: &str) { + metrics::counter!(names::MODULE_FAIL_OPEN_TOTAL, names::LABEL_MODULE => module.to_string()) + .increment(1); +} + +fn flag(name: &'static str, module: &str, on: bool) { + metrics::gauge!(name, names::LABEL_MODULE => module.to_string()).set(if on { + 1.0 + } else { + 0.0 + }); +} + +pub fn up(module: &str, up: bool) { + flag(names::MODULE_UP, module, up); +} + +pub fn circuit_open(module: &str, open: bool) { + flag(names::MODULE_CIRCUIT_OPEN, module, open); +} + +pub fn enabled(module: &str, enabled: bool) { + flag(names::MODULE_ENABLED, module, enabled); +} + +pub fn config_drift(module: &str, drift: bool) { + flag(names::MODULE_CONFIG_DRIFT, module, drift); +} + +pub fn catalog(catalog_hash: &str) { + metrics::gauge!(names::MODULE_CATALOG_INFO, names::LABEL_CATALOG_HASH => catalog_hash.to_string()) + .set(1.0); +} + +pub fn stored_assignments(over_budget_accounts: usize, orphaned_rows: usize) { + metrics::gauge!(names::MODULE_OVER_BUDGET_ACCOUNTS).set(over_budget_accounts as f64); + metrics::gauge!(names::MODULE_ORPHANED_ASSIGNMENTS).set(orphaned_rows as f64); +} diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs new file mode 100644 index 000000000..39b9aa163 --- /dev/null +++ b/crates/server/src/modules/mod.rs @@ -0,0 +1,308 @@ +//! Policy modules: a hook pipeline the Guardian consults before approving. + +pub mod admin; +pub mod breaker; +pub mod catalog; +pub mod check_limit; +pub mod disclosure; +pub mod grpc_kind; +pub mod limits; +pub mod metrics; +pub mod pipeline; +#[cfg(feature = "postgres")] +pub mod postgres_store; +pub mod registry; +pub mod request; +pub mod secrets; +pub mod store; +#[cfg(test)] +pub mod testing; + +use std::path::PathBuf; +use std::sync::Arc; + +pub use catalog::{CONFIG_ENV, Catalog, HookName}; +pub use pipeline::ModulePipeline; +pub use registry::Registry; + +/// Directory of the filesystem module tables; defaults to `/modules`. +pub const STATE_ENV: &str = "GUARDIAN_MODULES_STATE"; + +fn filesystem_store(catalog_path: &std::path::Path) -> Result { + let dir = std::env::var_os(STATE_ENV) + .filter(|value| !value.is_empty()) + .map(PathBuf::from) + .or_else(|| { + std::env::var_os("GUARDIAN_METADATA_PATH") + .filter(|value| !value.is_empty()) + .map(|path| PathBuf::from(path).join("modules")) + }) + .unwrap_or_else(|| catalog_path.with_extension("tables")); + store::FsModuleStore::open(dir) +} + +/// The pipeline configured by `GUARDIAN_MODULES_CONFIG`, or `None` when it is unset. `store` is +/// the backend's module tables; without one (filesystem backend) they are files. +pub async fn from_env( + now: String, + store: Option>, + registry: &Registry, + execution_lease: std::time::Duration, + network: crate::network::NetworkType, +) -> Result>, String> { + let unconfigured = Unconfigured { + prod: crate::config::stage::Stage::from_env() + .map_err(|e| e.to_string())? + .is_prod(), + disabled_on_purpose: disabled_on_purpose()?, + }; + load( + std::env::var_os(CONFIG_ENV), + unconfigured, + now, + store, + registry, + execution_lease, + network, + ) + .await +} + +/// What decides whether a Guardian may start without a catalog while its database holds module +/// state: refused in the prod stage unless [`DISABLED_ENV`] says it is on purpose. +#[derive(Clone, Copy, Debug)] +struct Unconfigured { + prod: bool, + disabled_on_purpose: bool, +} + +/// Set to `true` to start a prod-stage Guardian without a catalog although its database holds +/// module state; without it, a lost `GUARDIAN_MODULES_CONFIG` refuses startup instead of +/// silently running every account without its policies. +pub const DISABLED_ENV: &str = "GUARDIAN_MODULES_DISABLED"; + +fn disabled_on_purpose() -> Result { + match std::env::var(DISABLED_ENV) { + Err(std::env::VarError::NotPresent) => Ok(false), + Ok(value) => match value.trim() { + "true" => Ok(true), + "false" | "" => Ok(false), + other => Err(format!( + "{DISABLED_ENV} must be true or false, not {other:?}" + )), + }, + Err(std::env::VarError::NotUnicode(_)) => { + Err(format!("{DISABLED_ENV} must be true or false")) + } + } +} + +/// [`from_env`] for `config`, the value of `GUARDIAN_MODULES_CONFIG`. Only an unset variable +/// means "no modules": an empty value or a catalog that declares none is a mistake that would +/// otherwise start the server without any policy. +async fn load( + config: Option, + unconfigured: Unconfigured, + now: String, + store: Option>, + registry: &Registry, + execution_lease: std::time::Duration, + network: crate::network::NetworkType, +) -> Result>, String> { + let Some(path) = config else { + let stored = match &store { + Some(store) => store.instances().await?.len(), + None => 0, + }; + if stored > 0 && unconfigured.prod && !unconfigured.disabled_on_purpose { + return Err(format!( + "{CONFIG_ENV} is not set, but this Guardian's database holds state for {stored} policy module instance(s): starting would run every account without its policies. Set {CONFIG_ENV} to the catalog, or set {DISABLED_ENV}=true to run without policy modules on purpose" + )); + } + if stored > 0 { + tracing::warn!( + stored_instances = stored, + "{CONFIG_ENV} is not set: no policy module runs, although this Guardian's database holds module state from an earlier catalog" + ); + } else { + tracing::info!("{CONFIG_ENV} is not set: no policy module runs"); + } + return Ok(None); + }; + if path.is_empty() { + return Err(format!( + "{CONFIG_ENV} is set but empty; point it at a catalog file, or unset it to run without policy modules" + )); + } + let catalog_path = PathBuf::from(path); + let mut catalog = Catalog::load(&catalog_path)?; + if catalog.instances.is_empty() { + return Err(format!( + "module catalog {} declares no module; unset {CONFIG_ENV} to run without policy modules", + catalog_path.display() + )); + } + let limits = limits::Limits::from_env()?; + let prod = crate::config::stage::Stage::from_env() + .map_err(|e| e.to_string())? + .is_prod(); + if prod { + catalog.check_production()?; + catalog.check_budget(limits.budget, execution_lease)?; + } + let source = if catalog.names_secrets() { + let catalog_dir = catalog_path.parent().unwrap_or(std::path::Path::new(".")); + Some(secrets::from_env(catalog_dir, prod).await?) + } else { + None + }; + catalog.resolve_secrets(source.as_deref()).await; + let store = match store { + Some(store) => store, + None => Arc::new(filesystem_store(&catalog_path)?), + }; + let network_id = crate::metadata::network::MidenNetworkType::from(network).as_str(); + let pipeline = ModulePipeline::new(network_id, catalog, registry, store, now, limits).await?; + let version = pipeline.store().instance_version().await?; + let (over_budget, orphaned) = pipeline.report_stored_assignments().await?; + let builds = pipeline + .instances() + .iter() + .map(|instance| { + format!( + "{}={}", + instance.config.id, + instance.build.as_deref().unwrap_or("unavailable") + ) + }) + .collect::>() + .join(", "); + tracing::info!(catalog_hash = %pipeline.catalog_hash, params_version = version, %builds, over_budget, orphaned, "Policy modules loaded"); + Ok(Some(Arc::new(pipeline))) +} + +#[cfg(test)] +mod tests { + use super::*; + + const DEV: Unconfigured = Unconfigured { + prod: false, + disabled_on_purpose: false, + }; + + async fn loaded(config: Option<&str>) -> Result>, String> { + loaded_with(config, DEV, Arc::new(store::FsModuleStore::in_memory())).await + } + + async fn loaded_with( + config: Option<&str>, + unconfigured: Unconfigured, + store: Arc, + ) -> Result>, String> { + load( + config.map(Into::into), + unconfigured, + "2026-11-10T00:00:00Z".into(), + Some(store), + &Registry::first_party(), + std::time::Duration::from_secs(60), + crate::network::NetworkType::MidenLocal, + ) + .await + } + + fn catalog_file(text: &str) -> (tempfile::TempDir, String) { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("modules.toml"); + std::fs::write(&path, text).unwrap(); + let path = path.to_str().unwrap().to_string(); + (dir, path) + } + + #[tokio::test] + async fn only_an_unset_variable_runs_without_modules() { + assert!(loaded(None).await.unwrap().is_none()); + + let empty_value = loaded(Some("")) + .await + .err() + .expect("an empty value is refused"); + assert!(empty_value.contains("is set but empty"), "{empty_value}"); + + for text in ["", "# every module commented out\n"] { + let (_dir, path) = catalog_file(text); + let no_module = loaded(Some(&path)) + .await + .err() + .expect("a catalog without modules is refused"); + assert!(no_module.contains("declares no module"), "{no_module}"); + } + } + + /// A prod Guardian whose catalog variable went missing in a deploy would otherwise run + /// every account without its policies, with only a warning. + #[tokio::test] + async fn a_prod_guardian_with_module_state_needs_its_catalog_or_an_explicit_opt_out() { + let store: Arc = Arc::new(store::FsModuleStore::in_memory()); + store + .seed_instance( + "caps", + true, + &serde_json::json!({}), + &serde_json::json!({}), + "t0", + ) + .await + .unwrap(); + let prod = Unconfigured { + prod: true, + disabled_on_purpose: false, + }; + let refused = loaded_with(None, prod, store.clone()) + .await + .err() + .expect("refused"); + assert!(refused.contains(DISABLED_ENV), "{refused}"); + + let on_purpose = Unconfigured { + disabled_on_purpose: true, + ..prod + }; + assert!( + loaded_with(None, on_purpose, store.clone()) + .await + .unwrap() + .is_none() + ); + assert!( + loaded_with(None, DEV, store).await.unwrap().is_none(), + "outside prod it only warns" + ); + assert!( + loaded_with(None, prod, Arc::new(store::FsModuleStore::in_memory())) + .await + .unwrap() + .is_none(), + "a database without module state needs nothing" + ); + } + + #[tokio::test] + async fn a_catalog_with_a_module_loads() { + let (_dir, path) = catalog_file( + r#" +[[module]] +id = "caps" +kind = "spending-limit" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +"#, + ); + let pipeline = loaded(Some(&path)) + .await + .unwrap() + .expect("the catalog declares a module"); + assert_eq!(pipeline.instances().len(), 1); + } +} diff --git a/crates/server/src/modules/pipeline/budget.rs b/crates/server/src/modules/pipeline/budget.rs new file mode 100644 index 000000000..53a11573c --- /dev/null +++ b/crates/server/src/modules/pipeline/budget.rs @@ -0,0 +1,166 @@ +//! The evaluation budget of an account's stored modules: the check an operator write must pass, +//! and the recount behind the over-budget and orphaned-row gauges. + +use super::ModulePipeline; +use crate::error::GuardianError; +use crate::modules::catalog::{HookName, Scope}; +use crate::modules::store::{AccountParamsRow, ParamsKind}; + +/// An account whose stored modules could take longer than the evaluation budget. +struct OverBudget { + account_id: String, + hook: HookName, + worst_case: std::time::Duration, +} + +impl ModulePipeline { + /// The hook with the largest worst-case module time for an account whose rows name + /// `modules`, and that time: every `scope = all` instance, once more for an account layer on + /// it, plus every listed instance. Disabled instances count, since enabling needs no further + /// check; a row naming an instance the catalog no longer declares costs nothing. + fn worst_case(&self, modules: &[(&str, ParamsKind)]) -> (HookName, std::time::Duration) { + self.costs(modules) + .into_iter() + .max_by_key(|(_, total)| *total) + .unwrap_or(( + HookName::BeforeTransactionApproved, + std::time::Duration::ZERO, + )) + } + + /// The summed timeouts of the module calls an account naming `modules` makes at each gate + /// hook. + fn costs(&self, modules: &[(&str, ParamsKind)]) -> Vec<(HookName, std::time::Duration)> { + let calls = |id: &str, kind: ParamsKind| { + modules + .iter() + .filter(|(module_id, named)| *named == kind && *module_id == id) + .count() as u32 + }; + HookName::GATES + .into_iter() + .map(|hook| { + let total = self + .instances + .iter() + .filter(|instance| instance.config.hooks.contains(&hook)) + .map(|instance| { + let id = instance.config.id.as_str(); + let count = match instance.config.scope { + Scope::All => 1 + calls(id, ParamsKind::Layer), + Scope::Default | Scope::Assigned => calls(id, ParamsKind::Assignment), + }; + instance.config.timeout * count + }) + .sum(); + (hook, total) + }) + .collect() + } + + /// Refuses a write that would take the account's modules over the budget at a hook where + /// they are not already at least that far over. A write that keeps or lowers the cost passes, + /// so an account a deploy pushed over the budget can still be brought back under it. + pub fn check_budget( + &self, + current: &[AccountParamsRow], + proposed: &[AccountParamsRow], + ) -> Result<(), GuardianError> { + let named = |rows: &[AccountParamsRow]| -> Vec<(HookName, std::time::Duration)> { + let modules: Vec<(&str, ParamsKind)> = rows + .iter() + .map(|row| (row.module_id.as_str(), row.kind)) + .collect(); + self.costs(&modules) + }; + for ((hook, total), (_, now)) in named(proposed).into_iter().zip(named(current)) { + if total > self.limits.budget && total > now { + return Err(GuardianError::ModuleWriteRefused(format!( + "the account's modules at {} would take up to {} ms, over the evaluation budget of {} ms", + hook.as_str(), + total.as_millis(), + self.limits.budget.as_millis() + ))); + } + } + Ok(()) + } + + /// The accounts whose stored modules exceed the budget, each with its worst hook and that + /// hook's time, and the count of stored rows evaluation no longer applies (their instance + /// was removed from the catalog or changed `scope`, see [`ModulePipeline::row_applies`]). + /// One scan of which module each account row names, without params. + async fn scan_assignments(&self) -> Result<(Vec, usize), String> { + let rows = self.store.account_modules().await?; + let orphaned = rows + .iter() + .filter(|row| !self.row_applies(&row.module_id, row.kind)) + .count(); + let over = rows + .chunk_by(|a, b| a.account_id == b.account_id) + .filter_map(|account| { + let modules: Vec<(&str, ParamsKind)> = account + .iter() + .map(|row| (row.module_id.as_str(), row.kind)) + .collect(); + let (hook, worst_case) = self.worst_case(&modules); + (worst_case > self.limits.budget).then(|| OverBudget { + account_id: account[0].account_id.clone(), + hook, + worst_case, + }) + }) + .collect(); + Ok((over, orphaned)) + } + + /// The over-budget account count and the orphaned row count as last counted. + #[cfg(test)] + pub fn assignment_report(&self) -> (usize, usize) { + self.assignment_report + .lock() + .map(|report| *report) + .unwrap_or_default() + } + + fn record_assignment_report(&self, over_budget: usize, orphaned: usize) { + if let Ok(mut report) = self.assignment_report.lock() { + *report = (over_budget, orphaned); + } + } + + /// Logs every account whose stored modules exceed the budget, without refusing to start: a + /// deploy that raised a timeout must not become an outage. Returns the count of those + /// accounts and of stored rows evaluation no longer applies. + pub async fn report_stored_assignments(&self) -> Result<(usize, usize), String> { + let (over, orphaned) = self.scan_assignments().await?; + if orphaned > 0 { + tracing::warn!( + rows = orphaned, + "Stored account module rows no longer apply: their instance was removed from the catalog or its scope changed; GET /dashboard/accounts/{{id}}/modules marks them orphaned" + ); + } + for account in &over { + tracing::warn!( + account_id = %account.account_id, + hook = account.hook.as_str(), + worst_case_ms = account.worst_case.as_millis() as u64, + budget_ms = self.limits.budget.as_millis() as u64, + "Account's policy modules exceed the evaluation budget; the runtime budget applies" + ); + } + self.record_assignment_report(over.len(), orphaned); + Ok((over.len(), orphaned)) + } + + /// Recounts the over-budget accounts and orphaned rows for the gauges, so they follow what + /// operators change after startup: an alarm clears once the assignment is fixed. + pub async fn refresh_assignment_report(&self) { + match self.scan_assignments().await { + Ok((over, orphaned)) => self.record_assignment_report(over.len(), orphaned), + Err(error) => { + tracing::warn!(%error, "Stored module assignments not recounted; the gauges keep their last values"); + } + } + } +} diff --git a/crates/server/src/modules/pipeline/mod.rs b/crates/server/src/modules/pipeline/mod.rs new file mode 100644 index 000000000..ec548e587 --- /dev/null +++ b/crates/server/src/modules/pipeline/mod.rs @@ -0,0 +1,1818 @@ +//! Ordered evaluation of an account's modules at one hook. + +use guardian_module_sdk::{Decision, Effect, HookRequest, is_valid_reason_code}; + +mod budget; +mod probe; +mod startup; + +use super::catalog::{ClientReason, HookName, OnError, Scope}; +use std::collections::{HashMap, HashSet}; +use std::sync::{Arc, RwLock}; + +use super::breaker::{Breakers, Caller}; +use super::limits::Limits; +use super::registry::{CallError, Instance, isolated}; +use super::store::{AccountParamsRow, Assigned, ModuleStore, ParamsKind}; +use crate::delta_summary::FailedOpen; +use crate::error::GuardianError; + +/// The configuration a pipeline run evaluated with, and the failures `on_error = allow` let +/// through. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Evaluation { + pub catalog_hash: String, + /// The instance params version: global params and enabled flags. + pub params_version: u64, + /// The account's params version: its layers and assignment. + pub account_params_version: u64, + pub failed_open: Vec, +} + +impl Evaluation { + /// Records the failures `on_error = allow` let through at a hook that signs nothing, so they + /// are kept somewhere other than the log. A transaction's are stored with its signed delta + /// instead. `subject` adds what the hook judged, a proposal id for one. + pub fn audit_failed_open( + &self, + auditor: &dyn crate::audit::Auditor, + hook: HookName, + account_id: &str, + submitter: &str, + subject: serde_json::Map, + ) { + if self.failed_open.is_empty() { + return; + } + let mut payload = serde_json::json!({ + "hook": hook.as_str(), + "submitter": submitter, + "catalog_hash": self.catalog_hash, + "params_version": self.params_version, + "account_params_version": self.account_params_version, + "failed_open": self.failed_open, + }); + if let Some(fields) = payload.as_object_mut() { + fields.extend(subject); + } + auditor.record(crate::audit::AuditEvent { + operator_identity: crate::services::release_on_switch::SYSTEM_OPERATOR_IDENTITY + .to_string(), + action_kind: crate::audit::kinds::MODULES_FAILED_OPEN, + target_account_id: Some(account_id.to_string()), + payload, + outcome: crate::audit::AuditOutcome::Success, + error_code: None, + client_ip: None, + }); + } +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Layer { + Global, + Account, +} + +impl Layer { + pub fn as_str(self) -> &'static str { + match self { + Layer::Global => "global", + Layer::Account => "account", + } + } +} + +pub struct ModulePipeline { + instances: Vec, + store: Arc, + cache: RwLock, + limits: Limits, + breakers: Arc, + pub catalog_hash: String, + /// The network this Guardian serves, as modules receive it in `network_id`. + network_id: &'static str, + /// Instances whose stored seed differs from the catalog's params, as of startup. + seed_drift: HashSet, + /// Accounts over the budget and orphaned assignment rows, as of the last report. + assignment_report: std::sync::Mutex<(usize, usize)>, + /// Instances that started without passing their startup checks because their module did + /// not answer. Each health probe runs the checks again until they pass. + unchecked: std::sync::Mutex>, +} + +pub(super) type Rows = Arc>; + +/// What one evaluation reads: see [`ModulePipeline::snapshot`]. +pub(super) struct Snapshot { + pub params_version: u64, + pub account_params_version: u64, + pub rows: Rows, + pub account_rows: Vec, +} + +#[derive(Default)] +struct Cache { + version: Option, + rows: Rows, +} + +/// The modules one request runs through, resolved once with a single store read. +pub struct Plan<'a> { + hook: HookName, + account_id: String, + modules: Vec<(&'a Instance, serde_json::Value, Layer)>, + network_id: &'static str, + catalog_hash: String, + params_version: u64, + account_params_version: u64, + limits: Limits, + breakers: Arc, + /// A policy check: every request says so, and nothing is stored whatever the decision. + dry_run: bool, +} + +enum Failure { + Error(String), + /// The module refused this request as one it cannot judge: its failure for this request, + /// which says nothing about whether the module is up. + Rejected(String), + Timeout, + /// No `effect`, or a value this Guardian does not know: never read as an allow. + UnknownEffect(i32), + /// The request could not be built: an account view or the projection could not be + /// extracted, or the stored state could not be read. Never let through by `on_error`. + RequestUnavailable(String), + /// The encoded request exceeds the size cap; it is not sent. Never let through by + /// `on_error`. + RequestTooLarge(usize), + /// The instance's breaker is open; the module is not called. + CircuitOpen, +} + +impl Failure { + fn kind(&self) -> &'static str { + match self { + Failure::Error(_) | Failure::Rejected(_) => "error", + Failure::Timeout => "timeout", + Failure::UnknownEffect(_) => "invalid_decision", + Failure::RequestUnavailable(_) | Failure::RequestTooLarge(_) => "request_unavailable", + Failure::CircuitOpen => "circuit_open", + } + } + + /// The refusal for a failure the request itself causes, whatever the instance's + /// `on_error`: a requester can make a request that cannot be built or that exceeds the size + /// cap, so letting either through would let the requester switch fail-open instances off. + /// `on_error` covers only the module's own failures. A request that could not be built is + /// refused as unavailable, since its cause can be transient (the chain fee not loaded yet); + /// one over the cap is denied, since resending it cannot succeed. Returns the refusal and + /// its `reason` for `guardian_module_request_refused_total`, or `None` for the module's own + /// failures. + fn refusal(&self, instance: &Instance, layer: Layer) -> Option<(GuardianError, &'static str)> { + let generic = instance.config.client_reason == ClientReason::Generic; + match self { + Failure::RequestUnavailable(_) => Some(( + GuardianError::ModuleUnavailable { + module: (!generic).then(|| instance.config.id.clone()), + }, + "unavailable", + )), + Failure::RequestTooLarge(_) if generic => { + Some((GuardianError::ModuleDeniedGeneric, "too_large")) + } + Failure::RequestTooLarge(_) => Some(( + GuardianError::ModuleDenied { + module: instance.config.id.clone(), + reason_code: REQUEST_TOO_LARGE.to_string(), + layer: layer.as_str().to_string(), + client_message: Some(REQUEST_TOO_LARGE_MESSAGE.to_string()), + }, + "too_large", + )), + Failure::Error(_) + | Failure::Rejected(_) + | Failure::Timeout + | Failure::UnknownEffect(_) + | Failure::CircuitOpen => None, + } + } +} + +/// The reason code of the denial for a request over `GUARDIAN_MODULE_REQUEST_MAX_BYTES`. +const REQUEST_TOO_LARGE: &str = "request_too_large"; +const REQUEST_TOO_LARGE_MESSAGE: &str = + "This request is too large for this Guardian's policy modules to judge."; + +impl std::fmt::Display for Failure { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Failure::Error(message) => write!(f, "{message}"), + Failure::Rejected(message) => write!(f, "module rejected the request: {message}"), + Failure::Timeout => write!(f, "timed out"), + Failure::UnknownEffect(value) => write!(f, "unknown decision effect {value}"), + Failure::RequestUnavailable(message) => write!(f, "request unavailable: {message}"), + Failure::RequestTooLarge(bytes) => { + write!(f, "request of {bytes} bytes over the size cap") + } + Failure::CircuitOpen => write!(f, "circuit open"), + } + } +} + +impl ModulePipeline { + /// [`startup::storable`] under this pipeline's limits. + pub fn storable_normalization(&self, params: &serde_json::Value) -> Result<(), String> { + startup::storable(&self.limits, params) + } + + #[cfg(test)] + pub fn from_instances(instances: Vec) -> Self { + Self::from_instances_with_store( + instances, + Arc::new(super::store::FsModuleStore::in_memory()), + ) + } + + #[cfg(test)] + pub fn from_instances_with_store( + instances: Vec, + store: Arc, + ) -> Self { + Self { + instances, + store, + cache: RwLock::new(Cache::default()), + limits: Limits::default(), + breakers: Arc::new(Breakers::new(Limits::default().breaker_failures)), + catalog_hash: String::new(), + network_id: "local", + seed_drift: HashSet::new(), + assignment_report: std::sync::Mutex::new((0, 0)), + unchecked: std::sync::Mutex::default(), + } + } + + #[cfg(test)] + pub fn with_network(mut self, network_id: &'static str) -> Self { + self.network_id = network_id; + self + } + + #[cfg(test)] + pub fn with_limits(mut self, limits: Limits) -> Self { + self.breakers = Arc::new(Breakers::new(limits.breaker_failures)); + self.limits = limits; + self + } + + pub fn limits(&self) -> Limits { + self.limits + } + + pub fn breakers(&self) -> &Breakers { + &self.breakers + } + + pub fn instances(&self) -> &[Instance] { + &self.instances + } + + pub fn instance(&self, module_id: &str) -> Option<&Instance> { + self.instances + .iter() + .find(|instance| instance.config.id == module_id) + } + + /// Whether a stored account row is one evaluation applies: its instance is declared, and a + /// layer names a `scope = all` instance while an assignment entry names any other. A row + /// that fails this is left over from an earlier catalog (the instance was removed, or its + /// `scope` changed) and is reported as orphaned. + pub fn row_applies(&self, module_id: &str, kind: ParamsKind) -> bool { + self.instance(module_id).is_some_and(|instance| { + (kind == ParamsKind::Layer) == (instance.config.scope == Scope::All) + }) + } + + #[cfg(test)] + pub fn store_handle(&self) -> Arc { + self.store.clone() + } + + pub fn store(&self) -> &dyn ModuleStore { + self.store.as_ref() + } + + fn store_error(error: String) -> GuardianError { + GuardianError::StorageError(format!("module state unavailable: {error}")) + } + + /// The stored `(global params, enabled)` rows, cached per replica and refreshed when the + /// instance params version moves. One version read per call. + pub(super) async fn rows(&self) -> Result { + Ok(self.versioned_rows().await?.1) + } + + async fn versioned_rows(&self) -> Result<(u64, Rows), GuardianError> { + let version = self + .store + .instance_version() + .await + .map_err(Self::store_error)?; + if let Ok(cache) = self.cache.read() + && cache.version == Some(version) + { + return Ok((version, cache.rows.clone())); + } + let rows: Rows = Arc::new( + self.store + .instances() + .await + .map_err(Self::store_error)? + .into_iter() + .map(|row| (row.module_id, (row.global_params, row.enabled))) + .collect(), + ); + if let Ok(mut cache) = self.cache.write() { + *cache = Cache { + version: Some(version), + rows: rows.clone(), + }; + } + Ok((version, rows)) + } + + /// Whether the account has module history: any write to its layers or assignment, an + /// emptied assignment included. Only an account without any receives the `default` + /// instances, by the same rule the copy at registration applies. + pub async fn has_account_history(&self, account_id: &str) -> Result { + let Snapshot { + account_params_version, + account_rows, + .. + } = self.snapshot(&account_id.to_ascii_lowercase()).await?; + Ok(account_params_version != 0 + || account_rows + .iter() + .any(|row| row.kind == ParamsKind::Assignment)) + } + + /// The global rows and one account's rows with their two params versions, read in one store + /// call. Without it a request could combine a new global rule with an old account layer, a + /// combination no operator ever configured. The instance rows come from the cache when it + /// holds the instance params version the store reports. + pub(super) async fn snapshot(&self, account_id: &str) -> Result { + let cached = self + .cache + .read() + .ok() + .and_then(|cache| cache.version.map(|version| (version, cache.rows.clone()))); + let snapshot = self + .store + .snapshot(account_id, cached.as_ref().map(|(version, _)| *version)) + .await + .map_err(Self::store_error)?; + let rows = match (snapshot.instances, cached) { + (Some(instances), _) => { + let rows: Rows = Arc::new( + instances + .into_iter() + .map(|row| (row.module_id, (row.global_params, row.enabled))) + .collect(), + ); + if let Ok(mut cache) = self.cache.write() { + *cache = Cache { + version: Some(snapshot.instance_version), + rows: rows.clone(), + }; + } + rows + } + (None, Some((_, rows))) => rows, + (None, None) => { + return Err(Self::store_error( + "module store omitted the instance rows without a cached version".into(), + )); + } + }; + Ok(Snapshot { + params_version: snapshot.instance_version, + account_params_version: snapshot.account_version, + rows, + account_rows: snapshot.account_params, + }) + } + + pub(super) fn global_params_in(rows: &Rows, instance: &Instance) -> serde_json::Value { + if instance.config.file_managed_params { + return instance.config.params.clone(); + } + rows.get(&instance.config.id).map_or_else( + || instance.config.params.clone(), + |(params, _)| params.clone(), + ) + } + + pub(super) fn enabled_in(rows: &Rows, instance: &Instance) -> bool { + rows.get(&instance.config.id) + .map_or(instance.config.enabled, |(_, enabled)| *enabled) + } + + /// The instance's global params: the stored ones, or the catalog's when they are + /// file-managed or not seeded yet. + pub async fn global_params( + &self, + instance: &Instance, + ) -> Result { + Ok(Self::global_params_in(&self.rows().await?, instance)) + } + + /// Whether the instance is switched on: the stored runtime flag, or the startup flag for an + /// instance without a row yet. + pub async fn enabled(&self, instance: &Instance) -> Result { + Ok(Self::enabled_in(&self.rows().await?, instance)) + } + + /// The modules that run for this account at this hook, or `None` when there are none, so a + /// caller skips building the request. + pub async fn plan( + &self, + hook: HookName, + account_id: &str, + ) -> Result>, GuardianError> { + Ok(self.plan_with(hook, account_id, false).await?.0) + } + + /// The `before_account_registered` plan of an account registering for the first time (no + /// account yet, or a claim with no assignment history): the `all` instances and every + /// enabled `default` instance subscribed to the hook, with its current global params. Also + /// returns the `default` copies to store for the account: every `default` instance, a + /// disabled one included so it applies once re-enabled, with its global params as read in + /// the same snapshot. + pub async fn plan_first_registration( + &self, + account_id: &str, + ) -> Result<(Option>, Vec), GuardianError> { + self.plan_with(HookName::BeforeAccountRegistered, account_id, true) + .await + } + + async fn plan_with( + &self, + hook: HookName, + account_id: &str, + first_registration: bool, + ) -> Result<(Option>, Vec), GuardianError> { + let account_id = account_id.to_ascii_lowercase(); + let subscribed = |rows: &Rows, instance: &&Instance| { + instance.config.hooks.contains(&hook) && Self::enabled_in(rows, instance) + }; + let relevant = self.instances.iter().any(|instance| { + instance.config.hooks.contains(&hook) + || first_registration && instance.config.scope == Scope::Default + }); + if !relevant { + return Ok((None, Vec::new())); + } + let Snapshot { + params_version, + account_params_version, + rows, + account_rows, + } = self.snapshot(&account_id).await?; + let defaults: Vec = if first_registration { + self.instances + .iter() + .filter(|instance| instance.config.scope == Scope::Default) + .map(|instance| Assigned { + module_id: instance.config.id.clone(), + params: Self::global_params_in(&rows, instance), + }) + .collect() + } else { + Vec::new() + }; + let active: Vec<&Instance> = self + .instances + .iter() + .filter(|instance| subscribed(&rows, instance)) + .collect(); + if active.is_empty() { + return Ok((None, defaults)); + } + let mut modules = Vec::new(); + for instance in active + .iter() + .filter(|instance| instance.config.scope == Scope::All) + { + modules.push(( + *instance, + Self::global_params_in(&rows, instance), + Layer::Global, + )); + if let Some(layer) = account_rows + .iter() + .find(|row| row.kind == ParamsKind::Layer && row.module_id == instance.config.id) + { + modules.push((*instance, layer.params.clone(), Layer::Account)); + } + } + for row in account_rows + .iter() + .filter(|row| row.kind == ParamsKind::Assignment) + { + if let Some(instance) = active.iter().find(|instance| { + instance.config.id == row.module_id && instance.config.scope != Scope::All + }) { + modules.push((*instance, row.params.clone(), Layer::Account)); + } + } + for copy in &defaults { + if let Some(instance) = active + .iter() + .find(|instance| instance.config.id == copy.module_id) + { + modules.push((*instance, copy.params.clone(), Layer::Global)); + } + } + let plan = (!modules.is_empty()).then_some(Plan { + hook, + account_id, + modules, + network_id: self.network_id, + catalog_hash: self.catalog_hash.clone(), + params_version, + account_params_version, + limits: self.limits, + breakers: self.breakers.clone(), + dry_run: false, + }); + Ok((plan, defaults)) + } + + /// The plans for a dry-run check of a proposal: the `before_proposal_created` instances, + /// then those subscribed only to `before_transaction_approved`, so an instance on both runs + /// once and rules that must hold at approval are checked too. Instances with + /// `dry_run = false` are skipped. `complete` is false whenever the catalog has an enabled + /// transaction gate instance that opts out, whether or not it applies to this account, so + /// the answer reveals nothing about one account's instances. + pub async fn plan_dry_run( + &self, + account_id: &str, + ) -> Result<(Vec>, bool), GuardianError> { + let (_, rows) = self.versioned_rows().await?; + let complete = !self.instances.iter().any(|instance| { + Self::enabled_in(&rows, instance) + && !instance.config.dry_run + && (instance + .config + .hooks + .contains(&HookName::BeforeProposalCreated) + || instance + .config + .hooks + .contains(&HookName::BeforeTransactionApproved)) + }); + let mut plans = Vec::new(); + for hook in [ + HookName::BeforeProposalCreated, + HookName::BeforeTransactionApproved, + ] { + let Some(mut plan) = self.plan(hook, account_id).await? else { + continue; + }; + plan.modules.retain(|(instance, _, _)| { + instance.config.dry_run + && (hook == HookName::BeforeProposalCreated + || !instance + .config + .hooks + .contains(&HookName::BeforeProposalCreated)) + }); + plan.dry_run = true; + if !plan.modules.is_empty() { + plans.push(plan); + } + } + Ok((plans, complete)) + } + + pub async fn applies(&self, hook: HookName, account_id: &str) -> Result { + Ok(self.plan(hook, account_id).await?.is_some()) + } + + /// Plans and runs the hook in one step. + pub async fn run( + &self, + hook: HookName, + account_id: &str, + build: impl FnOnce() -> Result, + ) -> Result<(), GuardianError> { + match self.plan(hook, account_id).await? { + Some(plan) => plan.run(build).await.map(|_| ()), + None => Ok(()), + } + } +} + +impl Plan<'_> { + /// The network this Guardian serves, for this plan's request. + pub fn network_id(&self) -> &'static str { + self.network_id + } + + /// Runs the planned modules in order and returns the configuration they ran with. If + /// `build` fails (an account view or the projection could not be extracted, a proposal or + /// state read failed), the request is refused as unavailable whatever each module's + /// `on_error` says (RFC 0002 section 4.2): see [`Failure::refusal`]. + pub async fn run( + self, + build: impl FnOnce() -> Result, + ) -> Result { + let Plan { + hook, + account_id, + modules, + network_id: _, + catalog_hash, + params_version, + account_params_version, + limits, + breakers, + dry_run, + } = self; + let account_id = account_id.as_str(); + let mut approval = Evaluation { + catalog_hash, + params_version, + account_params_version, + failed_open: Vec::new(), + }; + let request_id = format!("{:032x}", rand::random::()); + let base = match build() { + Ok(base) => HookRequest { + request_id: request_id.clone(), + dry_run, + ..base + }, + Err(error) => { + for (instance, _, layer) in &modules { + let failure = Failure::RequestUnavailable(error.clone()); + approval + .failed_open + .extend(fail(instance, *layer, account_id, &failure)?); + } + return Ok(approval); + } + }; + + let caller = if dry_run { + Caller::DryRun + } else { + Caller::Request + }; + let deadline = tokio::time::Instant::now() + limits.budget; + let mut called_before = false; + for (instance, params, layer) in modules { + let id = instance.config.id.as_str(); + let mut request = base.clone(); + request.hook = hook.proto() as i32; + request.instance_id = id.to_string(); + request.params = serde_json::to_vec(¶ms).unwrap_or_default(); + + let remaining = deadline.saturating_duration_since(tokio::time::Instant::now()); + let size = prost::Message::encoded_len(&request); + let unsent = if size > limits.request_max_bytes { + Some(Failure::RequestTooLarge(size)) + } else if remaining.is_zero() { + Some(Failure::Timeout) + } else if !breakers.admit(id, caller) { + Some(Failure::CircuitOpen) + } else { + None + }; + if let Some(failure) = unsent { + super::metrics::evaluated( + id, + super::metrics::Outcome::Skipped, + std::time::Duration::ZERO, + ); + approval + .failed_open + .extend(fail(instance, layer, account_id, &failure)?); + continue; + } + + let cut_by_budget = cut_by_budget(called_before, remaining, instance.config.timeout); + called_before = true; + let module = instance.module.clone(); + let started = tokio::time::Instant::now(); + let outcome = isolated(instance.config.timeout.min(remaining), async move { + module.evaluate(&request).await + }) + .await; + let took = started.elapsed(); + let failure = match outcome.map(|decision| (effect(&decision), decision)) { + Ok((Some(Effect::Allow), _)) => { + if !dry_run { + breakers.answered(id); + } + super::metrics::evaluated(id, super::metrics::Outcome::Allow, took); + continue; + } + Ok((Some(Effect::Deny), decision)) => { + let reason_code = denial_reason_code(&instance.config.id, decision.reason_code); + if !dry_run { + breakers.answered(id); + } + super::metrics::evaluated(id, super::metrics::Outcome::Deny, took); + tracing::info!( + request_id = %request_id, + module = %instance.config.id, + account_id, + ?hook, + submitter = %base.submitter, + reason_code = %reason_code, + layer = layer.as_str(), + message = %decision.message, + catalog_hash = %approval.catalog_hash, + params_version = approval.params_version, + account_params_version = approval.account_params_version, + client_reason = ?instance.config.client_reason, + "Policy module denied the request" + ); + return Err(match instance.config.client_reason { + ClientReason::Generic => GuardianError::ModuleDeniedGeneric, + ClientReason::Full => GuardianError::ModuleDenied { + module: instance.config.id.clone(), + reason_code, + layer: layer.as_str().to_string(), + client_message: client_message(&decision.client_message), + }, + }); + } + Ok((Some(Effect::Unspecified) | None, decision)) => { + Failure::UnknownEffect(decision.effect) + } + Err(CallError::Module(guardian_module_sdk::ModuleError::InvalidRequest( + message, + ))) => Failure::Rejected(message), + Err(CallError::Module(error)) => Failure::Error(error.to_string()), + Err(CallError::Panicked(message)) => { + Failure::Error(format!("module panicked: {message}")) + } + Err(CallError::Timeout) => Failure::Timeout, + }; + super::metrics::evaluated(id, super::metrics::Outcome::Error, took); + if !dry_run { + count_toward_breaker(&breakers, id, &failure, cut_by_budget); + } + approval + .failed_open + .extend(fail(instance, layer, account_id, &failure)?); + } + Ok(approval) + } +} + +/// Whether a call that times out did so because earlier modules used up the budget: it was +/// left less than its own timeout. That is a timeout, but not the module's failure. The first +/// call always has its whole share. +fn cut_by_budget( + called_before: bool, + remaining: std::time::Duration, + timeout: std::time::Duration, +) -> bool { + called_before && remaining < timeout +} + +/// Records a failed call of a request (never a dry run's, which a cosigner sends without +/// anyone's signature) on the instance's breaker. The breaker stops calls to a module that is +/// down for every account, so only failures that say so count: a request the module rejected +/// is an answer, and a timeout the budget caused is not the module's. +fn count_toward_breaker(breakers: &Breakers, id: &str, failure: &Failure, cut_by_budget: bool) { + match failure { + Failure::Rejected(_) => breakers.answered(id), + Failure::Timeout if cut_by_budget => {} + _ => breakers.failed(id), + } +} + +const CLIENT_MESSAGE_MAX_CHARS: usize = 256; + +/// A module's text for the requester as plain text: control characters dropped, whitespace +/// collapsed, at most 256 characters, and none when empty. +fn client_message(text: &str) -> Option { + let plain: String = text + .chars() + .map(|c| if c.is_control() { ' ' } else { c }) + .collect::() + .split_whitespace() + .collect::>() + .join(" "); + let capped: String = plain.chars().take(CLIENT_MESSAGE_MAX_CHARS).collect(); + (!capped.is_empty()).then_some(capped) +} + +/// The reason code a denial is reported with: the module's own, or the generic one when the +/// module's breaks the reason code rule. An explicit deny stays a deny either way: treating a +/// malformed code as a module failure would let `on_error = "allow"` sign what the module +/// refused. +fn denial_reason_code(module: &str, reason_code: String) -> String { + if is_valid_reason_code(&reason_code) { + return reason_code; + } + tracing::warn!(module, %reason_code, "Policy module denied with a reason code that breaks the reason code rule; reported as policy_denied"); + crate::error::GENERIC_REASON_CODE.to_string() +} + +/// What a decision asks for: `None` for a decision that sets no effect or one this Guardian +/// does not know, neither of which is ever read as an allow. +fn effect(decision: &Decision) -> Option { + match Effect::try_from(decision.effect) { + Ok(Effect::Unspecified) | Err(_) => None, + Ok(effect) => Some(effect), + } +} + +/// Refuses a failure the request causes ([`Failure::refusal`]); otherwise applies the +/// instance's `on_error`: a refusal for `deny`, the failed-open record for `allow`. +fn fail( + instance: &Instance, + layer: Layer, + account_id: &str, + failure: &Failure, +) -> Result, GuardianError> { + if let Some((refusal, reason)) = failure.refusal(instance, layer) { + super::metrics::request_refused(&instance.config.id, reason); + tracing::warn!(module = %instance.config.id, account_id, %failure, "Policy module request could not be judged; refusing whatever on_error says"); + return Err(refusal); + } + match instance.config.on_error { + OnError::Deny => { + tracing::warn!(module = %instance.config.id, account_id, %failure, "Policy module failed; refusing"); + Err(GuardianError::ModuleUnavailable { + module: match instance.config.client_reason { + ClientReason::Full => Some(instance.config.id.clone()), + ClientReason::Generic => None, + }, + }) + } + OnError::Allow => { + super::metrics::failed_open(&instance.config.id); + tracing::warn!(module = %instance.config.id, account_id, %failure, "Policy module failed; continuing (fail-open)"); + Ok(Some(FailedOpen { + module_id: instance.config.id.clone(), + layer: layer.as_str().to_string(), + failure: failure.kind().to_string(), + })) + } + } +} + +#[cfg(test)] +mod tests { + use std::time::Duration; + + use super::*; + use crate::modules::testing::{Behaviour, StubModule, instance, pipeline}; + use guardian_module_sdk::Decision; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + async fn run(pipeline: &ModulePipeline) -> Result<(), GuardianError> { + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + } + + #[tokio::test] + async fn fail_closed_timeout_refuses_as_unavailable() { + let pipeline = pipeline(vec![instance( + "slow", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Hang), + )]); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { module }) if module.as_deref() == Some("slow") + )); + } + + #[tokio::test] + async fn fail_open_failure_continues_to_the_next_module() { + let denier = StubModule::denying("limit_exceeded"); + let pipeline = pipeline(vec![ + instance( + "down", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Fail), + ), + instance("caps", &[HOOK], OnError::Deny, denier.clone()), + ]); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleDenied { module, reason_code, .. }) + if module == "caps" && reason_code == "limit_exceeded" + )); + assert_eq!(denier.calls(), 1); + } + + #[tokio::test] + async fn fail_open_timeout_alone_allows() { + let pipeline = pipeline(vec![instance( + "slow", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Hang), + )]); + assert!(run(&pipeline).await.is_ok()); + } + + #[tokio::test] + async fn the_trace_keeps_only_what_failed_open() { + let pipeline = pipeline(vec![ + instance("caps", &[HOOK], OnError::Deny, StubModule::allowing()), + instance( + "risk", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Hang), + ), + ]); + let plan = || async { pipeline.plan(HOOK, "0xacc").await.unwrap().unwrap() }; + let approval = plan() + .await + .run(|| Ok(HookRequest::default())) + .await + .unwrap(); + assert_eq!( + approval.failed_open, + vec![FailedOpen { + module_id: "risk".into(), + layer: "global".into(), + failure: "timeout".into(), + }] + ); + + let unbuilt = plan().await.run(|| Err("no state".to_string())).await; + assert!(unbuilt.is_err(), "caps fails closed without a request"); + } + + #[tokio::test] + async fn a_panicking_module_is_a_module_failure() { + let pipeline = pipeline(vec![instance( + "buggy", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Panic), + )]); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { module }) if module.as_deref() == Some("buggy") + )); + + let pipeline = pipeline_with(OnError::Allow, Behaviour::Panic); + let approval = pipeline + .plan(HOOK, "0xacc") + .await + .unwrap() + .unwrap() + .run(|| Ok(HookRequest::default())) + .await + .unwrap(); + assert_eq!(approval.failed_open[0].failure, "error"); + } + + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn the_timeout_holds_when_a_module_blocks() { + let pipeline = pipeline_with(OnError::Deny, Behaviour::Block(Duration::from_secs(2))); + let started = std::time::Instant::now(); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + )); + assert!( + started.elapsed() < Duration::from_secs(1), + "answered at the timeout, not when the module returned" + ); + } + + fn pipeline_with(on_error: OnError, behaviour: Behaviour) -> Arc { + pipeline(vec![instance( + "stub", + &[HOOK], + on_error, + StubModule::new(behaviour), + )]) + } + + fn decision(reason_code: &str, effect: i32) -> Behaviour { + Behaviour::Decide(Decision { + reason_code: reason_code.into(), + effect, + ..Default::default() + }) + } + + #[tokio::test] + async fn the_effect_decides_and_a_missing_or_unknown_one_is_a_failure() { + assert!(matches!( + run(&pipeline_with( + OnError::Deny, + decision("explicit_deny", Effect::Deny as i32) + )) + .await, + Err(GuardianError::ModuleDenied { .. }) + )); + assert!( + run(&pipeline_with( + OnError::Deny, + decision("", Effect::Allow as i32) + )) + .await + .is_ok() + ); + for effect in [Effect::Unspecified as i32, 99] { + assert!( + matches!( + run(&pipeline_with(OnError::Deny, decision("", effect))).await, + Err(GuardianError::ModuleUnavailable { .. }) + ), + "effect {effect} is never read as an allow" + ); + } + } + + #[tokio::test] + async fn a_generic_instance_denies_without_details() { + let deny = Behaviour::Decide( + Decision::deny("recipient_sanctioned", "on list X") + .with_client_message("contact support"), + ); + let mut instance = instance("screening", &[HOOK], OnError::Deny, StubModule::new(deny)); + instance.config.client_reason = ClientReason::Generic; + assert!(matches!( + run(&pipeline(vec![instance])).await, + Err(GuardianError::ModuleDeniedGeneric) + )); + } + + #[tokio::test] + async fn a_full_denial_forwards_a_cleaned_client_message() { + let text = format!( + "Limit reached.\n\tAsk your\u{7} treasury admin. {}", + "x".repeat(400) + ); + let deny = Behaviour::Decide( + Decision::deny("amount_cap_exceeded", "internal").with_client_message(text), + ); + match run(&pipeline_with(OnError::Deny, deny)).await { + Err(GuardianError::ModuleDenied { + client_message: Some(message), + .. + }) => { + assert!(message.starts_with("Limit reached. Ask your treasury admin.")); + assert_eq!(message.chars().count(), 256); + assert!(!message.chars().any(char::is_control)); + } + other => panic!("unexpected {other:?}"), + } + assert_eq!(client_message(" \n "), None); + } + + #[tokio::test] + async fn a_request_never_mixes_a_global_rule_and_an_account_layer_from_different_versions() { + use super::super::store::Change; + use crate::modules::testing::{RacingStore, RacingWrite}; + let store = Arc::new(RacingStore::new()); + let change = Change { + operator: "0xop", + reason: "setup", + at: "2026-10-16T00:00:00Z".into(), + expected_version: None, + }; + store + .inner + .seed_instance( + "caps", + true, + &serde_json::json!({ "cap": 1000 }), + &serde_json::json!({ "cap": 1000 }), + "2026-10-16T00:00:00Z", + ) + .await + .unwrap(); + store + .inner + .set_layer( + "0xacc", + "caps", + Some(serde_json::json!({ "cap": 100 })), + &change, + ) + .await + .unwrap(); + *store.before_account_params.lock().unwrap() = vec![ + RacingWrite::Global("caps", serde_json::json!({ "cap": 100 })), + RacingWrite::Layer("0xacc", "caps", None), + ]; + let pipeline = ModulePipeline::from_instances_with_store( + vec![instance( + "caps", + &[HOOK], + OnError::Deny, + StubModule::allowing(), + )], + store, + ); + + let plan = pipeline.plan(HOOK, "0xacc").await.unwrap().unwrap(); + let params: Vec<_> = plan + .modules + .iter() + .map(|(_, params, _)| params.clone()) + .collect(); + assert_eq!( + params, + vec![serde_json::json!({ "cap": 100 })], + "the version moved during the read, so the plan was rebuilt from one version" + ); + } + + #[tokio::test] + async fn a_deny_stops_evaluation() { + let later = StubModule::allowing(); + let pipeline = pipeline(vec![ + instance("first", &[HOOK], OnError::Deny, StubModule::denying("no")), + instance("second", &[HOOK], OnError::Deny, later.clone()), + ]); + assert!(run(&pipeline).await.is_err()); + assert_eq!(later.calls(), 0); + } + + #[tokio::test] + async fn a_deny_with_a_malformed_reason_code_is_still_a_deny_whatever_on_error_says() { + for on_error in [OnError::Deny, OnError::Allow] { + let pipeline = pipeline(vec![instance( + "bad", + &[HOOK], + on_error, + StubModule::new(Behaviour::Decide(Decision::deny("RECIPIENT-Blocked", ""))), + )]); + match run(&pipeline).await { + Err(GuardianError::ModuleDenied { + module, + reason_code, + .. + }) => { + assert_eq!(module, "bad"); + assert_eq!(reason_code, crate::error::GENERIC_REASON_CODE); + } + other => panic!("{on_error:?}: expected a denial, got {other:?}"), + } + } + } + + #[tokio::test] + async fn a_request_that_cannot_be_built_is_refused_whatever_on_error_says() { + let closed = pipeline(vec![instance( + "caps", + &[HOOK], + OnError::Deny, + StubModule::allowing(), + )]); + let result = closed + .run(HOOK, "0xacc", || Err("view failed".into())) + .await; + assert!(matches!( + result, + Err(GuardianError::ModuleUnavailable { .. }) + )); + + let open = pipeline(vec![instance( + "caps", + &[HOOK], + OnError::Allow, + StubModule::allowing(), + )]); + assert!( + matches!( + open.run(HOOK, "0xacc", || Err("view failed".into())).await, + Err(GuardianError::ModuleUnavailable { .. }) + ), + "a requester must not be able to switch a fail-open module off by making the \ + request unbuildable" + ); + } + + #[tokio::test] + async fn modules_not_subscribed_to_the_hook_are_not_called() { + let other = StubModule::denying("no"); + let pipeline = pipeline(vec![instance( + "registration-only", + &[HookName::BeforeAccountRegistered], + OnError::Deny, + other.clone(), + )]); + assert!(!pipeline.applies(HOOK, "0xacc").await.unwrap()); + assert!(run(&pipeline).await.is_ok()); + assert_eq!(other.calls(), 0); + } + + mod layers { + use super::*; + use crate::modules::store::Change; + use crate::modules::testing::instance_with_params; + use guardian_module_sdk::policies::RecipientPolicy; + use guardian_module_sdk::proto::hook_request; + use guardian_module_sdk::{ + MidenTransaction, OutputNote, TransactionProjection, TransactionSubject, + }; + use serde_json::json; + + fn pay(recipient: &str) -> HookRequest { + HookRequest { + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + output_notes: vec![OutputNote { + note_id: "0xn".into(), + p2id_target: Some(recipient.into()), + ..Default::default() + }], + ..Default::default() + })), + ..Default::default() + })), + ..Default::default() + } + } + + fn blocklist() -> ModulePipeline { + ModulePipeline::from_instances(vec![instance_with_params( + "blocklist", + &[HOOK], + std::sync::Arc::new(RecipientPolicy), + json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + )]) + } + + fn change() -> Change<'static> { + Change { + operator: "0xop", + reason: "test", + at: "t".into(), + expected_version: None, + } + } + + async fn layer_of( + pipeline: &ModulePipeline, + account: &str, + recipient: &str, + ) -> Option { + match pipeline.run(HOOK, account, || Ok(pay(recipient))).await { + Ok(()) => None, + Err(GuardianError::ModuleDenied { layer, .. }) => Some(layer), + Err(other) => panic!("unexpected {other:?}"), + } + } + + #[tokio::test] + async fn account_layer_extends_the_global_rule() { + let pipeline = blocklist(); + pipeline + .store() + .set_layer( + "0xacc", + "blocklist", + Some(json!({ "denylist": ["0x000000000000000000000000000ccc"] })), + &change(), + ) + .await + .unwrap(); + + assert_eq!( + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa") + .await + .as_deref(), + Some("global") + ); + assert_eq!( + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000ccc") + .await + .as_deref(), + Some("account") + ); + assert_eq!( + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000bbb").await, + None + ); + assert_eq!( + layer_of(&pipeline, "0xother", "0x000000000000000000000000000ccc").await, + None + ); + assert_eq!( + layer_of(&pipeline, "0xother", "0x000000000000000000000000000aaa") + .await + .as_deref(), + Some("global") + ); + } + + #[tokio::test] + async fn an_account_layer_cannot_loosen_the_global_rule() { + let pipeline = blocklist(); + pipeline + .store() + .set_layer("0xacc", "blocklist", Some(json!({})), &change()) + .await + .unwrap(); + assert_eq!( + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa") + .await + .as_deref(), + Some("global") + ); + } + + #[tokio::test] + async fn global_params_changed_at_runtime_apply_to_the_next_evaluation() { + let pipeline = blocklist(); + pipeline + .store() + .seed_instance( + "blocklist", + true, + &json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + &json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + "t0", + ) + .await + .unwrap(); + pipeline + .store() + .set_global( + "blocklist", + json!({ "denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }), + &change(), + ) + .await + .unwrap(); + assert_eq!( + layer_of(&pipeline, "0xany", "0x000000000000000000000000000ddd") + .await + .as_deref(), + Some("global") + ); + } + + #[tokio::test] + async fn a_module_disabled_at_runtime_is_skipped_until_enabled_again() { + let pipeline = blocklist(); + pipeline + .store() + .seed_instance( + "blocklist", + true, + &json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + &json!({ "denylist": ["0x000000000000000000000000000aaa"] }), + "t0", + ) + .await + .unwrap(); + assert_eq!( + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa") + .await + .as_deref(), + Some("global") + ); + pipeline + .store() + .set_enabled("blocklist", false, &change()) + .await + .unwrap(); + assert_eq!( + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa").await, + None + ); + assert!(!pipeline.applies(HOOK, "0xacc").await.unwrap()); + pipeline + .store() + .set_enabled("blocklist", true, &change()) + .await + .unwrap(); + assert_eq!( + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa") + .await + .as_deref(), + Some("global") + ); + } + } +} + +#[cfg(test)] +mod evaluation_trace_tests { + use guardian_module_sdk::HookRequest; + + use super::*; + use crate::modules::catalog::{ClientReason, HookName, OnError}; + use crate::modules::testing::{StubModule, instance}; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + #[tokio::test] + async fn one_invocation_shares_a_request_id_and_the_next_gets_a_new_one() { + let first = StubModule::allowing(); + let second = StubModule::allowing(); + let pipeline = ModulePipeline::from_instances(vec![ + instance("first", &[HOOK], OnError::Deny, first.clone()), + instance("second", &[HOOK], OnError::Deny, second.clone()), + ]); + let id = |module: &StubModule| module.last_request().unwrap().request_id; + + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + .unwrap(); + let invocation = id(&first); + assert!(!invocation.is_empty()); + assert_eq!(id(&second), invocation); + + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + .unwrap(); + assert_ne!(id(&first), invocation); + } + + #[derive(Clone, Default)] + struct Captured(std::sync::Arc>>); + + impl std::io::Write for Captured { + fn write(&mut self, buf: &[u8]) -> std::io::Result { + self.0.lock().unwrap().extend_from_slice(buf); + Ok(buf.len()) + } + + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } + } + + impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for Captured { + type Writer = Captured; + + fn make_writer(&'a self) -> Self::Writer { + self.clone() + } + } + + #[tokio::test(flavor = "current_thread")] + async fn a_generic_denial_hides_the_decision_from_the_client_but_logs_it_whole() { + let captured = Captured::default(); + let subscriber = tracing_subscriber::fmt() + .with_writer(captured.clone()) + .with_ansi(false) + .finish(); + let _pin = crate::testing::log_capture::dispatcher_registry_pin(); + let _default = tracing::subscriber::set_default(subscriber); + + let mut screening = instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::denying("sanctioned_counterparty"), + ); + screening.config.client_reason = ClientReason::Generic; + let pipeline = ModulePipeline::from_instances(vec![screening]); + let result = pipeline + .run(HOOK, "0xacc", || { + Ok(HookRequest { + submitter: "0xsubmitter".into(), + ..Default::default() + }) + }) + .await; + assert!(matches!(result, Err(GuardianError::ModuleDeniedGeneric))); + + let log = String::from_utf8(captured.0.lock().unwrap().clone()).unwrap(); + for field in [ + "request_id=", + "module=screening", + "account_id=\"0xacc\"", + "submitter=0xsubmitter", + "reason_code=sanctioned_counterparty", + "layer=\"global\"", + "catalog_hash=", + "params_version=", + ] { + assert!(log.contains(field), "{field} missing from {log}"); + } + } +} + +#[cfg(test)] +mod failure_handling_tests { + use std::time::Duration; + + use guardian_module_sdk::HookRequest; + + use super::*; + use crate::modules::breaker::CircuitState; + use crate::modules::catalog::{HookName, OnError}; + use crate::modules::testing::{Behaviour, StubModule, instance}; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + fn hanging(id: &str, on_error: OnError, timeout: Duration) -> (Instance, Arc) { + let module = StubModule::new(Behaviour::Hang); + let mut hung = instance(id, &[HOOK], on_error, module.clone()); + hung.config.timeout = timeout; + (hung, module) + } + + async fn run(pipeline: &ModulePipeline) -> Result<(), GuardianError> { + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + } + + #[tokio::test] + async fn a_failing_fail_closed_module_refuses_retryably_and_a_fail_open_one_is_skipped() { + let closed = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Fail), + )]); + let refused = run(&closed).await.unwrap_err(); + assert!( + matches!(&refused, GuardianError::ModuleUnavailable { module } if module.as_deref() == Some("screening")) + ); + assert!(refused.retryable()); + + let mut hidden = instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Fail), + ); + hidden.config.client_reason = ClientReason::Generic; + let refused = run(&ModulePipeline::from_instances(vec![hidden])) + .await + .unwrap_err(); + assert!( + matches!(&refused, GuardianError::ModuleUnavailable { module: None }), + "an instance with generic denials is not named when it fails either: {refused:?}" + ); + + let open = ModulePipeline::from_instances(vec![instance( + "scoring", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Fail), + )]); + assert!(run(&open).await.is_ok()); + } + + #[tokio::test] + async fn dry_run_failures_do_not_open_the_circuit() { + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Fail), + )]) + .with_limits(Limits { + breaker_failures: 2, + ..Limits::default() + }); + for _ in 0..4 { + let (plans, _) = pipeline.plan_dry_run("0xacc").await.unwrap(); + for plan in plans { + assert!(plan.run(|| Ok(HookRequest::default())).await.is_err()); + } + } + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); + } + + #[tokio::test] + async fn a_request_the_module_rejects_does_not_open_the_circuit() { + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Reject), + )]) + .with_limits(Limits { + breaker_failures: 2, + ..Limits::default() + }); + for _ in 0..4 { + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + )); + } + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Closed, + "one account's unjudgeable requests do not stop the module for every account" + ); + } + + #[tokio::test] + async fn a_module_whose_timeout_is_the_whole_budget_still_opens_the_circuit() { + let (hung, _) = hanging("screening", OnError::Deny, Duration::from_millis(40)); + let pipeline = ModulePipeline::from_instances(vec![hung]).with_limits(Limits { + budget: Duration::from_millis(40), + breaker_failures: 2, + ..Limits::default() + }); + for _ in 0..2 { + assert!(run(&pipeline).await.is_err()); + } + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + } + + #[tokio::test] + async fn consecutive_failures_open_the_circuit_so_later_requests_skip_the_timeout() { + let (hung, module) = hanging("screening", OnError::Deny, Duration::from_millis(50)); + let pipeline = ModulePipeline::from_instances(vec![hung]).with_limits(Limits { + breaker_failures: 2, + ..Limits::default() + }); + for _ in 0..2 { + assert!(run(&pipeline).await.is_err()); + } + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + + let started = tokio::time::Instant::now(); + let refused = run(&pipeline).await.unwrap_err(); + assert!(matches!(refused, GuardianError::ModuleUnavailable { .. })); + assert!( + started.elapsed() < Duration::from_millis(50), + "an open circuit refuses without waiting the timeout" + ); + assert_eq!(module.calls(), 2, "the module is not called while open"); + + pipeline.breakers().probe_succeeded("screening"); + assert!(run(&pipeline).await.is_err()); + assert_eq!(module.calls(), 3, "half-open sends the next call"); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + } + + #[tokio::test] + async fn the_budget_cuts_later_modules_short_without_blaming_them() { + let (first, _) = hanging("first", OnError::Allow, Duration::from_millis(80)); + let (second, second_module) = hanging("second", OnError::Allow, Duration::from_millis(80)); + let pipeline = ModulePipeline::from_instances(vec![first, second]).with_limits(Limits { + budget: Duration::from_millis(100), + breaker_failures: 1, + ..Limits::default() + }); + let started = tokio::time::Instant::now(); + assert!(run(&pipeline).await.is_ok(), "both fail open"); + assert!( + started.elapsed() < Duration::from_millis(150), + "the second call gets only what is left of the budget" + ); + assert_eq!(second_module.calls(), 1); + assert_eq!(pipeline.breakers().state("first"), CircuitState::Open); + assert_eq!( + pipeline.breakers().state("second"), + CircuitState::Closed, + "a call cut short by the budget is not the module's failure" + ); + } + + #[tokio::test] + async fn an_oversized_request_is_denied_and_not_sent_whatever_on_error_says() { + for on_error in [OnError::Deny, OnError::Allow] { + let module = StubModule::allowing(); + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + on_error, + module.clone(), + )]) + .with_limits(Limits { + request_max_bytes: 64, + ..Limits::default() + }); + let refused = pipeline + .run(HOOK, "0xacc", || { + Ok(HookRequest { + submitter: "0x".repeat(64), + ..Default::default() + }) + }) + .await; + assert!( + matches!( + refused, + Err(GuardianError::ModuleDenied { ref module, ref reason_code, .. }) + if module == "screening" && reason_code == "request_too_large" + ), + "{on_error:?}: {refused:?}" + ); + assert_eq!(module.calls(), 0); + } + } + + #[tokio::test] + async fn a_generic_instance_refuses_without_naming_itself() { + let mut generic = instance("screening", &[HOOK], OnError::Allow, StubModule::allowing()); + generic.config.client_reason = crate::modules::catalog::ClientReason::Generic; + let pipeline = ModulePipeline::from_instances(vec![generic]).with_limits(Limits { + request_max_bytes: 64, + ..Limits::default() + }); + let oversized = pipeline + .run(HOOK, "0xacc", || { + Ok(HookRequest { + submitter: "0x".repeat(64), + ..Default::default() + }) + }) + .await; + assert!( + matches!(oversized, Err(GuardianError::ModuleDeniedGeneric)), + "{oversized:?}" + ); + let unbuildable = pipeline + .run(HOOK, "0xacc", || Err("view failed".into())) + .await; + assert!( + matches!( + unbuildable, + Err(GuardianError::ModuleUnavailable { module: None }) + ), + "{unbuildable:?}" + ); + } + + #[tokio::test] + async fn refused_requests_never_open_the_circuit() { + let module = StubModule::allowing(); + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + module.clone(), + )]) + .with_limits(Limits { + request_max_bytes: 64, + breaker_failures: 1, + ..Limits::default() + }); + for _ in 0..3 { + let _ = pipeline + .run(HOOK, "0xacc", || { + Ok(HookRequest { + submitter: "0x".repeat(64), + ..Default::default() + }) + }) + .await; + let _ = pipeline + .run(HOOK, "0xacc", || Err("view failed".into())) + .await; + } + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Closed, + "a requester's refused requests say nothing about whether the module is up" + ); + run(&pipeline) + .await + .expect("the next request reaches the module"); + assert_eq!(module.calls(), 1); + } + + #[tokio::test] + async fn a_fail_open_failure_does_not_stop_a_later_deny() { + let pipeline = ModulePipeline::from_instances(vec![ + instance( + "scoring", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Fail), + ), + instance( + "caps", + &[HOOK], + OnError::Deny, + StubModule::denying("amount_cap_exceeded"), + ), + ]); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleDenied { module, .. }) if module == "caps" + )); + } +} diff --git a/crates/server/src/modules/pipeline/probe.rs b/crates/server/src/modules/pipeline/probe.rs new file mode 100644 index 000000000..2d3dd4d69 --- /dev/null +++ b/crates/server/src/modules/pipeline/probe.rs @@ -0,0 +1,311 @@ +//! The health probe: every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` it asks each enabled module +//! whether it is up, half-opens or holds open its breaker, reruns the startup checks of an +//! instance that started unchecked, and publishes the state gauges. + +use std::sync::Arc; + +use super::{ModulePipeline, Rows}; +use crate::modules::breaker::CircuitState; +use crate::modules::registry::Unhealthy; + +/// How often the probe loop recounts the over-budget accounts and orphaned rows. +const ASSIGNMENT_REPORT_INTERVAL: std::time::Duration = std::time::Duration::from_secs(60); + +impl ModulePipeline { + /// Sets the state gauges from the stored rows and this replica's breakers. Run on every probe, + /// so they are set once a metrics recorder exists and follow changes other replicas make. + fn publish(&self, rows: &Rows) { + crate::modules::metrics::catalog(&self.catalog_hash); + let (over_budget, orphaned) = self + .assignment_report + .lock() + .map(|report| *report) + .unwrap_or_default(); + crate::modules::metrics::stored_assignments(over_budget, orphaned); + for instance in &self.instances { + let id = &instance.config.id; + let enabled = Self::enabled_in(rows, instance); + crate::modules::metrics::enabled(id, enabled); + crate::modules::metrics::config_drift( + id, + enabled != instance.config.catalog_enabled || self.seed_drift.contains(id), + ); + crate::modules::metrics::circuit_open( + id, + self.breakers.state(id) == CircuitState::Open, + ); + } + } + + /// Stores the params a recovered module normalized `read` to, as a startup does for a module + /// that answered: kept out when they break the params rules or the instance's params are + /// file-managed, written only if the stored params are still `read`, with a history entry + /// by the module. A failed write is logged; the next start migrates again. + async fn store_recovered_migration( + &self, + instance: &crate::modules::registry::Instance, + read: &serde_json::Value, + params: serde_json::Value, + ) { + let id = instance.config.id.as_str(); + if instance.config.file_managed_params || ¶ms == read { + return; + } + if let Err(error) = super::startup::storable(&self.limits, ¶ms) { + tracing::warn!(module = id, %error, "Module's normalized params break the params rules; kept the stored params"); + return; + } + let operator = format!( + "module:{}", + instance.build.as_deref().unwrap_or(&instance.config.kind) + ); + let change = crate::modules::store::Change { + operator: &operator, + reason: "params migrated by the module", + at: chrono::Utc::now().to_rfc3339(), + expected_version: None, + }; + match self.store.set_global_if(id, read, params, &change).await { + Ok(Some(_)) => { + tracing::info!(module = id, %operator, "Module normalized its stored global params after it recovered; stored the migrated form") + } + Ok(None) => tracing::warn!( + module = id, + "Global params changed while the recovered module migrated them; kept the newer value, migration retries next start" + ), + Err(error) => { + tracing::warn!(module = id, %error, "Storing the recovered module's migrated params failed; migration retries next start") + } + } + } + + /// One health probe of every enabled instance: `Describe` under its timeout, with the startup + /// checks. An instance that started without them runs all of them here, the params that apply + /// included, before any call is let through, and stores the params its module migrated. A healthy module half-opens an open breaker so the next real call is sent. One + /// that does not answer counts as a failed call toward its breaker. One that answers with a + /// protocol version, capability or hook set this Guardian cannot work with opens its breaker + /// at once: its decisions are not trusted until a probe passes again. + pub async fn probe(&self) { + let Ok(rows) = self.rows().await else { + return; + }; + self.publish(&rows); + for instance in &self.instances { + if !Self::enabled_in(&rows, instance) { + continue; + } + let id = instance.config.id.as_str(); + let unchecked = self + .unchecked + .lock() + .is_ok_and(|unchecked| unchecked.contains(id)); + let healthy = if unchecked { + let read = Self::global_params_in(&rows, instance); + match crate::modules::registry::check(&instance.config, &instance.module, &read) + .await + { + Ok(checked) => { + self.store_recovered_migration(instance, &read, checked.params) + .await; + Ok(()) + } + Err(unhealthy) => Err(unhealthy), + } + } else { + crate::modules::registry::describe_healthy(&instance.config, &instance.module) + .await + .map(|_| ()) + }; + crate::modules::metrics::up(id, healthy.is_ok()); + match healthy { + Ok(()) => { + if unchecked { + if let Ok(mut unchecked) = self.unchecked.lock() { + unchecked.remove(id); + } + tracing::info!( + module = id, + "Policy module passed the startup checks it could not be reached for" + ); + } + self.breakers.probe_succeeded(id); + } + Err(Unhealthy::Unreachable(error)) => { + tracing::warn!(module = id, %error, "Policy module health probe failed"); + self.breakers.failed(id); + } + Err(Unhealthy::Incompatible(error) | Unhealthy::InvalidParams(error)) => { + tracing::warn!(module = id, %error, "Policy module cannot be used by this Guardian; its circuit is open until a probe passes"); + self.breakers.hold_open(id); + } + } + } + } + + /// Runs [`Self::probe`] every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` for the life of the server. + pub fn spawn_probe(self: Arc) -> tokio::task::JoinHandle<()> { + tokio::spawn(async move { + let mut interval = tokio::time::interval(self.limits.probe_interval); + interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); + let mut counted = tokio::time::Instant::now(); + loop { + interval.tick().await; + if counted.elapsed() >= ASSIGNMENT_REPORT_INTERVAL { + self.refresh_assignment_report().await; + counted = tokio::time::Instant::now(); + } + self.probe().await; + } + }) + } +} + +#[cfg(test)] +mod tests { + use std::time::Duration; + + use guardian_module_sdk::HookRequest; + + use super::super::*; + use crate::modules::breaker::CircuitState; + use crate::modules::catalog::{HookName, OnError}; + use crate::modules::testing::{Behaviour, StubModule, instance, pipeline}; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + fn hanging(id: &str, on_error: OnError, timeout: Duration) -> (Instance, Arc) { + let module = StubModule::new(Behaviour::Hang); + let mut hung = instance(id, &[HOOK], on_error, module.clone()); + hung.config.timeout = timeout; + (hung, module) + } + + async fn run(pipeline: &ModulePipeline) -> Result<(), GuardianError> { + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + } + + #[tokio::test] + async fn a_probe_publishes_the_state_gauges() { + let pipeline = pipeline(vec![instance( + "caps", + &[HookName::BeforeTransactionApproved], + OnError::Deny, + StubModule::allowing(), + )]); + let rows = pipeline.rows().await.unwrap(); + let recorder = crate::metrics::build_recorder(); + let handle = recorder.handle(); + metrics::with_local_recorder(&recorder, || pipeline.publish(&rows)); + let text = handle.render(); + for line in [ + "guardian_module_enabled{module=\"caps\"} 1", + "guardian_module_circuit_open{module=\"caps\"} 0", + "guardian_module_config_drift{module=\"caps\"} 0", + "guardian_module_over_budget_accounts 0", + "guardian_module_orphaned_assignments 0", + "guardian_module_catalog_info{catalog_hash=\"\"} 1", + ] { + assert!(text.contains(line), "{line} missing from:\n{text}"); + } + } + + #[tokio::test] + async fn a_module_that_turns_incompatible_is_not_trusted_until_a_probe_passes() { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.protocol_version = guardian_module_sdk::PROTOCOL_VERSION + 1; + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + Arc::new(stub), + )]); + run(&pipeline) + .await + .expect("the module allows until a probe finds it incompatible"); + pipeline.probe().await; + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + )); + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Open, + "it stays open while the probe keeps failing" + ); + } + + #[tokio::test] + async fn probes_a_module_does_not_answer_count_toward_its_breaker() { + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + Arc::new(Undescribed), + )]) + .with_limits(Limits { + breaker_failures: 2, + ..Limits::default() + }); + pipeline.probe().await; + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Open, + "no request had to find the module down" + ); + } + + #[tokio::test] + async fn a_healthy_probe_half_opens_and_a_failing_one_leaves_the_circuit_open() { + let healthy = crate::modules::testing::instance_with_params( + "caps", + &[HOOK], + Arc::new(guardian_module_sdk::policies::RecipientPolicy), + serde_json::json!({}), + ); + let (down, _) = hanging("screening", OnError::Deny, Duration::from_millis(20)); + let pipeline = ModulePipeline::from_instances(vec![healthy, down]).with_limits(Limits { + breaker_failures: 1, + ..Limits::default() + }); + pipeline.breakers().failed("caps"); + pipeline.breakers().failed("screening"); + pipeline.probe().await; + assert_eq!(pipeline.breakers().state("caps"), CircuitState::HalfOpen); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + } + + /// Allows every request but never answers `Describe`. + struct Undescribed; + + #[async_trait::async_trait] + impl guardian_module_sdk::Module for Undescribed { + async fn describe( + &self, + _: &guardian_module_sdk::DescribeRequest, + ) -> Result { + Err(guardian_module_sdk::ModuleError::Unavailable( + "no answer".into(), + )) + } + + async fn validate_params( + &self, + _: &[u8], + ) -> Result { + Ok(guardian_module_sdk::ParamsVerdict::ok()) + } + + async fn evaluate( + &self, + _: &HookRequest, + ) -> Result { + Ok(guardian_module_sdk::Decision::allow()) + } + } +} diff --git a/crates/server/src/modules/pipeline/startup.rs b/crates/server/src/modules/pipeline/startup.rs new file mode 100644 index 000000000..9cfd34511 --- /dev/null +++ b/crates/server/src/modules/pipeline/startup.rs @@ -0,0 +1,992 @@ +//! Startup reconciliation: the catalog file and the stored module state become the running +//! pipeline. It runs once per process, before any request, in this order: +//! +//! 1. The catalog's params are checked against the size cap. +//! 2. The stored instance rows are read and applied to the catalog: the stored enabled flag and +//! operator-managed global params replace the catalog's, except that an instance the catalog +//! requires is enabled ([`Stored::apply_to`]). +//! 3. The instances are built and checked against their modules +//! ([`Registry::instantiate`](crate::modules::registry::Registry::instantiate)). A failure here +//! stops startup before anything is written. +//! 4. The startup writes ([`StartupWrites`]): the catalog-required enables, the seeds of +//! instances new to this Guardian, and the params a module migrated. +//! 5. Instances whose module did not answer start with their breaker held open, and each health +//! probe runs their checks until they pass. + +use std::collections::{HashMap, HashSet}; +use std::sync::{Arc, RwLock}; + +use super::{Cache, ModulePipeline}; +use crate::modules::breaker::Breakers; +use crate::modules::catalog::{Catalog, contains_secret_reference}; +use crate::modules::limits::Limits; +use crate::modules::registry::{Instance, Instantiated, Registry}; +use crate::modules::store::{Change, InstanceRow, ModuleStore}; + +/// The rules every stored params value follows, applied to what a module returns as normalized +/// params: within the size cap and free of secret references. +pub(super) fn storable(limits: &Limits, params: &serde_json::Value) -> Result<(), String> { + limits.check_params_size(params)?; + if crate::modules::catalog::contains_secret_reference(params) { + return Err("normalized params contain a secret reference".into()); + } + Ok(()) +} + +/// The stored instance rows as startup found them, by module id. +struct Stored { + rows: HashMap, +} + +/// What the stored state changes in the catalog before the instances are built. +struct Applied { + /// Operator-managed global params that differ from the catalog's and apply instead. + effective: HashMap, + /// Instances whose stored seed differs from the catalog's params. + seed_drift: HashSet, + /// Instances stored as disabled that the catalog declares enabled and not + /// operator-disableable, so startup enables them. + enabled_by_catalog: Vec, + /// Instances whose params moved out of the catalog file: their catalog params apply now and + /// are stored in place of the empty placeholder a file-managed instance keeps. + adopted: Vec, +} + +impl Stored { + async fn read(store: &dyn ModuleStore) -> Result { + Ok(Self { + rows: store + .instances() + .await? + .into_iter() + .map(|row| (row.module_id.clone(), row)) + .collect(), + }) + } + + /// The instances this Guardian has run before. + fn known(&self) -> HashSet { + self.rows.keys().cloned().collect() + } + + fn contains(&self, module_id: &str) -> bool { + self.rows.contains_key(module_id) + } + + fn global_params(&self, module_id: &str) -> Option<&serde_json::Value> { + self.rows.get(module_id).map(|row| &row.global_params) + } + + /// Applies the stored state to every catalog instance it has a row for. The stored flag is + /// the switch, with one exception: an instance the catalog declares enabled and not + /// operator-disableable cannot be left off by a disable that was allowed under an earlier + /// catalog, and switching it on only tightens policy. + fn apply_to(&self, catalog: &mut Catalog) -> Applied { + let mut applied = Applied { + effective: HashMap::new(), + seed_drift: HashSet::new(), + enabled_by_catalog: Vec::new(), + adopted: Vec::new(), + }; + for config in &mut catalog.instances { + let Some(row) = self.rows.get(&config.id) else { + continue; + }; + if !config.file_managed_params && row.seeded_params != config.params { + applied.seed_drift.insert(config.id.clone()); + } + let catalog_requires_it = + !row.enabled && config.catalog_enabled && !config.operator_can_disable; + if catalog_requires_it { + tracing::warn!(module = %config.id, "Stored flag disables an instance the catalog declares enabled and not operator-disableable; enabling it"); + applied.enabled_by_catalog.push(config.id.clone()); + } else if row.enabled != config.catalog_enabled { + tracing::warn!(module = %config.id, enabled = row.enabled, "Catalog `enabled` differs from the stored runtime flag; the stored flag applies"); + } + config.enabled = row.enabled || catalog_requires_it; + let was_file_managed = contains_secret_reference(&row.seeded_params); + let placeholder = row.global_params == serde_json::json!({}); + if config.file_managed_params { + if !placeholder { + tracing::warn!(module = %config.id, "Params now come from the catalog file (they reference secrets); the operator-managed global params stored for this instance no longer apply"); + } + } else if was_file_managed && placeholder { + tracing::warn!(module = %config.id, "Params moved out of the catalog file; the catalog params apply and are stored as the operator-managed global params"); + applied.adopted.push(config.id.clone()); + } else if row.global_params != config.params { + tracing::warn!(module = %config.id, "Catalog params differ from the operator-managed global params; the stored params apply"); + applied + .effective + .insert(config.id.clone(), row.global_params.clone()); + } + } + applied + } +} + +/// The writes startup makes once the instances are built, each recorded in the params history +/// with startup as its operator. +struct StartupWrites<'a> { + store: &'a dyn ModuleStore, + limits: &'a Limits, + now: &'a str, +} + +impl StartupWrites<'_> { + fn change<'c>(&self, operator: &'c str, reason: &'c str) -> Change<'c> { + Change { + operator, + reason, + at: self.now.to_string(), + expected_version: None, + } + } + + async fn enable_required(&self, module_ids: &[String]) -> Result<(), String> { + for module_id in module_ids { + self.store + .set_enabled( + module_id, + true, + &self.change( + "catalog", + "the catalog declares the instance enabled and not operator-disableable", + ), + ) + .await?; + } + Ok(()) + } + + /// Seeds every catalog instance without a stored row: with the module's normalized form of + /// the catalog params when it is storable, an empty object for file-managed params (whose + /// seed records the catalog params as written, secret references included, so a later + /// start can tell the params were file-managed). + async fn seed_new( + &self, + catalog: &Catalog, + stored: &Stored, + normalized: &HashMap, + ) -> Result<(), String> { + for config in catalog + .instances + .iter() + .filter(|config| !stored.contains(&config.id)) + { + let (seed, catalog) = if config.file_managed_params { + (serde_json::json!({}), config.params.clone()) + } else { + let seed = normalized + .get(&config.id) + .filter(|params| storable(self.limits, params).is_ok()) + .unwrap_or(&config.params) + .clone(); + (seed, config.params.clone()) + }; + self.store + .seed_instance(&config.id, config.enabled, &seed, &catalog, self.now) + .await?; + } + Ok(()) + } + + /// Stores the catalog params of instances whose params moved out of the catalog file (in the + /// module's normalized form when it is storable), only while the stored global params are + /// still the empty placeholder, so an operator's newer write is never overwritten. + async fn store_adopted( + &self, + catalog: &Catalog, + adopted: &[String], + normalized: &HashMap, + ) -> Result<(), String> { + for config in catalog + .instances + .iter() + .filter(|config| adopted.contains(&config.id)) + { + let params = normalized + .get(&config.id) + .filter(|params| storable(self.limits, params).is_ok()) + .unwrap_or(&config.params); + if let Err(error) = storable(self.limits, params) { + tracing::warn!(module = %config.id, %error, "Catalog params break the params rules; they apply but are not stored"); + continue; + } + self.store + .set_global_if( + &config.id, + &serde_json::json!({}), + params.clone(), + &self.change("catalog", "params moved out of the catalog file"), + ) + .await?; + } + Ok(()) + } + + /// Stores the form a module normalized stored global params into, only while they are still + /// the value startup read, so an operator's newer write is never overwritten. Adopted + /// instances were stored by [`StartupWrites::store_adopted`] already. + async fn store_migrations( + &self, + instances: &[Instance], + stored: &Stored, + normalized: &HashMap, + adopted: &[String], + ) -> Result<(), String> { + for instance in instances.iter().filter(|instance| { + !instance.config.file_managed_params && !adopted.contains(&instance.config.id) + }) { + let (Some(params), Some(read)) = ( + normalized.get(&instance.config.id), + stored.global_params(&instance.config.id), + ) else { + continue; + }; + if let Err(error) = storable(self.limits, params) { + tracing::warn!(module = %instance.config.id, %error, "Module's normalized params break the params rules; kept the stored params"); + continue; + } + let operator = format!( + "module:{}", + instance.build.as_deref().unwrap_or(&instance.config.kind) + ); + let migrated = self + .store + .set_global_if( + &instance.config.id, + read, + params.clone(), + &self.change(&operator, "params migrated by the module"), + ) + .await?; + if migrated.is_some() { + tracing::info!(module = %instance.config.id, %operator, "Module normalized its stored global params; stored the migrated form"); + } else { + tracing::warn!(module = %instance.config.id, "Global params changed while the module migrated them; kept the newer value, migration retries next start"); + } + } + Ok(()) + } +} + +impl ModulePipeline { + /// Reconciles the catalog with the stored state and builds the pipeline (see the module + /// documentation for the steps). + pub async fn new( + network_id: &'static str, + mut catalog: Catalog, + registry: &Registry, + store: Arc, + now: String, + limits: Limits, + ) -> Result { + for config in &catalog.instances { + limits + .check_params_size(&config.params) + .map_err(|e| format!("module {}: catalog {e}", config.id))?; + } + let stored = Stored::read(store.as_ref()).await?; + let applied = stored.apply_to(&mut catalog); + let Instantiated { + instances, + normalized, + unreachable, + } = registry + .instantiate(&catalog, &applied.effective, &stored.known()) + .await?; + let writes = StartupWrites { + store: store.as_ref(), + limits: &limits, + now: &now, + }; + writes.enable_required(&applied.enabled_by_catalog).await?; + writes.seed_new(&catalog, &stored, &normalized).await?; + writes + .store_adopted(&catalog, &applied.adopted, &normalized) + .await?; + writes + .store_migrations(&instances, &stored, &normalized, &applied.adopted) + .await?; + let breakers = Arc::new(Breakers::new(limits.breaker_failures)); + for module_id in &unreachable { + breakers.hold_open(module_id); + } + Ok(Self { + instances, + store, + cache: RwLock::new(Cache::default()), + breakers, + unchecked: std::sync::Mutex::new(unreachable), + limits, + catalog_hash: catalog.hash, + network_id, + seed_drift: applied.seed_drift, + assignment_report: std::sync::Mutex::new((0, 0)), + }) + } +} + +#[cfg(test)] +mod tests { + use guardian_module_sdk::HookRequest; + + use super::super::*; + use crate::modules::breaker::CircuitState; + use crate::modules::catalog::{Catalog, HookName}; + use crate::modules::registry::Registry; + use crate::modules::store::ModuleStore; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + async fn run(pipeline: &ModulePipeline) -> Result<(), GuardianError> { + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + } + + fn caps_catalog(params: &str) -> Catalog { + Catalog::parse( + &format!( + r#" +[[module]] +id = "caps" +kind = "spending-limit" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = {params} +"# + ), + None, + ) + .unwrap() + } + + #[tokio::test] + async fn invalid_catalog_params_stop_startup_without_seeding_them() { + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let registry = Registry::first_party(); + let now = "2026-10-15T00:00:00Z".to_string(); + let started = ModulePipeline::new( + "local", + caps_catalog(r#"{ max_per_transactionx = {} }"#), + ®istry, + store.clone(), + now.clone(), + crate::modules::limits::Limits::default(), + ) + .await; + assert!(started.is_err()); + assert!(store.instances().await.unwrap().is_empty()); + + let fixed = caps_catalog( + r#"{ max_per_transaction = { "0x0000000000000000000000000000aa" = "5" } }"#, + ); + let started = ModulePipeline::new( + "local", + fixed, + ®istry, + store.clone(), + now, + crate::modules::limits::Limits::default(), + ) + .await + .expect("the corrected catalog starts"); + assert!( + started.instances()[0] + .build + .as_deref() + .is_some_and(|build| build.starts_with("spending-limit")) + ); + assert_eq!(store.instances().await.unwrap().len(), 1); + } + + #[tokio::test] + async fn stored_params_not_the_stale_catalog_seed_are_checked_at_startup() { + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let registry = Registry::first_party(); + let now = "2026-10-15T00:00:00Z".to_string(); + store + .seed_instance( + "caps", + true, + &serde_json::json!({ "max_per_transaction": {} }), + &serde_json::json!({ "max_per_transaction": {} }), + &now, + ) + .await + .unwrap(); + ModulePipeline::new( + "local", + caps_catalog(r#"{ max_per_transactionx = {} }"#), + ®istry, + store.clone(), + now.clone(), + crate::modules::limits::Limits::default(), + ) + .await + .expect("the stored params apply, so the stale seed is not checked"); + + store + .set_global( + "caps", + serde_json::json!({ "unknown": true }), + &crate::modules::store::Change { + operator: "0xop", + reason: "test", + at: now.clone(), + expected_version: None, + }, + ) + .await + .unwrap(); + let valid_seed = caps_catalog(r#"{ max_per_transaction = {} }"#); + assert!( + ModulePipeline::new( + "local", + valid_seed, + ®istry, + store, + now, + crate::modules::limits::Limits::default() + ) + .await + .is_err() + ); + } + + #[tokio::test] + async fn normalized_params_that_break_the_params_rules_are_not_stored() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + let catalog = Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 5 } +"#, + None, + ) + .unwrap(); + for normalized in [ + serde_json::json!({ "new_name": "x".repeat(200) }), + serde_json::json!({ "key": { "$secret": "vendor-key" } }), + ] { + let mut stub = ProtocolStub::new(); + stub.normalized = Some(normalized.clone()); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + ModulePipeline::new( + "local", + catalog.clone(), + ®istry, + store.clone(), + "2026-10-16T00:00:00Z".to_string(), + crate::modules::limits::Limits { + params_max_bytes: 100, + ..Default::default() + }, + ) + .await + .unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "old_name": 5 }), + "kept the catalog params instead of {normalized}" + ); + } + } + + #[tokio::test] + async fn catalog_params_a_module_normalizes_are_not_reported_as_drift() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + let catalog = Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 5 } +"#, + None, + ) + .unwrap(); + let mut stub = ProtocolStub::new(); + stub.normalized = Some(serde_json::json!({ "new_name": 5 })); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let start = || { + ModulePipeline::new( + "local", + catalog.clone(), + ®istry, + store.clone(), + "2026-10-16T00:00:00Z".to_string(), + crate::modules::limits::Limits::default(), + ) + }; + start().await.unwrap(); + let row = store.instances().await.unwrap().remove(0); + assert_eq!(row.global_params, serde_json::json!({ "new_name": 5 })); + assert_eq!( + row.seeded_params, + serde_json::json!({ "old_name": 5 }), + "the seed is the catalog value as written" + ); + let restarted = start().await.unwrap(); + assert!( + restarted.seed_drift.is_empty(), + "an unchanged catalog is not drift" + ); + } + + #[tokio::test] + async fn params_moved_out_of_the_catalog_file_apply_and_are_stored() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + let catalog = |params: &str| { + Catalog::parse( + &format!( + r#" +[[module]] +id = "vendor" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = {params} +"# + ), + None, + ) + .unwrap() + }; + let mut registry = Registry::first_party(); + registry + .register( + "protocol-stub", + Arc::new(FixedFactory(Arc::new(ProtocolStub::new()))), + ) + .unwrap(); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let start = |catalog: Catalog| { + ModulePipeline::new( + "local", + catalog, + ®istry, + store.clone(), + "2026-10-16T00:00:00Z".to_string(), + crate::modules::limits::Limits::default(), + ) + }; + + struct VendorKey; + #[async_trait::async_trait] + impl crate::modules::secrets::SecretSource for VendorKey { + async fn read(&self, _name: &str) -> Result { + Ok(secrecy::SecretString::from("vendor secret".to_string())) + } + } + let mut file_managed = catalog(r#"{ api_key = { "$secret" = "vendor-key" }, cap = 5 }"#); + file_managed.resolve_secrets(Some(&VendorKey)).await; + start(file_managed).await.unwrap(); + let row = store.instances().await.unwrap().remove(0); + assert_eq!(row.global_params, serde_json::json!({}), "the placeholder"); + + start(catalog("{ cap = 5 }")).await.unwrap(); + let row = store.instances().await.unwrap().remove(0); + assert_eq!( + row.global_params, + serde_json::json!({ "cap": 5 }), + "the catalog params apply and operators can now change them through the API" + ); + + start(catalog("{ cap = 7 }")).await.unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "cap": 5 }), + "from then on the stored params are operator-managed and the catalog only seeds" + ); + } + + const OUTAGE_CATALOG: &str = r#" +[[module]] +id = "screening" +kind = "outage-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +"#; + + async fn start_with( + module: Arc, + catalog: &str, + store: Arc, + ) -> Result { + let mut registry = Registry::first_party(); + registry + .register( + "outage-stub", + Arc::new(crate::modules::testing::FixedFactory(module)), + ) + .unwrap(); + ModulePipeline::new( + "local", + Catalog::parse(catalog, None).unwrap(), + ®istry, + store, + "2026-11-10T00:00:00Z".to_string(), + crate::modules::limits::Limits::default(), + ) + .await + } + + #[tokio::test] + async fn a_known_instance_whose_module_is_down_starts_unavailable_and_recovers_on_a_probe() { + use std::sync::atomic::Ordering; + let module = crate::modules::testing::Outage::new(false); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + start_with(module.clone(), OUTAGE_CATALOG, store.clone()) + .await + .expect("the first start passes the checks and makes the instance known"); + + module.set_down(true); + let pipeline = start_with(module.clone(), OUTAGE_CATALOG, store) + .await + .expect("a module outage does not keep the Guardian from restarting"); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + assert!( + matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + ), + "its accounts are refused meanwhile, not approved" + ); + + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Open, + "still down" + ); + + module.set_down(false); + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::HalfOpen + ); + run(&pipeline).await.expect("the module decides again"); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); + assert_eq!(module.evaluations.load(Ordering::SeqCst), 1); + } + + #[tokio::test] + async fn a_module_that_recovers_from_an_outage_has_its_migrated_params_stored() { + let module = crate::modules::testing::Outage::new(false); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + start_with(module.clone(), OUTAGE_CATALOG, store.clone()) + .await + .unwrap(); + module.set_down(true); + let pipeline = start_with(module.clone(), OUTAGE_CATALOG, store.clone()) + .await + .unwrap(); + + let migrated = serde_json::json!({ "lists": ["ofac"] }); + *module.normalized.lock().unwrap() = Some(migrated.clone()); + module.set_down(false); + pipeline.probe().await; + + assert_eq!(store.instances().await.unwrap()[0].global_params, migrated); + let history = store.history("screening", None, 10).await.unwrap(); + assert_eq!(history[0].new, migrated); + assert_eq!(history[0].reason, "params migrated by the module"); + assert!( + history[0].operator.starts_with("module:"), + "{}", + history[0].operator + ); + + pipeline.probe().await; + assert_eq!( + store.history("screening", None, 10).await.unwrap().len(), + history.len(), + "a checked instance is not migrated again" + ); + } + + #[tokio::test] + async fn an_instance_new_to_this_guardian_must_answer_at_startup() { + let module = crate::modules::testing::Outage::new(true); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let refused = start_with(module, OUTAGE_CATALOG, store.clone()) + .await + .err() + .expect("a wrong endpoint in a new catalog entry is found at deploy time"); + assert!(refused.contains("screening"), "{refused}"); + assert!(store.instances().await.unwrap().is_empty()); + } + + #[tokio::test] + async fn a_known_instance_that_answers_incompatibly_still_stops_startup() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + const CATALOG: &str = r#" +[[module]] +id = "screening" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +"#; + let start = |protocol_version: u32, store: Arc| async move { + let mut stub = ProtocolStub::new(); + stub.protocol_version = protocol_version; + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + ModulePipeline::new( + "local", + Catalog::parse(CATALOG, None).unwrap(), + ®istry, + store, + "2026-11-10T00:00:00Z".to_string(), + crate::modules::limits::Limits::default(), + ) + .await + }; + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + start(guardian_module_sdk::PROTOCOL_VERSION, store.clone()) + .await + .unwrap(); + assert!( + start(guardian_module_sdk::PROTOCOL_VERSION + 1, store) + .await + .is_err(), + "only a module that does not answer may start unavailable" + ); + } + + #[tokio::test] + async fn an_instance_the_catalog_requires_is_enabled_at_startup() { + let disabled_in_store = || async { + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + store + .seed_instance( + "screening", + false, + &serde_json::json!({}), + &serde_json::json!({}), + "t0", + ) + .await + .unwrap(); + store + }; + + let store = disabled_in_store().await; + let pipeline = start_with( + crate::modules::testing::Outage::new(false), + OUTAGE_CATALOG, + store.clone(), + ) + .await + .unwrap(); + assert!( + store.instances().await.unwrap()[0].enabled, + "enabled and not operator-disableable in the catalog: a stored disable does not stand" + ); + let history = store.history("screening", None, 10).await.unwrap(); + assert_eq!(history[0].operator, "catalog"); + assert_eq!(history[0].new, serde_json::json!({ "enabled": true })); + assert!( + pipeline + .applies(HookName::BeforeTransactionApproved, "0xacc") + .await + .unwrap() + ); + + let store = disabled_in_store().await; + let disableable = format!("{OUTAGE_CATALOG}operator_can_disable = true\n"); + let pipeline = start_with( + crate::modules::testing::Outage::new(false), + &disableable, + store.clone(), + ) + .await + .unwrap(); + assert!( + !store.instances().await.unwrap()[0].enabled, + "an operator may hold a disableable instance off, so the stored flag stands" + ); + assert!( + !pipeline + .applies(HookName::BeforeTransactionApproved, "0xacc") + .await + .unwrap() + ); + } + + #[tokio::test] + async fn startup_stores_params_the_module_migrated() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + let catalog = || { + Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 5 } +"#, + None, + ) + .unwrap() + }; + let mut stub = ProtocolStub::new(); + stub.normalized = Some(serde_json::json!({ "new_name": 5 })); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let now = "2026-10-16T00:00:00Z".to_string(); + + ModulePipeline::new( + "local", + catalog(), + ®istry, + store.clone(), + now.clone(), + crate::modules::limits::Limits::default(), + ) + .await + .unwrap(); + let seeded = store.instances().await.unwrap(); + assert_eq!( + seeded[0].global_params, + serde_json::json!({ "new_name": 5 }), + "a new instance is seeded in the migrated shape" + ); + + store + .set_global( + "migrating", + serde_json::json!({ "old_name": 7 }), + &crate::modules::store::Change { + operator: "0xop", + reason: "old shape", + at: now.clone(), + expected_version: None, + }, + ) + .await + .unwrap(); + ModulePipeline::new( + "local", + catalog(), + ®istry, + store.clone(), + now, + crate::modules::limits::Limits::default(), + ) + .await + .unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "new_name": 5 }) + ); + let last = store.history("migrating", None, 1).await.unwrap().remove(0); + assert_eq!(last.operator, "module:protocol-stub 1"); + assert_eq!(last.reason, "params migrated by the module"); + assert_eq!(last.previous, serde_json::json!({ "old_name": 7 })); + } + + /// An operator lowers the stored params while the module is migrating them at startup; + /// the migration must not replace the operator's newer value with its stale result. + #[tokio::test] + async fn a_startup_migration_never_overwrites_a_newer_operator_write() { + use crate::modules::testing::{FixedFactory, ProtocolStub, RacingStore, RacingWrite}; + let catalog = Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 1000 } +"#, + None, + ) + .unwrap(); + let mut stub = ProtocolStub::new(); + stub.normalized = Some(serde_json::json!({ "new_name": 1000 })); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store = Arc::new(RacingStore::new()); + store + .inner + .seed_instance( + "migrating", + true, + &serde_json::json!({ "old_name": 1000 }), + &serde_json::json!({ "old_name": 1000 }), + "2026-10-16T00:00:00Z", + ) + .await + .unwrap(); + *store.before_set_global_if.lock().unwrap() = vec![RacingWrite::Global( + "migrating", + serde_json::json!({ "new_name": 100 }), + )]; + + ModulePipeline::new( + "local", + catalog, + ®istry, + store.clone(), + "2026-10-16T00:00:02Z".into(), + crate::modules::limits::Limits::default(), + ) + .await + .unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "new_name": 100 }), + "the operator's cap of 100 stays" + ); + let last = store.history("migrating", None, 1).await.unwrap().remove(0); + assert_eq!( + last.operator, "0xracing-operator", + "no migration entry after it" + ); + } +} diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs new file mode 100644 index 000000000..c8bf24c17 --- /dev/null +++ b/crates/server/src/modules/postgres_store.rs @@ -0,0 +1,1287 @@ +//! The module tables on Postgres. + +use async_trait::async_trait; +use chrono::{DateTime, Utc}; +use diesel::QueryableByName; +use diesel::sql_types::{BigInt, Bool, Integer, Jsonb, Nullable, Text, Timestamptz}; +use diesel_async::pooled_connection::deadpool::Pool; +use diesel_async::scoped_futures::ScopedFutureExt; +use diesel_async::{AsyncConnection, AsyncPgConnection, RunQueryDsl}; + +use super::store::{ + AccountModule, AccountParamsRow, Assigned, Change, HistoryEntry, InstanceRow, ModuleSnapshot, + ModuleStore, ParamsKind, WriteError, assignment_changes, +}; + +pub struct PgModuleStore { + pool: Pool, +} + +impl PgModuleStore { + pub fn new(pool: Pool) -> Self { + Self { pool } + } + + async fn conn( + &self, + ) -> Result, String> { + self.pool + .get() + .await + .map_err(|e| format!("module store pool: {e}")) + } +} + +fn at(change: &Change<'_>) -> Result, String> { + DateTime::parse_from_rfc3339(&change.at) + .map(|at| at.with_timezone(&Utc)) + .map_err(|e| format!("invalid change time: {e}")) +} + +#[derive(QueryableByName)] +struct InstanceSql { + #[diesel(sql_type = Text)] + module_id: String, + #[diesel(sql_type = Bool)] + enabled: bool, + #[diesel(sql_type = Jsonb)] + global_params: serde_json::Value, + #[diesel(sql_type = Jsonb)] + seeded_params: serde_json::Value, + #[diesel(sql_type = Timestamptz)] + updated_at: DateTime, + #[diesel(sql_type = Text)] + updated_by: String, +} + +#[derive(QueryableByName)] +struct AccountParamsSql { + #[diesel(sql_type = Text)] + account_id: String, + #[diesel(sql_type = Text)] + module_id: String, + #[diesel(sql_type = Text)] + kind: String, + #[diesel(sql_type = Integer)] + position: i32, + #[diesel(sql_type = Jsonb)] + params: serde_json::Value, + #[diesel(sql_type = Timestamptz)] + updated_at: DateTime, + #[diesel(sql_type = Text)] + updated_by: String, +} + +#[derive(QueryableByName)] +struct HistorySql { + #[diesel(sql_type = BigInt)] + id: i64, + #[diesel(sql_type = BigInt)] + version: i64, + #[diesel(sql_type = Text)] + module_id: String, + #[diesel(sql_type = Nullable)] + account_id: Option, + #[diesel(sql_type = Jsonb)] + previous_params: serde_json::Value, + #[diesel(sql_type = Jsonb)] + new_params: serde_json::Value, + #[diesel(sql_type = Text)] + operator: String, + #[diesel(sql_type = Text)] + reason: String, + #[diesel(sql_type = Timestamptz)] + changed_at: DateTime, +} + +#[derive(QueryableByName)] +struct VersionSql { + #[diesel(sql_type = BigInt)] + version: i64, +} + +#[derive(QueryableByName)] +struct ParamsSql { + #[diesel(sql_type = Jsonb)] + params: serde_json::Value, +} + +impl From for WriteError { + fn from(error: diesel::result::Error) -> Self { + WriteError::Storage(error.to_string()) + } +} + +/// Refuses an operator write made against `expected` once the rows it locked have moved past +/// it: `version` is the version this write commits as, so the rows were at `version - 1`. +fn check(version: i64, expected: Option) -> Result<(), WriteError> { + let current = (version - 1) as u64; + match expected { + Some(expected) if expected != current => Err(WriteError::Stale { current }), + _ => Ok(()), + } +} + +/// Takes the instance write lock and returns the instance params version this write commits +/// as. +async fn bump(conn: &mut AsyncPgConnection) -> Result { + let rows: Vec = diesel::sql_query( + "UPDATE module_state_version SET version = version + 1 RETURNING version", + ) + .load(conn) + .await?; + rows.into_iter() + .next() + .map(|row| row.version) + .ok_or(diesel::result::Error::NotFound) +} + +/// Takes the write lock of one account's rows and returns the account params version this +/// write commits as. Writes to other accounts and to the instance rows do not wait for it. +async fn bump_account( + conn: &mut AsyncPgConnection, + account_id: &str, +) -> Result { + let rows: Vec = diesel::sql_query( + "INSERT INTO module_account_version (account_id, version) VALUES ($1, 1) \ + ON CONFLICT (account_id) DO UPDATE SET version = module_account_version.version + 1 \ + RETURNING version", + ) + .bind::(account_id) + .load(conn) + .await?; + rows.into_iter() + .next() + .map(|row| row.version) + .ok_or(diesel::result::Error::NotFound) +} + +#[allow(clippy::too_many_arguments)] +async fn append( + conn: &mut AsyncPgConnection, + version: i64, + module_id: &str, + account_id: Option<&str>, + previous: &serde_json::Value, + new: &serde_json::Value, + change: &Change<'_>, + changed_at: DateTime, +) -> Result { + diesel::sql_query( + "INSERT INTO module_params_history \ + (version, module_id, account_id, previous_params, new_params, operator, reason, \ + changed_at) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)", + ) + .bind::(version) + .bind::(module_id) + .bind::, _>(account_id) + .bind::(previous) + .bind::(new) + .bind::(change.operator) + .bind::(change.reason) + .bind::(changed_at) + .execute(conn) + .await +} + +fn account_params_row(row: AccountParamsSql) -> Result { + Ok(AccountParamsRow { + account_id: row.account_id, + module_id: row.module_id, + kind: ParamsKind::parse(&row.kind)?, + position: row.position, + params: row.params, + updated_at: row.updated_at.to_rfc3339(), + updated_by: row.updated_by, + }) +} + +diesel::define_sql_function! { + /// Typed so the statement is prepared once per connection: one module evaluation is one + /// call (see the migration for what it returns). + fn guardian_module_snapshot( + account_id: Text, + cached_version: Nullable, + ) -> Record<(BigInt, BigInt, Nullable, Jsonb)>; +} + +diesel::define_sql_function! { + /// Typed so the statement is prepared once per connection: the default-module copy of a + /// first registration is one call, which locks only that account's version row, for that + /// call only (see the migration). + fn guardian_module_seed_assignment( + account_id: Text, + modules: Jsonb, + operator: Text, + reason: Text, + changed_at: Timestamptz, + ) -> Nullable; +} + +#[async_trait] +impl ModuleStore for PgModuleStore { + async fn seed_instance( + &self, + module_id: &str, + enabled: bool, + params: &serde_json::Value, + catalog_params: &serde_json::Value, + at_text: &str, + ) -> Result<(), String> { + let changed_at = DateTime::parse_from_rfc3339(at_text) + .map(|at| at.with_timezone(&Utc)) + .map_err(|e| format!("invalid seed time: {e}"))?; + let mut conn = self.conn().await?; + let (module_id, params, catalog_params) = ( + module_id.to_string(), + params.clone(), + catalog_params.clone(), + ); + let seeded = conn + .transaction::<(), diesel::result::Error, _>(|conn| { + async move { + let version = bump(conn).await?; + let inserted = diesel::sql_query( + "INSERT INTO module_instances \ + (module_id, enabled, global_params, seeded_params, updated_at, updated_by) \ + VALUES ($1, $2, $3, $4, $5, 'catalog') ON CONFLICT (module_id) DO NOTHING", + ) + .bind::(&module_id) + .bind::(enabled) + .bind::(¶ms) + .bind::(&catalog_params) + .bind::(changed_at) + .execute(conn) + .await?; + if inserted == 0 { + return Err(diesel::result::Error::RollbackTransaction); + } + let change = Change { + operator: "catalog", + reason: "seeded from the catalog file", + at: String::new(), + expected_version: None, + }; + append( + conn, + version, + &module_id, + None, + &serde_json::Value::Null, + ¶ms, + &change, + changed_at, + ) + .await?; + Ok(()) + } + .scope_boxed() + }) + .await; + match seeded { + Ok(()) | Err(diesel::result::Error::RollbackTransaction) => Ok(()), + Err(e) => Err(format!("seed module {e}")), + } + } + + async fn instances(&self) -> Result, String> { + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query( + "SELECT module_id, enabled, global_params, seeded_params, updated_at, updated_by \ + FROM module_instances ORDER BY module_id", + ) + .load(&mut conn) + .await + .map_err(|e| format!("module instances: {e}"))?; + Ok(rows + .into_iter() + .map(|row| InstanceRow { + module_id: row.module_id, + enabled: row.enabled, + global_params: row.global_params, + seeded_params: row.seeded_params, + updated_at: row.updated_at.to_rfc3339(), + updated_by: row.updated_by, + }) + .collect()) + } + + async fn set_enabled( + &self, + module_id: &str, + enabled: bool, + change: &Change<'_>, + ) -> Result { + #[derive(QueryableByName)] + struct EnabledSql { + #[diesel(sql_type = Bool)] + enabled: bool, + } + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let module_id = module_id.to_string(); + conn.transaction::(|conn| { + async move { + let version = bump(conn).await?; + let previous: Vec = diesel::sql_query( + "SELECT enabled FROM module_instances WHERE module_id = $1 FOR UPDATE", + ) + .bind::(&module_id) + .load(conn) + .await?; + let previous = previous + .into_iter() + .next() + .ok_or(diesel::result::Error::NotFound)? + .enabled; + diesel::sql_query( + "UPDATE module_instances SET enabled = $2, updated_at = $3, updated_by = $4 \ + WHERE module_id = $1", + ) + .bind::(&module_id) + .bind::(enabled) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + append( + conn, + version, + &module_id, + None, + &serde_json::json!({ "enabled": previous }), + &serde_json::json!({ "enabled": enabled }), + change, + changed_at, + ) + .await?; + Ok(version) + } + .scope_boxed() + }) + .await + .map(|version| version as u64) + .map_err(|e| format!("set enabled: {e}")) + } + + async fn set_global( + &self, + module_id: &str, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result { + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let module_id = module_id.to_string(); + conn.transaction::(|conn| { + async move { + let version = bump(conn).await?; + check(version, change.expected_version)?; + let previous: Vec = diesel::sql_query( + "SELECT global_params AS params FROM module_instances \ + WHERE module_id = $1 FOR UPDATE", + ) + .bind::(&module_id) + .load(conn) + .await?; + let previous = previous + .into_iter() + .next() + .map(|row| row.params) + .unwrap_or_default(); + diesel::sql_query( + "INSERT INTO module_instances \ + (module_id, enabled, global_params, seeded_params, updated_at, updated_by) \ + VALUES ($1, TRUE, $2, $2, $3, $4) ON CONFLICT (module_id) DO UPDATE SET \ + global_params = EXCLUDED.global_params, updated_at = EXCLUDED.updated_at, \ + updated_by = EXCLUDED.updated_by", + ) + .bind::(&module_id) + .bind::(¶ms) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + append( + conn, version, &module_id, None, &previous, ¶ms, change, changed_at, + ) + .await?; + Ok(version) + } + .scope_boxed() + }) + .await + .map(|version| version as u64) + .map_err(|e| e.context("set global params")) + } + + async fn set_global_if( + &self, + module_id: &str, + expected: &serde_json::Value, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result, String> { + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let (module_id, expected) = (module_id.to_string(), expected.clone()); + let written = conn + .transaction::(|conn| { + async move { + let version = bump(conn).await?; + let current: Vec = diesel::sql_query( + "SELECT global_params AS params FROM module_instances \ + WHERE module_id = $1 FOR UPDATE", + ) + .bind::(&module_id) + .load(conn) + .await?; + let Some(previous) = current.into_iter().next().map(|row| row.params) else { + return Err(diesel::result::Error::RollbackTransaction); + }; + if previous != expected { + return Err(diesel::result::Error::RollbackTransaction); + } + diesel::sql_query( + "UPDATE module_instances SET global_params = $2, updated_at = $3, \ + updated_by = $4 WHERE module_id = $1", + ) + .bind::(&module_id) + .bind::(¶ms) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + append( + conn, version, &module_id, None, &previous, ¶ms, change, changed_at, + ) + .await?; + Ok(version) + } + .scope_boxed() + }) + .await; + match written { + Ok(version) => Ok(Some(version as u64)), + Err(diesel::result::Error::RollbackTransaction) => Ok(None), + Err(e) => Err(format!("set global params: {e}")), + } + } + + async fn account_params(&self, account_id: &str) -> Result, String> { + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query( + "SELECT account_id, module_id, kind, position, params, updated_at, updated_by \ + FROM module_account_params WHERE account_id = $1 ORDER BY position, module_id", + ) + .bind::(account_id) + .load(&mut conn) + .await + .map_err(|e| format!("account module params: {e}"))?; + rows.into_iter().map(account_params_row).collect() + } + + async fn snapshot( + &self, + account_id: &str, + cached_version: Option, + ) -> Result { + let mut conn = self.conn().await?; + let (instance_version, account_version, instances, account_params): ( + i64, + i64, + Option, + serde_json::Value, + ) = diesel::select(guardian_module_snapshot( + account_id, + cached_version.map(|version| version as i64), + )) + .get_result(&mut conn) + .await + .map_err(|e| format!("module snapshot: {e}"))?; + Ok(ModuleSnapshot { + instance_version: instance_version as u64, + account_version: account_version as u64, + instances: instances + .map(serde_json::from_value) + .transpose() + .map_err(|e| format!("module snapshot instances: {e}"))?, + account_params: serde_json::from_value(account_params) + .map_err(|e| format!("module snapshot account rows: {e}"))?, + }) + } + + async fn account_modules(&self) -> Result, String> { + #[derive(QueryableByName)] + struct AccountModuleSql { + #[diesel(sql_type = Text)] + account_id: String, + #[diesel(sql_type = Text)] + module_id: String, + #[diesel(sql_type = Text)] + kind: String, + } + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query( + "SELECT account_id, module_id, kind FROM module_account_params \ + ORDER BY account_id, position, module_id", + ) + .load(&mut conn) + .await + .map_err(|e| format!("account modules: {e}"))?; + rows.into_iter() + .map(|row| { + Ok(AccountModule { + account_id: row.account_id, + module_id: row.module_id, + kind: ParamsKind::parse(&row.kind)?, + }) + }) + .collect() + } + + async fn set_layer( + &self, + account_id: &str, + module_id: &str, + params: Option, + change: &Change<'_>, + ) -> Result { + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let (account_id, module_id) = (account_id.to_string(), module_id.to_string()); + conn.transaction::(|conn| { + async move { + let version = bump_account(conn, &account_id).await?; + check(version, change.expected_version)?; + let previous: Vec = diesel::sql_query( + "DELETE FROM module_account_params WHERE account_id = $1 AND module_id = $2 \ + AND kind = 'layer' RETURNING params", + ) + .bind::(&account_id) + .bind::(&module_id) + .load(conn) + .await?; + let previous = previous + .into_iter() + .next() + .map(|row| row.params) + .unwrap_or_default(); + if let Some(params) = ¶ms { + diesel::sql_query( + "INSERT INTO module_account_params \ + (account_id, module_id, kind, position, params, updated_at, updated_by) \ + VALUES ($1, $2, 'layer', 0, $3, $4, $5)", + ) + .bind::(&account_id) + .bind::(&module_id) + .bind::(params) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + } + let new = params.unwrap_or_default(); + append( + conn, + version, + &module_id, + Some(&account_id), + &previous, + &new, + change, + changed_at, + ) + .await?; + Ok(version) + } + .scope_boxed() + }) + .await + .map(|version| version as u64) + .map_err(|e| e.context("set account layer")) + } + + async fn set_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result { + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let account_id = account_id.to_string(); + conn.transaction::(|conn| { + async move { + let version = bump_account(conn, &account_id).await?; + check(version, change.expected_version)?; + let removed: Vec = diesel::sql_query( + "DELETE FROM module_account_params WHERE account_id = $1 \ + AND kind = 'assignment' RETURNING account_id, module_id, kind, position, \ + params, updated_at, updated_by", + ) + .bind::(&account_id) + .load(conn) + .await?; + let previous = removed + .into_iter() + .map(|row| AccountParamsRow { + account_id: row.account_id, + module_id: row.module_id, + kind: ParamsKind::Assignment, + position: row.position, + params: row.params, + updated_at: row.updated_at.to_rfc3339(), + updated_by: row.updated_by, + }) + .collect::>(); + for (position, assigned) in modules.iter().enumerate() { + diesel::sql_query( + "INSERT INTO module_account_params \ + (account_id, module_id, kind, position, params, updated_at, updated_by) \ + VALUES ($1, $2, 'assignment', $3, $4, $5, $6)", + ) + .bind::(&account_id) + .bind::(&assigned.module_id) + .bind::(position as i32) + .bind::(&assigned.params) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + } + for (module_id, before, after) in assignment_changes(&previous, &modules) { + append( + conn, + version, + &module_id, + Some(&account_id), + &before, + &after, + change, + changed_at, + ) + .await?; + } + Ok(version) + } + .scope_boxed() + }) + .await + .map(|version| version as u64) + .map_err(|e| e.context("set assignment")) + } + + async fn seed_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result { + if modules.is_empty() { + return Ok(false); + } + let changed_at = at(change)?; + let modules = serde_json::Value::Array( + modules + .into_iter() + .map(|assigned| { + serde_json::json!({ "module_id": assigned.module_id, "params": assigned.params }) + }) + .collect(), + ); + let mut conn = self.conn().await?; + let committed: Option = diesel::select(guardian_module_seed_assignment( + account_id, + modules, + change.operator, + change.reason, + changed_at, + )) + .get_result(&mut conn) + .await + .map_err(|e| format!("seed assignment: {e}"))?; + Ok(committed.is_some()) + } + + async fn history( + &self, + module_id: &str, + before: Option, + limit: usize, + ) -> Result, String> { + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query( + "SELECT id, version, module_id, account_id, previous_params, new_params, operator, \ + reason, changed_at FROM module_params_history WHERE module_id = $1 \ + AND ($2::BIGINT IS NULL OR id < $2) ORDER BY id DESC LIMIT $3", + ) + .bind::(module_id) + .bind::, _>(before.map(|before| before as i64)) + .bind::(limit as i64) + .load(&mut conn) + .await + .map_err(|e| format!("module params history: {e}"))?; + Ok(rows + .into_iter() + .map(|row| HistoryEntry { + id: row.id as u64, + version: row.version as u64, + module_id: row.module_id, + account_id: row.account_id, + previous: row.previous_params, + new: row.new_params, + operator: row.operator, + reason: row.reason, + at: row.changed_at.to_rfc3339(), + }) + .collect()) + } + + async fn instance_version(&self) -> Result { + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query("SELECT version FROM module_state_version") + .load(&mut conn) + .await + .map_err(|e| format!("module params version: {e}"))?; + Ok(rows.into_iter().next().map_or(0, |row| row.version as u64)) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::*; + use crate::storage::postgres::build_postgres_pool_lazy; + use crate::testing::pg::test_database_url; + + fn change(at: &str) -> Change<'static> { + Change { + operator: "0xop", + reason: "ticket", + at: at.to_string(), + expected_version: None, + } + } + + async fn account_version(store: &PgModuleStore, account: &str) -> u64 { + store.snapshot(account, None).await.unwrap().account_version + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn a_snapshot_reads_both_versions_and_skips_rows_the_cache_holds() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let t0 = "2026-11-09T00:00:00Z"; + let module = format!("caps-{}", rand::random::()); + let account = format!("0xacc{}", rand::random::()); + store + .seed_instance( + &module, + true, + &json!({ "cap": 1000 }), + &json!({ "cap": 1000 }), + t0, + ) + .await + .unwrap(); + let instance_version = store.instance_version().await.unwrap(); + store + .set_layer(&account, &module, Some(json!({ "cap": 100 })), &change(t0)) + .await + .unwrap(); + + let fresh = store.snapshot(&account, None).await.unwrap(); + assert_eq!( + fresh.instance_version, instance_version, + "an account write leaves the instance version, so no cache is invalidated" + ); + assert_eq!(fresh.account_version, 1); + let instances = fresh.instances.expect("no cached version"); + let row = instances + .iter() + .find(|row| row.module_id == module) + .unwrap(); + assert_eq!(row.global_params, json!({ "cap": 1000 })); + assert_eq!(fresh.account_params.len(), 1); + assert_eq!(fresh.account_params[0].params, json!({ "cap": 100 })); + assert_eq!(fresh.account_params[0].kind, ParamsKind::Layer); + + let cached = store + .snapshot(&account, Some(fresh.instance_version)) + .await + .unwrap(); + assert!(cached.instances.is_none(), "the cache holds this version"); + assert_eq!(cached.account_params, fresh.account_params); + + store + .set_global(&module, json!({ "cap": 10 }), &change(t0)) + .await + .unwrap(); + let moved = store + .snapshot(&account, Some(fresh.instance_version)) + .await + .unwrap(); + assert!(moved.instance_version > fresh.instance_version); + assert_eq!( + moved.account_version, 1, + "an instance write leaves the account's" + ); + let row = moved + .instances + .expect("a stale cache gets the rows") + .into_iter() + .find(|row| row.module_id == module) + .unwrap(); + assert_eq!(row.global_params, json!({ "cap": 10 })); + let nobody = store.snapshot("0xnobody", None).await.unwrap(); + assert!(nobody.account_params.is_empty()); + assert_eq!(nobody.account_version, 0); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn module_tables_round_trip_and_version_moves_with_history() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let other_replica = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let t0 = "2026-10-15T00:00:00Z"; + let module = format!("blocklist-{}", rand::random::()); + let account = format!("0xacc{}", rand::random::()); + let start = store.instance_version().await.unwrap(); + + store + .seed_instance( + &module, + true, + &json!({ "denylist": ["0xaaa"] }), + &json!({ "denylist": ["0xaaa"] }), + t0, + ) + .await + .unwrap(); + store + .seed_instance( + &module, + true, + &json!({ "ignored": true }), + &json!({ "ignored": true }), + t0, + ) + .await + .unwrap(); + store + .set_global( + &module, + json!({ "denylist": ["0xaaa", "0xddd"] }), + &change(t0), + ) + .await + .unwrap(); + let layer = store + .set_layer( + &account, + &module, + Some(json!({ "denylist": ["0xccc"] })), + &change(t0), + ) + .await + .unwrap(); + let assignment = store + .set_assignment( + &account, + vec![Assigned { + module_id: format!("{module}-opt"), + params: json!({ "a": 1 }), + }], + &change(t0), + ) + .await + .unwrap(); + assert_eq!( + (layer, assignment), + (1, 2), + "the account counts its own writes" + ); + + let instance = other_replica + .instances() + .await + .unwrap() + .into_iter() + .find(|row| row.module_id == module) + .unwrap(); + assert_eq!( + instance.global_params, + json!({ "denylist": ["0xaaa", "0xddd"] }) + ); + assert_eq!(instance.seeded_params, json!({ "denylist": ["0xaaa"] })); + + let rows = other_replica.account_params(&account).await.unwrap(); + assert_eq!(rows.len(), 2); + assert!(rows.iter().any(|row| row.kind == ParamsKind::Layer)); + + let history = other_replica.history(&module, None, 10).await.unwrap(); + assert_eq!(history.len(), 3); + assert_eq!(history[0].account_id.as_deref(), Some(account.as_str())); + let older = other_replica + .history(&module, Some(history[0].id), 1) + .await + .unwrap(); + assert_eq!( + older, + vec![history[1].clone()], + "paged below an entry, newest first" + ); + assert_eq!( + other_replica.instance_version().await.unwrap(), + start + 2, + "the seed and the global write; the account's writes have their own version" + ); + + store + .set_layer(&account, &module, None, &change(t0)) + .await + .unwrap(); + assert_eq!(store.account_params(&account).await.unwrap().len(), 1); + + store + .set_enabled(&module, false, &change(t0)) + .await + .unwrap(); + let instance = other_replica + .instances() + .await + .unwrap() + .into_iter() + .find(|row| row.module_id == module) + .unwrap(); + assert!(!instance.enabled); + assert!( + store + .set_enabled("no-such-module", false, &change(t0)) + .await + .is_err() + ); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn concurrent_writes_to_an_account_serialize_and_its_version_counts_them() { + let url = test_database_url().await; + let store = std::sync::Arc::new(PgModuleStore::new( + build_postgres_pool_lazy(&url, 8).expect("pool"), + )); + let account = format!("0xacc{}", rand::random::()); + let t0 = "2026-10-15T00:00:00Z"; + let before = store.instance_version().await.unwrap(); + let writes = (0..8).map(|n| { + let store = store.clone(); + let account = account.clone(); + tokio::spawn(async move { + store + .set_assignment( + &account, + vec![Assigned { + module_id: format!("opt-{n}"), + params: json!({}), + }], + &change(t0), + ) + .await + }) + }); + for write in writes { + write.await.unwrap().unwrap(); + } + let rows = store.account_params(&account).await.unwrap(); + assert_eq!(rows.len(), 1, "one replacement wins, never a union"); + assert_eq!(account_version(&store, &account).await, 8); + assert_eq!(store.instance_version().await.unwrap(), before); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn default_copies_reach_only_accounts_without_assignment_history() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let account = format!("0xseed{}", rand::random::()); + let copy = || { + vec![Assigned { + module_id: "screening".into(), + params: json!({ "limit": 5 }), + }] + }; + let t0 = "2026-11-09T00:00:00Z"; + assert!( + store + .seed_assignment(&account, copy(), &change(t0)) + .await + .unwrap() + ); + assert_eq!(account_version(&store, &account).await, 1); + assert!( + !store + .seed_assignment(&account, copy(), &change(t0)) + .await + .unwrap(), + "an existing assignment is kept" + ); + assert_eq!( + account_version(&store, &account).await, + 1, + "a refused copy does not move the version" + ); + store + .set_assignment(&account, Vec::new(), &change(t0)) + .await + .unwrap(); + assert!( + !store + .seed_assignment(&account, copy(), &change(t0)) + .await + .unwrap(), + "an assignment an operator emptied is not refilled" + ); + assert!(store.account_params(&account).await.unwrap().is_empty()); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn an_operator_write_that_changed_nothing_still_blocks_the_default_copy() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let account = format!("0xnoop{}", rand::random::()); + store + .set_assignment(&account, Vec::new(), &change("2026-11-10T00:00:00Z")) + .await + .unwrap(); + let copied = store + .seed_assignment( + &account, + vec![Assigned { + module_id: "screening".into(), + params: json!({}), + }], + &change("2026-11-10T00:00:00Z"), + ) + .await + .unwrap(); + assert!(!copied, "the operator wrote the account first"); + assert!(store.account_params(&account).await.unwrap().is_empty()); + assert_eq!(account_version(&store, &account).await, 1); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn concurrent_default_copies_of_one_account_write_once() { + let url = test_database_url().await; + let store = std::sync::Arc::new(PgModuleStore::new( + build_postgres_pool_lazy(&url, 8).expect("pool"), + )); + let account = format!("0xrace{}", rand::random::()); + let copies = (0..8).map(|n| { + let store = store.clone(); + let account = account.clone(); + tokio::spawn(async move { + store + .seed_assignment( + &account, + vec![Assigned { + module_id: "screening".into(), + params: json!({ "copy": n }), + }], + &change("2026-11-10T00:00:00Z"), + ) + .await + .unwrap() + }) + }); + let mut written = 0; + for copy in copies { + written += usize::from(copy.await.unwrap()); + } + assert_eq!(written, 1, "exactly one registration copies the defaults"); + assert_eq!(store.account_params(&account).await.unwrap().len(), 1); + assert_eq!(account_version(&store, &account).await, 1); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn a_default_copy_racing_an_operator_write_never_overwrites_it() { + let url = test_database_url().await; + let store = std::sync::Arc::new(PgModuleStore::new( + build_postgres_pool_lazy(&url, 4).expect("pool"), + )); + for _ in 0..10 { + let account = format!("0xrace{}", rand::random::()); + let operator = Assigned { + module_id: "operator-choice".into(), + params: json!({ "set_by": "operator" }), + }; + let seed = { + let (store, account) = (store.clone(), account.clone()); + tokio::spawn(async move { + store + .seed_assignment( + &account, + vec![Assigned { + module_id: "screening".into(), + params: json!({ "set_by": "catalog" }), + }], + &change("2026-11-10T00:00:00Z"), + ) + .await + .unwrap() + }) + }; + let write = { + let (store, account, operator) = (store.clone(), account.clone(), operator.clone()); + tokio::spawn(async move { + store + .set_assignment(&account, vec![operator], &change("2026-11-10T00:00:00Z")) + .await + .unwrap() + }) + }; + let (copied, _) = (seed.await.unwrap(), write.await.unwrap()); + let rows = store.account_params(&account).await.unwrap(); + assert_eq!( + rows.iter() + .map(|row| (row.module_id.as_str(), &row.params)) + .collect::>(), + vec![(operator.module_id.as_str(), &operator.params)], + "the operator's assignment stands whichever write committed first" + ); + assert_eq!( + account_version(&store, &account).await, + 1 + u64::from(copied), + "one version per write that committed" + ); + } + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn a_default_copy_keeps_its_order_and_records_each_module() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let run = rand::random::(); + let account = format!("0xorder{run}"); + let (second, first) = (format!("a-second-{run}"), format!("z-first-{run}")); + let instance_version = store.instance_version().await.unwrap(); + assert!( + store + .seed_assignment( + &account, + vec![ + Assigned { + module_id: first.clone(), + params: json!({ "limit": 1 }), + }, + Assigned { + module_id: second.clone(), + params: json!({ "limit": 2 }), + }, + ], + &change("2026-11-10T00:00:00Z"), + ) + .await + .unwrap() + ); + let version = account_version(&store, &account).await; + assert_eq!(version, 1, "one copy is one version"); + assert_eq!( + store.instance_version().await.unwrap(), + instance_version, + "a registration does not touch the instance version" + ); + let rows = store.account_params(&account).await.unwrap(); + assert_eq!( + rows.iter() + .map(|row| (row.module_id.as_str(), row.position, row.kind)) + .collect::>(), + vec![ + (first.as_str(), 0, ParamsKind::Assignment), + (second.as_str(), 1, ParamsKind::Assignment), + ], + "evaluation order is the order given, not the id order" + ); + assert_eq!(rows[1].params, json!({ "limit": 2 })); + for (module, params) in [ + (&first, json!({ "limit": 1 })), + (&second, json!({ "limit": 2 })), + ] { + let history = store.history(module, None, 10).await.unwrap(); + assert_eq!(history.len(), 1); + assert_eq!(history[0].version, version); + assert_eq!(history[0].previous, serde_json::Value::Null); + assert_eq!(history[0].new, params); + } + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn a_conditional_write_only_replaces_the_value_it_expects() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let module = format!("cas-{}", rand::random::()); + let t0 = "2026-10-16T00:00:00Z"; + store + .seed_instance( + &module, + true, + &json!({ "old_name": 1000 }), + &json!({ "old_name": 1000 }), + t0, + ) + .await + .unwrap(); + store + .set_global(&module, json!({ "new_name": 100 }), &change(t0)) + .await + .unwrap(); + let before = store.instance_version().await.unwrap(); + assert_eq!( + store + .set_global_if( + &module, + &json!({ "old_name": 1000 }), + json!({ "new_name": 1000 }), + &change(t0) + ) + .await + .unwrap(), + None, + "the stale expectation does not write" + ); + assert_eq!( + store.instance_version().await.unwrap(), + before, + "and does not move the version" + ); + assert_eq!( + store + .set_global_if( + &module, + &json!({ "new_name": 100 }), + json!({ "new_name": 50 }), + &change(t0) + ) + .await + .unwrap(), + Some(before + 1), + "a write reports the version it committed as" + ); + let row = store + .instances() + .await + .unwrap() + .into_iter() + .find(|row| row.module_id == module) + .unwrap(); + assert_eq!(row.global_params, json!({ "new_name": 50 })); + } +} diff --git a/crates/server/src/modules/registry.rs b/crates/server/src/modules/registry.rs new file mode 100644 index 000000000..8b4982df3 --- /dev/null +++ b/crates/server/src/modules/registry.rs @@ -0,0 +1,702 @@ +//! Module kinds and instance creation. + +use std::collections::{HashMap, HashSet}; +use std::sync::Arc; + +use guardian_module_sdk::policies::{ + self, CodePolicy, RecipientPolicy, SignerPolicy, SpendingLimit, +}; +use guardian_module_sdk::{ + DescribeRequest, Module, ModuleError, ModuleFactory, ModuleInfo, ModuleInstanceConfig, + PROTOCOL_VERSION, capability, +}; + +use super::catalog::{Catalog, InstanceConfig}; +use super::grpc_kind::GrpcFactory; + +#[derive(Clone)] +pub struct Instance { + pub config: InstanceConfig, + pub module: Arc, + /// `name version` from `describe` at startup; `None` when the checks failed. + pub build: Option, +} + +/// A first-party policy: stateless, so every instance of the kind shares one module; each +/// call carries its instance's params. +struct FirstParty(Arc); + +impl ModuleFactory for FirstParty { + fn create(&self, _instance: &ModuleInstanceConfig) -> Result, ModuleError> { + Ok(self.0.clone()) + } +} + +/// The created instances, and the params each module normalized at its startup check (only +/// the instances whose normalized params differ from the ones checked). +pub struct Instantiated { + pub instances: Vec, + pub normalized: HashMap, + /// Enabled instances whose module did not answer its startup checks and that start + /// unavailable: their checks run again on each health probe. + pub unreachable: HashSet, +} + +pub struct Registry { + factories: HashMap>, +} + +impl Registry { + pub fn first_party() -> Self { + let mut registry = Self { + factories: HashMap::new(), + }; + let policies: [(&str, Arc); 4] = [ + (policies::spending_limit::KIND, Arc::new(SpendingLimit)), + (policies::recipient_policy::KIND, Arc::new(RecipientPolicy)), + (policies::signer_policy::KIND, Arc::new(SignerPolicy)), + (policies::code_policy::KIND, Arc::new(CodePolicy)), + ]; + for (kind, module) in policies { + registry + .factories + .insert(kind.into(), Arc::new(FirstParty(module))); + } + registry + .factories + .insert("grpc".into(), Arc::new(GrpcFactory)); + registry + } + + /// Adds a kind the catalog can name. A kind is registered once; the first-party names + /// (the four policies and `grpc`) cannot be replaced. + pub fn register( + &mut self, + kind: impl Into, + factory: Arc, + ) -> Result<(), String> { + let kind = kind.into(); + if self.factories.contains_key(&kind) { + return Err(format!("module kind {kind} is already registered")); + } + self.factories.insert(kind, factory); + Ok(()) + } + + /// Creates every instance and checks it against the params that will apply (`effective`, + /// keyed by instance id; the catalog's when absent). An enabled instance that cannot be + /// created, is unsupported or misconfigured stops startup; a disabled one is logged and + /// kept disabled. + /// + /// An enabled instance whose module does not answer starts unavailable when it is `known` + /// (it ran on an earlier start), so a module's outage does not keep the Guardian from + /// restarting: its accounts follow `on_error` until a health probe passes the checks. One + /// that is new to this Guardian must answer, so a wrong endpoint in a new catalog entry is + /// found when it is deployed. + pub async fn instantiate( + &self, + catalog: &Catalog, + effective: &HashMap, + known: &HashSet, + ) -> Result { + let mut instances = Vec::with_capacity(catalog.instances.len()); + let mut normalized = HashMap::new(); + let mut unreachable = HashSet::new(); + for config in &catalog.instances { + let mut config = config.clone(); + let params = effective.get(&config.id).unwrap_or(&config.params); + let ready = match self.create(&config) { + Ok(module) => check(&config, &module, params) + .await + .map(|checked| (module.clone(), checked)) + .map_err(|error| (error, Some(module))), + Err(error) => Err((Unhealthy::Incompatible(error), None)), + }; + let (module, build) = match ready { + Ok((module, checked)) => { + if checked.params != *params { + normalized.insert(config.id.clone(), checked.params); + } + ( + module, + Some(format!("{} {}", checked.info.name, checked.info.version)), + ) + } + Err((Unhealthy::Unreachable(error), Some(module))) + if config.enabled && known.contains(&config.id) => + { + tracing::warn!(module = %config.id, %error, "Enabled module did not answer its startup checks; it starts unavailable and its accounts follow on_error until a health probe passes"); + unreachable.insert(config.id.clone()); + (module, None) + } + Err((error, _)) if config.enabled => { + return Err(format!("module {}: {error}", config.id)); + } + Err((error, module)) => { + tracing::warn!(module = %config.id, %error, "Disabled module failed its startup checks"); + config.enabled = false; + ( + module.unwrap_or_else(|| Arc::new(Unavailable(error.to_string()))), + None, + ) + } + }; + instances.push(Instance { + config, + module, + build, + }); + } + Ok(Instantiated { + instances, + normalized, + unreachable, + }) + } + + fn create(&self, config: &InstanceConfig) -> Result, String> { + let factory = self + .factories + .get(&config.kind) + .ok_or_else(|| format!("unknown kind {}", config.kind))?; + let credentials = config.credentials.clone()?; + let instance = ModuleInstanceConfig::new( + config.id.clone(), + config.kind.clone(), + config.timeout, + config.params.clone(), + ) + .with_endpoint(config.endpoint.clone()) + .with_auth_token(credentials.auth_token) + .with_tls(credentials.tls) + .with_secrets(credentials.params); + std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| factory.create(&instance))) + .map_err(|_| "module factory panicked".to_string())? + .map_err(|e| e.to_string()) + } +} + +/// Stands in for a disabled instance that could not be created; never evaluated while disabled. +struct Unavailable(String); + +#[async_trait::async_trait] +impl Module for Unavailable { + async fn describe( + &self, + _guardian: &guardian_module_sdk::DescribeRequest, + ) -> Result { + Err(ModuleError::Unavailable(self.0.clone())) + } + + async fn validate_params( + &self, + _params: &[u8], + ) -> Result { + Err(ModuleError::Unavailable(self.0.clone())) + } + + async fn evaluate( + &self, + _request: &guardian_module_sdk::HookRequest, + ) -> Result { + Err(ModuleError::Unavailable(self.0.clone())) + } +} + +/// Why a module call produced no result. +#[derive(Debug)] +pub enum CallError { + Timeout, + /// The panic message, when the payload was a string. + Panicked(String), + Module(ModuleError), +} + +impl std::fmt::Display for CallError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + CallError::Timeout => write!(f, "timed out"), + CallError::Panicked(message) => write!(f, "panicked: {message}"), + CallError::Module(error) => write!(f, "{error}"), + } + } +} + +/// Runs one module call on its own task, so a panic in the module becomes an error instead of +/// unwinding through the request, and the timeout holds even when an in-process module blocks +/// instead of awaiting. A call that times out, or whose caller goes away, is aborted at its next +/// await point. +pub async fn isolated( + timeout: std::time::Duration, + call: impl std::future::Future> + Send + 'static, +) -> Result { + struct AbortOnDrop(tokio::task::JoinHandle); + impl Drop for AbortOnDrop { + fn drop(&mut self) { + self.0.abort(); + } + } + let mut task = AbortOnDrop(tokio::spawn(call)); + match tokio::time::timeout(timeout, &mut task.0).await { + Ok(Ok(result)) => result.map_err(CallError::Module), + Ok(Err(error)) => Err(CallError::Panicked(match error.try_into_panic() { + Ok(payload) => payload + .downcast_ref::<&str>() + .map(|message| message.to_string()) + .or_else(|| payload.downcast_ref::().cloned()) + .unwrap_or_else(|| "non-string panic payload".into()), + Err(error) => error.to_string(), + })), + Err(_) => Err(CallError::Timeout), + } +} + +/// The oldest module protocol version this Guardian accepts. It equals `PROTOCOL_VERSION` +/// until a second major version exists; from then on the previous major stays accepted for a +/// deprecation window (RFC 0002 section 3.5). +pub const MIN_PROTOCOL_VERSION: u32 = PROTOCOL_VERSION; + +/// Optional protocol features this Guardian provides. +pub const CAPABILITIES: &[&str] = &[capability::PARAMS_NORMALIZATION]; + +/// What the Guardian tells a module in `Describe`. +pub fn describe_request() -> DescribeRequest { + DescribeRequest { + guardian_protocol_version: PROTOCOL_VERSION, + guardian_min_protocol_version: MIN_PROTOCOL_VERSION, + guardian_capabilities: CAPABILITIES.iter().map(|c| c.to_string()).collect(), + } +} + +/// A module that passed its startup checks, and the params to store for it (the module's +/// normalized form when it returned one). +pub struct Checked { + pub info: ModuleInfo, + pub params: serde_json::Value, +} + +/// Startup checks: protocol version, required capabilities, hook support and the params that +/// will apply. Also run before enabling. +pub async fn check( + config: &InstanceConfig, + module: &Arc, + params: &serde_json::Value, +) -> Result { + let info = describe_healthy(config, module).await?; + let params = validate_params(module, params, config.timeout).await?; + Ok(Checked { info, params }) +} + +/// Why a module failed its checks. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Unhealthy { + /// The module did not answer: it may be down. + Unreachable(String), + /// The module answered, but with something this Guardian cannot work with (it refused the + /// call, or speaks another protocol version, requires a capability this Guardian lacks or + /// no longer supports a configured hook), so its decisions cannot be trusted either. + Incompatible(String), + /// The module refuses the params that would apply to it. + InvalidParams(String), +} + +impl Unhealthy { + /// A call that produced no result: no answer in time, or the module reporting itself + /// unavailable, is unreachable; anything else is an answer this Guardian cannot use. + fn call(name: &str, error: CallError) -> Self { + let detail = format!("{name} {error}"); + match error { + CallError::Timeout | CallError::Module(ModuleError::Unavailable(_)) => { + Unhealthy::Unreachable(detail) + } + CallError::Module(_) | CallError::Panicked(_) => Unhealthy::Incompatible(detail), + } + } +} + +impl std::fmt::Display for Unhealthy { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Unhealthy::Unreachable(detail) + | Unhealthy::Incompatible(detail) + | Unhealthy::InvalidParams(detail) => { + write!(f, "{detail}") + } + } + } +} + +impl From for String { + fn from(unhealthy: Unhealthy) -> Self { + unhealthy.to_string() + } +} + +/// `Describe` under the instance's timeout, refused when the module speaks a protocol version +/// outside the supported range, requires a capability this Guardian lacks, or no longer supports +/// a configured hook. The startup checks and the periodic health probe share it. +pub async fn describe_healthy( + config: &InstanceConfig, + module: &Arc, +) -> Result { + let describing = module.clone(); + let info = isolated(config.timeout, async move { + describing.describe(&describe_request()).await + }) + .await + .map_err(|e| Unhealthy::call("describe", e))?; + if !(MIN_PROTOCOL_VERSION..=PROTOCOL_VERSION).contains(&info.protocol_version) { + return Err(Unhealthy::Incompatible(format!( + "unsupported protocol version {}; this Guardian accepts {MIN_PROTOCOL_VERSION} to {PROTOCOL_VERSION}", + info.protocol_version + ))); + } + if info.protocol_version < PROTOCOL_VERSION { + tracing::warn!(module = %config.id, protocol_version = info.protocol_version, current = PROTOCOL_VERSION, "Module speaks a deprecated protocol version"); + } + if let Some(missing) = info + .required_capabilities + .iter() + .find(|required| !CAPABILITIES.contains(&required.as_str())) + { + return Err(Unhealthy::Incompatible(format!( + "module requires capability {missing}, which this Guardian does not provide" + ))); + } + for hook in &config.hooks { + if !info.hooks.contains(&(hook.proto() as i32)) { + return Err(Unhealthy::Incompatible(format!( + "module does not support hook {hook:?}" + ))); + } + } + Ok(info) +} + +/// Asks the module whether `params` are valid; used at startup and for every params write. +/// Returns the params to store: the module's normalized form when it sent one, otherwise +/// `params` unchanged. +pub async fn validate_params( + module: &Arc, + params: &serde_json::Value, + timeout: std::time::Duration, +) -> Result { + let bytes = serde_json::to_vec(params).map_err(|e| Unhealthy::InvalidParams(e.to_string()))?; + let validating = module.clone(); + let verdict = isolated( + timeout, + async move { validating.validate_params(&bytes).await }, + ) + .await + .map_err(|e| Unhealthy::call("validate_params", e))?; + if !verdict.ok { + return Err(Unhealthy::InvalidParams(format!( + "invalid params: {}", + verdict.message + ))); + } + if verdict.normalized_params.is_empty() { + return Ok(params.clone()); + } + match serde_json::from_slice::(&verdict.normalized_params) { + Ok(normalized) if normalized.is_object() => Ok(normalized), + _ => Err(Unhealthy::Incompatible( + "normalized params are not a JSON object".into(), + )), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn catalog(entry: &str) -> Catalog { + Catalog::parse(entry, None).unwrap() + } + + const UNKNOWN_KIND: &str = r#" +[[module]] +id = "staged" +kind = "vendor-not-built-in" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +enabled = ENABLED +"#; + + const BAD_ENDPOINT: &str = r#" +[[module]] +id = "staged" +kind = "grpc" +endpoint = "grpc://not a valid uri" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +enabled = ENABLED +"#; + + #[tokio::test] + async fn disabled_instances_that_cannot_be_created_stay_disabled() { + for entry in [UNKNOWN_KIND, BAD_ENDPOINT] { + let instances = Registry::first_party() + .instantiate( + &catalog(&entry.replace("ENABLED", "false")), + &HashMap::new(), + &HashSet::new(), + ) + .await + .expect("a disabled instance does not block startup") + .instances; + assert_eq!(instances.len(), 1); + assert!(!instances[0].config.enabled); + } + } + + #[tokio::test] + async fn enabled_instances_that_cannot_be_created_stop_startup() { + for entry in [UNKNOWN_KIND, BAD_ENDPOINT] { + let result = Registry::first_party() + .instantiate( + &catalog(&entry.replace("ENABLED", "true")), + &HashMap::new(), + &HashSet::new(), + ) + .await; + assert!(result.is_err()); + } + } + + #[tokio::test] + async fn the_guide_catalogs_load() { + for text in [ + include_str!("../../../../docs/guides/policy-modules/remote.toml"), + include_str!("../../../../docs/guides/policy-modules/custom.toml"), + include_str!("../../../../docs/guides/policy-modules/custom-in-process.toml"), + include_str!("../../../../docs/guides/policy-modules/compliance.toml"), + ] { + Catalog::parse(text, None).expect("guide catalog parses"); + } + let built_in = include_str!("../../../../docs/guides/policy-modules/built-in.toml"); + let unedited = Registry::first_party() + .instantiate(&catalog(built_in), &HashMap::new(), &HashSet::new()) + .await + .err() + .expect("the guide catalog does not start until its placeholder is replaced"); + assert!( + unedited.contains("neither an account id in 0x hex form nor a bech32 account address"), + "{unedited}" + ); + let edited = built_in.replace( + "0xREPLACE_WITH_FAUCET_ID", + "0x0a1b2c3d4e5f60718293a4b5c6d7e8", + ); + let started = Registry::first_party() + .instantiate(&catalog(&edited), &HashMap::new(), &HashSet::new()) + .await + .expect("the built-in guide catalog passes the startup checks"); + assert!( + started + .instances + .iter() + .all(|instance| instance.config.enabled) + ); + assert!( + started.normalized.is_empty(), + "hex params are stored as written" + ); + + let by_address = built_in.replace( + "0xREPLACE_WITH_FAUCET_ID", + "mdev1aq0u96z73ckz2y2kr4xp57950qrn4xjc", + ); + let started = Registry::first_party() + .instantiate(&catalog(&by_address), &HashMap::new(), &HashSet::new()) + .await + .expect("a faucet named by its bech32 address passes the startup checks"); + assert_eq!( + started.normalized.get("caps"), + Some(&serde_json::json!({ + "max_per_transaction": { "0x1fc2e85e8e2c2511561d4c1a78b478": "5" } + })), + "the hex id is what gets stored" + ); + } + + struct StubFactory; + + impl ModuleFactory for StubFactory { + fn create(&self, _: &ModuleInstanceConfig) -> Result, ModuleError> { + Ok(Arc::new(RecipientPolicy)) + } + } + + struct PanickingFactory; + + impl ModuleFactory for PanickingFactory { + fn create(&self, _: &ModuleInstanceConfig) -> Result, ModuleError> { + panic!("factory bug") + } + } + + const CUSTOM: &str = r#" +[[module]] +id = "house-rules" +kind = "house-policy" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +"#; + + #[tokio::test] + async fn a_registered_kind_loads_from_the_catalog() { + let mut registry = Registry::first_party(); + registry + .register("house-policy", Arc::new(StubFactory)) + .unwrap(); + let instances = registry + .instantiate(&catalog(CUSTOM), &HashMap::new(), &HashSet::new()) + .await + .unwrap() + .instances; + assert_eq!(instances[0].config.kind, "house-policy"); + assert!(instances[0].config.enabled); + assert!( + Registry::first_party() + .instantiate(&catalog(CUSTOM), &HashMap::new(), &HashSet::new()) + .await + .is_err(), + "unregistered, the same catalog stops startup" + ); + } + + #[test] + fn a_kind_name_is_taken_once() { + let mut registry = Registry::first_party(); + for taken in policies::KINDS.into_iter().chain(["grpc"]) { + assert!(registry.register(taken, Arc::new(StubFactory)).is_err()); + } + registry + .register("house-policy", Arc::new(StubFactory)) + .unwrap(); + assert!( + registry + .register("house-policy", Arc::new(StubFactory)) + .is_err() + ); + } + + #[tokio::test] + async fn a_panicking_factory_fails_startup_cleanly() { + let mut registry = Registry::first_party(); + registry + .register("house-policy", Arc::new(PanickingFactory)) + .unwrap(); + let error = registry + .instantiate(&catalog(CUSTOM), &HashMap::new(), &HashSet::new()) + .await + .err() + .unwrap(); + assert!(error.contains("factory panicked"), "{error}"); + } + + #[tokio::test] + async fn a_panic_keeps_its_message() { + let timeout = std::time::Duration::from_secs(1); + let literal = isolated::<()>(timeout, async { panic!("literal message") }).await; + assert!( + matches!(literal, Err(CallError::Panicked(message)) if message == "literal message") + ); + let id = 7; + let formatted = isolated::<()>(timeout, async move { panic!("instance {id} broke") }).await; + assert!( + matches!(formatted, Err(CallError::Panicked(message)) if message == "instance 7 broke") + ); + } + + const PROTOCOL_CATALOG: &str = r#" +[[module]] +id = "negotiated" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 5 } +"#; + + async fn load(stub: crate::modules::testing::ProtocolStub) -> Result { + let mut registry = Registry::first_party(); + registry + .register( + "protocol-stub", + Arc::new(crate::modules::testing::FixedFactory(Arc::new(stub))), + ) + .unwrap(); + registry + .instantiate(&catalog(PROTOCOL_CATALOG), &HashMap::new(), &HashSet::new()) + .await + } + + #[tokio::test] + async fn describe_tells_the_module_what_this_guardian_speaks() { + let stub = Arc::new(crate::modules::testing::ProtocolStub::new()); + let mut registry = Registry::first_party(); + registry + .register( + "protocol-stub", + Arc::new(crate::modules::testing::FixedFactory(stub.clone())), + ) + .unwrap(); + registry + .instantiate(&catalog(PROTOCOL_CATALOG), &HashMap::new(), &HashSet::new()) + .await + .unwrap(); + let sent = stub.described_with.lock().unwrap().clone().unwrap(); + assert_eq!(sent.guardian_protocol_version, PROTOCOL_VERSION); + assert_eq!(sent.guardian_min_protocol_version, MIN_PROTOCOL_VERSION); + assert!( + sent.guardian_capabilities + .contains(&capability::PARAMS_NORMALIZATION.to_string()) + ); + } + + #[tokio::test] + async fn a_protocol_version_outside_the_supported_range_is_refused() { + for version in [MIN_PROTOCOL_VERSION - 1, PROTOCOL_VERSION + 1] { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.protocol_version = version; + let error = load(stub).await.err().unwrap(); + assert!(error.contains("unsupported protocol version"), "{error}"); + } + } + + #[tokio::test] + async fn a_capability_this_guardian_lacks_is_refused() { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.required_capabilities = vec!["pending.v2".into()]; + let error = load(stub).await.err().unwrap(); + assert!(error.contains("requires capability pending.v2"), "{error}"); + + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.required_capabilities = vec![capability::PARAMS_NORMALIZATION.into()]; + assert!(load(stub).await.is_ok()); + } + + #[tokio::test] + async fn normalized_params_come_back_from_the_startup_check() { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.normalized = Some(serde_json::json!({ "new_name": 5 })); + let loaded = load(stub).await.unwrap(); + assert_eq!( + loaded.normalized.get("negotiated"), + Some(&serde_json::json!({ "new_name": 5 })) + ); + assert!( + load(crate::modules::testing::ProtocolStub::new()) + .await + .unwrap() + .normalized + .is_empty(), + "a module that returns nothing changes nothing" + ); + } +} diff --git a/crates/server/src/modules/request.rs b/crates/server/src/modules/request.rs new file mode 100644 index 000000000..80852ff88 --- /dev/null +++ b/crates/server/src/modules/request.rs @@ -0,0 +1,370 @@ +//! Assembling what a module receives: account views, projection and proposal context. Assembly +//! decodes nothing: the views and projections come from the decode each request already makes +//! inside the reconstruction task, so the async workers only copy finished parts. + +use chrono::{DateTime, Utc}; +use guardian_module_sdk::prost_types::Timestamp; +use guardian_module_sdk::proto::hook_request; +use guardian_module_sdk::{AccountView, HookRequest, RegistrationSubject, TransactionSubject}; + +use crate::delta_object::{DeltaObject, DeltaStatus}; +use crate::metadata::NetworkConfig; +use crate::metadata::auth::Auth; +use crate::network::{ModuleAccount, ModuleAccountInputs, ModuleInputs}; + +#[derive(Debug, Clone, PartialEq)] +pub struct ProposalContext { + pub proposer: String, + pub metadata: serde_json::Value, +} + +/// The proposer and metadata of a stored proposal that is still pending. +pub fn proposal_context(proposal: &DeltaObject) -> Option { + match &proposal.status { + DeltaStatus::Pending { proposer_id, .. } => Some(ProposalContext { + proposer: proposer_id.clone(), + metadata: proposal + .delta_payload + .get("metadata") + .cloned() + .unwrap_or(serde_json::Value::Null), + }), + _ => None, + } +} + +fn timestamp(at: DateTime) -> Timestamp { + Timestamp { + seconds: at.timestamp(), + nanos: at.timestamp_subsec_nanos() as i32, + } +} + +/// An account state and the commitment the Guardian computed for it (never one a client sent). +#[derive(Clone, Copy)] +pub struct StateRef<'a> { + pub commitment: &'a str, + pub json: &'a serde_json::Value, +} + +/// The scheme every signer shares, or `mixed` when the signers use more than one. +fn signers_scheme(schemes: &std::collections::HashMap) -> Result { + let mut distinct: Vec<&String> = schemes.values().collect(); + distinct.sort(); + distinct.dedup(); + match distinct.as_slice() { + [] => Err("account view has no signer schemes".into()), + [scheme] => Ok((*scheme).clone()), + _ => Ok("mixed".into()), + } +} + +/// The account's view, its `auth_scheme` summarizing the signers' schemes. A multisig account's +/// signers and schemes are decoded from its state; a single-key account (no `default_threshold`) +/// takes its one signer and that signer's scheme from its verified auth configuration. +fn view(account: Result, auth: &Auth) -> Result { + let mut view = account?.view; + if view.default_threshold.is_none() { + match auth.cosigner_commitments().as_slice() { + [signer] => { + let scheme = auth.signer_scheme(signer).ok_or_else(|| { + format!("single-key signer {signer} has no registered scheme") + })?; + view.signer_commitments = vec![signer.clone()]; + view.signer_schemes = [(signer.clone(), scheme.as_str().to_string())].into(); + } + signers => { + return Err(format!( + "single-key account registered with {} signers", + signers.len() + )); + } + } + } + view.auth_scheme = signers_scheme(&view.signer_schemes)?; + Ok(view) +} + +/// Modules are not offered EVM accounts. The network a module is told is the one this Guardian +/// serves, never the `network_type` an account was registered with, which its registrant chose. +fn ensure_miden(config: &NetworkConfig) -> Result<(), String> { + match config { + NetworkConfig::Miden { .. } => Ok(()), + NetworkConfig::Evm { .. } => Err("policy modules do not evaluate EVM accounts".into()), + } +} + +pub struct TransactionInput<'a> { + pub network_id: &'static str, + pub account_id: &'a str, + pub submitter: &'a str, + pub submitter_session: bool, + pub auth: &'a Auth, + pub network_config: &'a NetworkConfig, + pub inputs: ModuleInputs, + pub proposal: Option, + pub accounting_time: DateTime, +} + +pub fn transaction_request(input: TransactionInput<'_>) -> Result { + ensure_miden(input.network_config)?; + let ModuleInputs { + before, + after, + transaction, + } = input.inputs; + let transaction = transaction?; + let (proposer, unverified_metadata) = match input.proposal { + Some(context) => ( + context.proposer, + serde_json::to_vec(&context.metadata).map_err(|e| e.to_string())?, + ), + None => (String::new(), Vec::new()), + }; + Ok(HookRequest { + network: "miden".into(), + network_id: input.network_id.into(), + account_id: input.account_id.to_ascii_lowercase(), + accounting_time: Some(timestamp(input.accounting_time)), + submitter: input.submitter.to_string(), + submitter_session: input.submitter_session, + before: Some(view(before, input.auth)?), + after: Some(view(after, input.auth)?), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(guardian_module_sdk::TransactionProjection::miden( + transaction.projection, + )), + raw: Some(guardian_module_sdk::RawTransaction { + encoding: guardian_module_sdk::RawTransaction::MIDEN_TRANSACTION_SUMMARY.into(), + data: transaction.raw_tx_summary, + }), + proposer, + unverified_metadata, + })), + ..Default::default() + }) +} + +pub struct RegistrationInput<'a> { + pub network_id: &'static str, + pub account_id: &'a str, + pub submitter: &'a str, + pub submitter_session: bool, + pub auth: &'a Auth, + pub network_config: &'a NetworkConfig, + /// The view of the state already stored for the account, when there is one. + pub stored: Option>, + /// The view and the whole state of the initial state the request registers. + pub initial: ModuleAccountInputs, + pub accounting_time: DateTime, +} + +pub fn registration_request(input: RegistrationInput<'_>) -> Result { + ensure_miden(input.network_config)?; + Ok(HookRequest { + network: "miden".into(), + network_id: input.network_id.into(), + account_id: input.account_id.to_ascii_lowercase(), + accounting_time: Some(timestamp(input.accounting_time)), + submitter: input.submitter.to_string(), + submitter_session: input.submitter_session, + before: input + .stored + .map(|stored| view(stored, input.auth)) + .transpose()?, + after: Some(view(input.initial.view, input.auth)?), + subject: Some(hook_request::Subject::Registration(RegistrationSubject { + initial_state: Some(guardian_module_sdk::AccountStateProjection::miden( + input.initial.state?, + )), + })), + ..Default::default() + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn multisig_view(schemes: &[(&str, &str)]) -> AccountView { + AccountView { + signer_commitments: schemes.iter().map(|(signer, _)| (*signer).into()).collect(), + signer_schemes: schemes + .iter() + .map(|(signer, scheme)| ((*signer).into(), (*scheme).into())) + .collect(), + default_threshold: Some(1), + ..Default::default() + } + } + + fn built(decoded: AccountView, auth: &Auth) -> Result { + view( + Ok(ModuleAccount { + view: decoded, + nonce: 0, + }), + auth, + ) + } + + #[test] + fn auth_scheme_summarizes_the_decoded_signer_schemes() { + let auth = Auth::MidenFalconRpo { + cosigner_commitments: vec!["0xa".into()], + }; + let shared = built(multisig_view(&[("0xa", "ecdsa"), ("0xb", "ecdsa")]), &auth).unwrap(); + assert_eq!( + shared.auth_scheme, "ecdsa", + "read from state, not the registration" + ); + let mixed = built(multisig_view(&[("0xa", "falcon"), ("0xb", "ecdsa")]), &auth).unwrap(); + assert_eq!(mixed.auth_scheme, "mixed"); + assert_eq!( + mixed.signer_schemes.get("0xb").map(String::as_str), + Some("ecdsa") + ); + } + + #[test] + fn a_single_key_view_takes_its_signer_and_scheme_from_the_registration() { + let auth = Auth::MidenEcdsa { + cosigner_commitments: vec!["0xsolo".into()], + }; + let single = built(AccountView::default(), &auth).unwrap(); + assert_eq!(single.signer_commitments, vec!["0xsolo".to_string()]); + assert_eq!( + single.signer_schemes.get("0xsolo").map(String::as_str), + Some("ecdsa") + ); + assert_eq!(single.auth_scheme, "ecdsa"); + } + + fn registration( + config: &NetworkConfig, + auth: &Auth, + initial: ModuleAccountInputs, + ) -> Result { + registration_request(RegistrationInput { + network_id: "mainnet", + account_id: "0xacc", + submitter: "0xa", + submitter_session: false, + auth, + network_config: config, + stored: None, + initial, + accounting_time: Utc::now(), + }) + } + + fn decoded(view: AccountView) -> ModuleAccountInputs { + ModuleAccountInputs { + view: Ok(ModuleAccount { view, nonce: 0 }), + state: Ok(guardian_module_sdk::MidenAccountState::default()), + } + } + + #[test] + fn requests_name_the_guardians_network_and_refuse_evm_accounts() { + use crate::metadata::network::MidenNetworkType; + let auth = Auth::MidenFalconRpo { + cosigner_commitments: vec!["0xa".into()], + }; + let registered_as_testnet = registration( + &NetworkConfig::Miden { + network_type: MidenNetworkType::Testnet, + }, + &auth, + decoded(multisig_view(&[("0xa", "falcon")])), + ) + .unwrap(); + assert_eq!(registered_as_testnet.network, "miden"); + assert_eq!( + registered_as_testnet.network_id, "mainnet", + "the Guardian's network, not the one the account was registered with" + ); + assert_eq!( + registered_as_testnet + .subject + .and_then(|subject| match subject { + hook_request::Subject::Registration(registration) => registration.initial_state, + hook_request::Subject::Transaction(_) => None, + }) + .and_then(|state| state.network), + Some( + guardian_module_sdk::proto::account_state_projection::Network::Miden( + guardian_module_sdk::MidenAccountState::default() + ) + ), + "the registration carries the account's state" + ); + assert!( + registration( + &NetworkConfig::Evm { + chain_id: 1, + account_address: "0x1".into(), + multisig_validator_address: "0x2".into(), + }, + &auth, + decoded(multisig_view(&[("0xa", "falcon")])), + ) + .is_err() + ); + } + + #[test] + fn modules_receive_the_account_id_in_lowercase_whatever_spelling_registered_it() { + let auth = Auth::MidenFalconRpo { + cosigner_commitments: vec!["0xa".into()], + }; + let request = registration_request(RegistrationInput { + network_id: "mainnet", + account_id: "0xAcC", + submitter: "0xa", + submitter_session: false, + auth: &auth, + network_config: &NetworkConfig::miden_default(), + stored: None, + initial: decoded(multisig_view(&[("0xa", "falcon")])), + accounting_time: Utc::now(), + }) + .unwrap(); + assert_eq!(request.account_id, "0xacc"); + } + + #[test] + fn an_input_that_could_not_be_extracted_fails_the_request() { + let auth = Auth::MidenFalconRpo { + cosigner_commitments: vec!["0xa".into()], + }; + let config = NetworkConfig::miden_default(); + let undecodable_state = ModuleAccountInputs { + state: Err("state does not decode".into()), + ..decoded(multisig_view(&[("0xa", "falcon")])) + }; + assert_eq!( + registration(&config, &auth, undecodable_state).unwrap_err(), + "state does not decode" + ); + let transaction = transaction_request(TransactionInput { + network_id: "mainnet", + account_id: "0xacc", + submitter: "0xa", + submitter_session: false, + auth: &auth, + network_config: &config, + inputs: ModuleInputs { + before: Err("base does not decode".into()), + after: Ok(ModuleAccount { + view: multisig_view(&[("0xa", "falcon")]), + nonce: 1, + }), + transaction: Ok(Default::default()), + }, + proposal: None, + accounting_time: Utc::now(), + }); + assert_eq!(transaction.unwrap_err(), "base does not decode"); + } +} diff --git a/crates/server/src/modules/secrets.rs b/crates/server/src/modules/secrets.rs new file mode 100644 index 000000000..4648947ec --- /dev/null +++ b/crates/server/src/modules/secrets.rs @@ -0,0 +1,368 @@ +//! The secrets backend for module credentials and `$secret` params: files in a directory, or +//! AWS Secrets Manager. Secrets are read once, when the catalog's instances are created. + +use std::path::{Path, PathBuf}; + +use async_trait::async_trait; +use guardian_module_sdk::secrecy::{ExposeSecret, SecretString}; +use guardian_module_sdk::{ClientIdentity, ModuleTls}; + +use super::catalog::{Catalog, Credentials, SecretRefs, check_secret_name}; + +pub const PROVIDER_ENV: &str = "GUARDIAN_MODULE_SECRET_PROVIDER"; +pub const DIR_ENV: &str = "GUARDIAN_MODULE_SECRET_DIR"; + +#[async_trait] +pub trait SecretSource: Send + Sync { + async fn read(&self, name: &str) -> Result; +} + +/// One file per secret, at `/`, readable by its owner only. +pub struct FileSecrets { + dir: PathBuf, +} + +impl FileSecrets { + pub fn new(dir: PathBuf) -> Self { + Self { dir } + } + + fn path(&self, name: &str) -> Result { + check_secret_name(name)?; + let relative = Path::new(name); + let plain = relative + .components() + .all(|component| matches!(component, std::path::Component::Normal(_))); + if plain { + Ok(self.dir.join(relative)) + } else { + Err(format!( + "secret name {name:?} must be a relative path without . or .. segments" + )) + } + } +} + +#[async_trait] +impl SecretSource for FileSecrets { + async fn read(&self, name: &str) -> Result { + let path = self.path(name)?; + ensure_owner_only(&path)?; + std::fs::read_to_string(&path) + .map(SecretString::from) + .map_err(|e| format!("cannot read secret file {}: {e}", path.display())) + } +} + +pub struct AwsSecrets { + client: aws_sdk_secretsmanager::Client, +} + +impl AwsSecrets { + pub async fn from_env() -> Result { + if std::env::var("AWS_REGION").map_or(true, |region| region.is_empty()) { + return Err(format!("{PROVIDER_ENV}=aws needs AWS_REGION to be set")); + } + let config = aws_config::defaults(aws_config::BehaviorVersion::latest()) + .load() + .await; + Ok(Self { + client: aws_sdk_secretsmanager::Client::new(&config), + }) + } +} + +#[async_trait] +impl SecretSource for AwsSecrets { + async fn read(&self, name: &str) -> Result { + check_secret_name(name)?; + let response = self + .client + .get_secret_value() + .secret_id(name) + .send() + .await + .map_err(|e| format!("cannot read secret {name} from Secrets Manager: {e}"))?; + response + .secret_string() + .map(|value| SecretString::from(value.to_owned())) + .ok_or_else(|| format!("secret {name} holds no secret string")) + } +} + +/// The provider named by `GUARDIAN_MODULE_SECRET_PROVIDER`: `aws` by default in the prod stage, +/// `file` otherwise, reading `GUARDIAN_MODULE_SECRET_DIR` or the catalog's directory. +pub async fn from_env(catalog_dir: &Path, prod: bool) -> Result, String> { + let provider = std::env::var(PROVIDER_ENV).unwrap_or_default(); + let provider = match provider.as_str() { + "" if prod => "aws", + "" => "file", + other => other, + }; + match provider { + "file" => { + let dir = std::env::var_os(DIR_ENV) + .filter(|value| !value.is_empty()) + .map(PathBuf::from) + .unwrap_or_else(|| catalog_dir.to_path_buf()); + Ok(Box::new(FileSecrets::new(dir))) + } + "aws" => Ok(Box::new(AwsSecrets::from_env().await?)), + other => Err(format!( + "{PROVIDER_ENV} must be \"file\" or \"aws\", got {other:?}" + )), + } +} + +impl SecretRefs { + /// Reads every secret the instance names; an error names the secret, never its value. + pub async fn resolve(&self, source: Option<&dyn SecretSource>) -> Result { + let read = |name: &str| { + let name = name.to_string(); + async move { + match source { + Some(source) => source.read(&name).await, + None => Err("no secrets provider".to_string()), + } + .map_err(|e| format!("secret {name}: {e}")) + } + }; + let auth_token = match &self.token { + Some(name) => { + let token = read(name).await?.expose_secret().trim().to_owned(); + if token.is_empty() { + return Err(format!("secret {name}: the token is empty")); + } + Some(SecretString::from(token)) + } + None => None, + }; + let tls = match &self.tls { + Some(tls) => { + let ca_pem = tls + .ca_file + .as_ref() + .map(|path| { + std::fs::read(path) + .map_err(|e| format!("cannot read CA file {}: {e}", path.display())) + }) + .transpose()?; + let client_identity = match (&tls.client_cert, &tls.client_key) { + (Some(cert), Some(key)) => Some(ClientIdentity::new( + read(cert).await?.expose_secret().as_bytes().to_vec(), + read(key).await?, + )), + _ => None, + }; + Some(ModuleTls::new(ca_pem, client_identity)) + } + None => None, + }; + let mut params = std::collections::BTreeMap::new(); + for name in &self.params { + params.insert(name.clone(), read(name).await?); + } + Ok(Credentials { + auth_token, + tls, + params, + }) + } +} + +impl Catalog { + /// Resolves every instance's secrets. A failure is kept on the instance, so it stops startup + /// for an enabled instance and leaves a disabled one disabled. + pub async fn resolve_secrets(&mut self, source: Option<&dyn SecretSource>) { + for config in &mut self.instances { + config.credentials = config.secrets.resolve(source).await; + } + } + + pub fn names_secrets(&self) -> bool { + self.instances + .iter() + .any(|config| config.secrets.names_secrets()) + } +} + +#[cfg(unix)] +fn ensure_owner_only(path: &Path) -> Result<(), String> { + use std::os::unix::fs::PermissionsExt; + + let mode = std::fs::metadata(path) + .map_err(|e| format!("cannot read secret file {}: {e}", path.display()))? + .permissions() + .mode(); + if mode & 0o077 == 0 { + Ok(()) + } else { + Err(format!( + "secret file {} must not be accessible by group or others (set its permissions to 0600)", + path.display() + )) + } +} + +#[cfg(not(unix))] +fn ensure_owner_only(_path: &Path) -> Result<(), String> { + Ok(()) +} + +#[cfg(test)] +mod tests { + use std::collections::HashMap; + + use super::*; + + struct Fixed(HashMap<&'static str, &'static str>); + + #[async_trait] + impl SecretSource for Fixed { + async fn read(&self, name: &str) -> Result { + self.0 + .get(name) + .map(|value| SecretString::from(value.to_string())) + .ok_or_else(|| "not found".to_string()) + } + } + + fn catalog(extra: &str, params: &str) -> Catalog { + Catalog::parse( + &format!( + r#" +[[module]] +id = "m" +kind = "{kind}" +{endpoint} +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +{extra} +params = {params} +"#, + kind = if extra.is_empty() { + "vendor-screening" + } else { + "grpc" + }, + endpoint = if extra.is_empty() { + "" + } else { + r#"endpoint = "grpc://risk.internal:7443""# + }, + ), + None, + ) + .unwrap() + } + + fn private_dir() -> PathBuf { + let dir = std::env::temp_dir().join(format!("secrets_{:016x}", rand::random::())); + std::fs::create_dir_all(dir.join("modules")).unwrap(); + dir + } + + #[cfg(unix)] + fn write_private(path: &Path, value: &str) { + use std::os::unix::fs::PermissionsExt; + std::fs::write(path, value).unwrap(); + std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600)).unwrap(); + } + + #[tokio::test] + async fn a_token_and_client_identity_resolve_from_the_source() { + let mut catalog = catalog( + r#"auth = { token_secret = "guardian/modules/risk-token" } +tls = { client_cert_secret = "risk-cert", client_key_secret = "risk-key" }"#, + "{}", + ); + assert!(catalog.instances[0].credentials.is_err()); + let source = Fixed(HashMap::from([ + ("guardian/modules/risk-token", "very-secret-token\n"), + ("risk-cert", "CERT"), + ("risk-key", "very-secret-key"), + ])); + catalog.resolve_secrets(Some(&source)).await; + let credentials = catalog.instances[0].credentials.as_ref().unwrap(); + assert_eq!( + credentials.auth_token.as_ref().unwrap().expose_secret(), + "very-secret-token" + ); + let identity = credentials + .tls + .as_ref() + .unwrap() + .client_identity + .as_ref() + .unwrap(); + assert_eq!(identity.cert_pem, b"CERT"); + let debug = format!("{catalog:?}"); + assert!(!debug.contains("very-secret-token") && !debug.contains("very-secret-key")); + } + + #[tokio::test] + async fn a_missing_secret_is_kept_on_the_instance_by_name() { + let mut catalog = catalog(r#"auth = { token_secret = "absent" }"#, "{}"); + catalog.resolve_secrets(Some(&Fixed(HashMap::new()))).await; + let error = catalog.instances[0].credentials.as_ref().unwrap_err(); + assert!(error.contains("secret absent"), "{error}"); + } + + #[tokio::test] + async fn params_secrets_resolve_and_the_params_keep_the_references() { + let mut catalog = catalog( + "", + r#"{ vendor = { api_key = { "$secret" = "vendor-key" } } }"#, + ); + let source = Fixed(HashMap::from([("vendor-key", "k1")])); + catalog.resolve_secrets(Some(&source)).await; + let config = &catalog.instances[0]; + assert_eq!( + config.credentials.as_ref().unwrap().params["vendor-key"].expose_secret(), + "k1" + ); + assert_eq!( + config.params, + serde_json::json!({ "vendor": { "api_key": { "$secret": "vendor-key" } } }) + ); + } + + #[test] + fn malformed_references_are_refused_at_parse() { + for params in [ + r#"{ api_key = { "$secret" = "k", extra = 1 } }"#, + r#"{ api_key = { "$secret" = 1 } }"#, + r#"{ api_key = { "$secret" = "has space" } }"#, + ] { + let text = format!( + "[[module]]\nid = \"m\"\nkind = \"vendor-screening\"\nscope = \"all\"\nhooks = [\"before_transaction_approved\"]\ntimeout_ms = 20\nparams = {params}\n" + ); + assert!(Catalog::parse(&text, None).is_err(), "{params}"); + } + } + + #[cfg(unix)] + #[tokio::test] + async fn the_file_provider_reads_private_files_below_its_directory() { + let dir = private_dir(); + write_private(&dir.join("modules/token"), "t1\n"); + let source = FileSecrets::new(dir.clone()); + assert_eq!( + source.read("modules/token").await.unwrap().expose_secret(), + "t1\n" + ); + for name in ["../token", "modules/../token", "/etc/passwd", "./token"] { + assert!(source.read(name).await.is_err(), "{name}"); + } + std::fs::write(dir.join("open"), "t2").unwrap(); + { + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(dir.join("open"), std::fs::Permissions::from_mode(0o644)) + .unwrap(); + } + let error = source.read("open").await.unwrap_err(); + assert!(error.contains("0600"), "{error}"); + std::fs::remove_dir_all(dir).ok(); + } +} diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs new file mode 100644 index 000000000..177110625 --- /dev/null +++ b/crates/server/src/modules/store.rs @@ -0,0 +1,1232 @@ +//! Module state tables: `module_instances`, `module_account_params`, `module_params_history`. + +use std::collections::BTreeMap; +use std::path::PathBuf; +use std::sync::RwLock; + +use async_trait::async_trait; +use serde::{Deserialize, Serialize}; + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct InstanceRow { + pub module_id: String, + pub enabled: bool, + pub global_params: serde_json::Value, + pub seeded_params: serde_json::Value, + pub updated_at: String, + pub updated_by: String, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ParamsKind { + Layer, + Assignment, +} + +impl ParamsKind { + pub fn as_str(self) -> &'static str { + match self { + ParamsKind::Layer => "layer", + ParamsKind::Assignment => "assignment", + } + } + + pub fn parse(kind: &str) -> Result { + match kind { + "layer" => Ok(ParamsKind::Layer), + "assignment" => Ok(ParamsKind::Assignment), + other => Err(format!("unknown params kind {other}")), + } + } +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct AccountParamsRow { + pub account_id: String, + pub module_id: String, + pub kind: ParamsKind, + pub position: i32, + pub params: serde_json::Value, + pub updated_at: String, + pub updated_by: String, +} + +/// One row of an account, without its params: which module it names and how. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct AccountModule { + pub account_id: String, + pub module_id: String, + pub kind: ParamsKind, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct HistoryEntry { + /// The entry's place in the history, increasing in write order: the cursor a page of + /// history is read below. + #[serde(default)] + pub id: u64, + /// The params version the write committed as: the instance params version for an entry + /// without `account_id`, that account's params version for one with it. + pub version: u64, + pub module_id: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub account_id: Option, + #[schema(value_type = Option)] + pub previous: serde_json::Value, + #[schema(value_type = Option)] + pub new: serde_json::Value, + pub operator: String, + pub reason: String, + pub at: String, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct Assigned { + pub module_id: String, + #[schema(value_type = Object)] + pub params: serde_json::Value, +} + +/// Who changed what and why, for the history and the audit record. +pub struct Change<'a> { + pub operator: &'a str, + pub reason: &'a str, + pub at: String, + /// The params version the operator read before this write: the instance params version + /// for a global write, the account's for a layer or assignment. Set, the write is refused + /// as [`WriteError::Stale`] once that version has moved, so two operators editing from the + /// same read cannot silently drop each other's change. Unset, the write is unconditional. + pub expected_version: Option, +} + +/// Why an operator write did not commit. +#[derive(Debug)] +pub enum WriteError { + /// The write named the version it was made against, and the rows have moved since. + Stale { + current: u64, + }, + Storage(String), +} + +impl From for WriteError { + fn from(message: String) -> Self { + WriteError::Storage(message) + } +} + +impl From<&str> for WriteError { + fn from(message: &str) -> Self { + WriteError::Storage(message.to_string()) + } +} + +impl WriteError { + /// Names the write a storage failure happened in; a stale write is left as it is. + pub fn context(self, write: &str) -> Self { + match self { + WriteError::Storage(message) => WriteError::Storage(format!("{write}: {message}")), + stale @ WriteError::Stale { .. } => stale, + } + } +} + +impl std::fmt::Display for WriteError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + WriteError::Stale { current } => { + write!( + f, + "the params moved to version {current} since they were read" + ) + } + WriteError::Storage(message) => write!(f, "{message}"), + } + } +} + +/// Module state every replica reads. Each write updates its rows and appends the history in +/// one transaction. There are two kinds of params version: the instance params version moves +/// with every write to the instance rows and keys each replica's instance cache, and each +/// account's params version moves with every write to that account's rows. A write to one +/// account therefore never invalidates a cache or waits for a write to another account. +#[async_trait] +pub trait ModuleStore: Send + Sync { + /// Inserts the instance row the first time `module_id` is seen; later calls do nothing. + /// Stores a new instance with `params` as its global params and `catalog_params`, the + /// catalog's value as written, as its seed, so drift compares like with like even when + /// the module normalized the params it stores. + async fn seed_instance( + &self, + module_id: &str, + enabled: bool, + params: &serde_json::Value, + catalog_params: &serde_json::Value, + at: &str, + ) -> Result<(), String>; + + async fn instances(&self) -> Result, String>; + + /// Switches an instance on or off for every account. Recorded in the history as + /// `{"enabled": previous}` to `{"enabled": new}`, so the instance params version moves and + /// caches refresh. Like every operator write, returns the version the write committed as, + /// so the audit entry of the write names that version and not one read afterwards. + async fn set_enabled( + &self, + module_id: &str, + enabled: bool, + change: &Change<'_>, + ) -> Result; + + async fn set_global( + &self, + module_id: &str, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result; + + /// Replaces the global params only while they still equal `expected`, and returns the + /// version it committed as, or `None` when it did not write. For writes derived from a + /// value read earlier (a module migrating params), so an operator's newer write is never + /// overwritten. + async fn set_global_if( + &self, + module_id: &str, + expected: &serde_json::Value, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result, String>; + + async fn account_params(&self, account_id: &str) -> Result, String>; + + /// What one evaluation reads, in one read: the instance params version, the account's + /// params version and rows and, unless `cached_version` is the instance params version, + /// the instance rows. + async fn snapshot( + &self, + account_id: &str, + cached_version: Option, + ) -> Result; + + /// Which module every account row names, ordered by account. A scan for the budget and + /// orphan report, never read on a request path; it carries no params, which are copied per + /// account and can be large. + async fn account_modules(&self) -> Result, String>; + + /// Sets or removes the account's layer on a `scope = all` instance. Returns the account + /// params version the write committed as. + async fn set_layer( + &self, + account_id: &str, + module_id: &str, + params: Option, + change: &Change<'_>, + ) -> Result; + + /// Replaces the account's assignment. Returns the account params version the write + /// committed as. + async fn set_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result; + + /// Writes `modules` as the account's assignment only when it has no assignment and no + /// write has touched its rows yet (account params version 0), which is how `default` + /// instances reach a newly registered account; an operator's earlier write always wins. + /// Returns whether it wrote. + async fn seed_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result; + + /// The module's history, newest first: at most `limit` entries whose `id` is below + /// `before`. + async fn history( + &self, + module_id: &str, + before: Option, + limit: usize, + ) -> Result, String>; + + /// The instance params version: the version of the latest write to the instance rows. + async fn instance_version(&self) -> Result; +} + +/// See [`ModuleStore::snapshot`]. +#[derive(Debug, Clone)] +pub struct ModuleSnapshot { + pub instance_version: u64, + pub account_version: u64, + pub instances: Option>, + pub account_params: Vec, +} + +#[derive(Debug, Default, Clone)] +struct Tables { + instances: BTreeMap, + account_params: Vec, + history: Vec, + instance_version: u64, + account_versions: BTreeMap, +} + +impl Tables { + fn instance_version(&self) -> u64 { + self.instance_version + } + + fn account_version(&self, account_id: &str) -> u64 { + self.account_versions.get(account_id).copied().unwrap_or(0) + } + + /// Refuses a write made against `expected` once the version of its scope (the instance + /// rows for `None`, that account's rows for `Some`) has moved past it. + fn check(&self, account_id: Option<&str>, expected: Option) -> Result<(), WriteError> { + let current = match account_id { + None => self.instance_version, + Some(account_id) => self.account_version(account_id), + }; + match expected { + Some(expected) if expected != current => Err(WriteError::Stale { current }), + _ => Ok(()), + } + } + + /// Moves the version a write commits as, once per write however many history entries it + /// appends: the instance version for `None`, that account's for `Some`. + fn bump(&mut self, account_id: Option<&str>) -> u64 { + let version = match account_id { + None => &mut self.instance_version, + Some(account_id) => self + .account_versions + .entry(account_id.to_string()) + .or_default(), + }; + *version += 1; + *version + } + + /// The versions a state file without them implies: the highest of each scope's history + /// entries. + fn versions_from_history(&mut self) { + for entry in &self.history { + let version = match entry.account_id.as_deref() { + None => &mut self.instance_version, + Some(account_id) => self + .account_versions + .entry(account_id.to_string()) + .or_default(), + }; + *version = (*version).max(entry.version); + } + } + + fn account_rows(&self, account_id: &str) -> Vec { + let mut rows: Vec = self + .account_params + .iter() + .filter(|row| row.account_id == account_id) + .cloned() + .collect(); + rows.sort_by_key(|row| row.position); + rows + } + + fn append( + &mut self, + version: u64, + module_id: &str, + account_id: Option<&str>, + previous: serde_json::Value, + new: serde_json::Value, + change: &Change<'_>, + ) { + let id = self.history.len() as u64 + 1; + self.history.push(HistoryEntry { + id, + version, + module_id: module_id.to_string(), + account_id: account_id.map(str::to_string), + previous, + new, + operator: change.operator.to_string(), + reason: change.reason.to_string(), + at: change.at.clone(), + }); + } + + fn row_params(&self, account_id: &str, module_id: &str, kind: ParamsKind) -> serde_json::Value { + self.account_params + .iter() + .find(|row| { + row.account_id == account_id && row.module_id == module_id && row.kind == kind + }) + .map(|row| row.params.clone()) + .unwrap_or_default() + } +} + +const STATE_FILE: &str = "module_state.json"; + +/// The three tables as one file, so a write and its history row land together or not at all. +#[derive(Serialize, serde::Deserialize, Default)] +struct Snapshot { + instances: Vec, + account_params: Vec, + history: Vec, + #[serde(default)] + instance_version: u64, + #[serde(default)] + account_versions: BTreeMap, +} + +/// The filesystem backend's copy of the three tables. +pub struct FsModuleStore { + tables: RwLock, + dir: Option, +} + +fn read_snapshot(dir: &std::path::Path) -> Result { + match std::fs::read_to_string(dir.join(STATE_FILE)) { + Ok(text) => serde_json::from_str(&text).map_err(|e| format!("invalid {STATE_FILE}: {e}")), + Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(Snapshot::default()), + Err(e) => Err(format!("cannot read {STATE_FILE}: {e}")), + } +} + +fn write_snapshot(dir: &std::path::Path, tables: &Tables) -> Result<(), String> { + use std::io::Write; + let snapshot = Snapshot { + instances: tables.instances.values().cloned().collect(), + account_params: tables.account_params.clone(), + history: tables.history.clone(), + instance_version: tables.instance_version, + account_versions: tables.account_versions.clone(), + }; + let json = serde_json::to_vec_pretty(&snapshot).map_err(|e| e.to_string())?; + let path = dir.join(STATE_FILE); + let temp = path.with_extension("tmp"); + let failed = |e: std::io::Error| format!("cannot write {STATE_FILE}: {e}"); + let mut file = std::fs::File::create(&temp).map_err(failed)?; + file.write_all(&json).map_err(failed)?; + file.sync_all().map_err(failed)?; + std::fs::rename(&temp, &path).map_err(failed)?; + std::fs::File::open(dir) + .and_then(|dir| dir.sync_all()) + .map_err(failed) +} + +impl FsModuleStore { + pub fn in_memory() -> Self { + Self { + tables: RwLock::new(Tables::default()), + dir: None, + } + } + + pub fn open(dir: PathBuf) -> Result { + std::fs::create_dir_all(&dir) + .map_err(|e| format!("cannot create {}: {e}", dir.display()))?; + let snapshot = read_snapshot(&dir)?; + let mut tables = Tables { + instances: snapshot + .instances + .into_iter() + .map(|row| (row.module_id.clone(), row)) + .collect(), + account_params: snapshot.account_params, + history: snapshot + .history + .into_iter() + .zip(1u64..) + .map(|(entry, id)| HistoryEntry { id, ..entry }) + .collect(), + instance_version: snapshot.instance_version, + account_versions: snapshot.account_versions, + }; + tables.versions_from_history(); + Ok(Self { + tables: RwLock::new(tables), + dir: Some(dir), + }) + } + + fn read(&self, view: impl FnOnce(&Tables) -> T) -> T { + match self.tables.read() { + Ok(tables) => view(&tables), + Err(poisoned) => view(&poisoned.into_inner()), + } + } + + fn write>( + &self, + apply: impl FnOnce(&mut Tables) -> Result, + ) -> Result { + let mut tables = self + .tables + .write() + .map_err(|_| E::from("module store poisoned".to_string()))?; + let mut next = tables.clone(); + let out = apply(&mut next)?; + if let Some(dir) = &self.dir { + write_snapshot(dir, &next).map_err(E::from)?; + } + *tables = next; + Ok(out) + } +} + +#[async_trait] +impl ModuleStore for FsModuleStore { + async fn seed_instance( + &self, + module_id: &str, + enabled: bool, + params: &serde_json::Value, + catalog_params: &serde_json::Value, + at: &str, + ) -> Result<(), String> { + if self.read(|tables| tables.instances.contains_key(module_id)) { + return Ok(()); + } + self.write(|tables| { + tables.instances.insert( + module_id.to_string(), + InstanceRow { + module_id: module_id.to_string(), + enabled, + global_params: params.clone(), + seeded_params: catalog_params.clone(), + updated_at: at.to_string(), + updated_by: "catalog".into(), + }, + ); + let change = Change { + operator: "catalog", + reason: "seeded from the catalog file", + at: at.to_string(), + expected_version: None, + }; + let version = tables.bump(None); + tables.append( + version, + module_id, + None, + serde_json::Value::Null, + params.clone(), + &change, + ); + Ok(()) + }) + } + + async fn instances(&self) -> Result, String> { + Ok(self.read(|tables| tables.instances.values().cloned().collect())) + } + + async fn set_enabled( + &self, + module_id: &str, + enabled: bool, + change: &Change<'_>, + ) -> Result { + self.write(|tables| { + let row = tables + .instances + .get_mut(module_id) + .ok_or_else(|| format!("module {module_id} has no instance row"))?; + let previous = std::mem::replace(&mut row.enabled, enabled); + row.updated_at = change.at.clone(); + row.updated_by = change.operator.to_string(); + let version = tables.bump(None); + tables.append( + version, + module_id, + None, + serde_json::json!({ "enabled": previous }), + serde_json::json!({ "enabled": enabled }), + change, + ); + Ok(version) + }) + } + + async fn set_global( + &self, + module_id: &str, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result { + self.write(|tables| { + tables.check(None, change.expected_version)?; + let row = tables + .instances + .entry(module_id.to_string()) + .or_insert_with(|| InstanceRow { + module_id: module_id.to_string(), + enabled: true, + global_params: serde_json::Value::Null, + seeded_params: params.clone(), + updated_at: change.at.clone(), + updated_by: change.operator.to_string(), + }); + let previous = std::mem::replace(&mut row.global_params, params.clone()); + row.updated_at = change.at.clone(); + row.updated_by = change.operator.to_string(); + let version = tables.bump(None); + tables.append(version, module_id, None, previous, params, change); + Ok(version) + }) + } + + async fn set_global_if( + &self, + module_id: &str, + expected: &serde_json::Value, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result, String> { + self.write(|tables| { + let Some(row) = tables + .instances + .get_mut(module_id) + .filter(|row| row.global_params == *expected) + else { + return Ok(None); + }; + let previous = std::mem::replace(&mut row.global_params, params.clone()); + row.updated_at = change.at.clone(); + row.updated_by = change.operator.to_string(); + let version = tables.bump(None); + tables.append(version, module_id, None, previous, params, change); + Ok(Some(version)) + }) + } + + async fn account_params(&self, account_id: &str) -> Result, String> { + Ok(self.read(|tables| tables.account_rows(account_id))) + } + + async fn snapshot( + &self, + account_id: &str, + cached_version: Option, + ) -> Result { + Ok(self.read(|tables| { + let instance_version = tables.instance_version(); + ModuleSnapshot { + instance_version, + account_version: tables.account_version(account_id), + instances: (cached_version != Some(instance_version)) + .then(|| tables.instances.values().cloned().collect()), + account_params: tables.account_rows(account_id), + } + })) + } + + async fn account_modules(&self) -> Result, String> { + Ok(self.read(|tables| { + let mut rows: Vec<&AccountParamsRow> = tables.account_params.iter().collect(); + rows.sort_by(|a, b| (&a.account_id, a.position).cmp(&(&b.account_id, b.position))); + rows.into_iter() + .map(|row| AccountModule { + account_id: row.account_id.clone(), + module_id: row.module_id.clone(), + kind: row.kind, + }) + .collect() + })) + } + + async fn set_layer( + &self, + account_id: &str, + module_id: &str, + params: Option, + change: &Change<'_>, + ) -> Result { + self.write(|tables| { + tables.check(Some(account_id), change.expected_version)?; + let version = tables.bump(Some(account_id)); + let previous = tables.row_params(account_id, module_id, ParamsKind::Layer); + tables.account_params.retain(|row| { + !(row.account_id == account_id + && row.module_id == module_id + && row.kind == ParamsKind::Layer) + }); + if let Some(params) = ¶ms { + tables.account_params.push(AccountParamsRow { + account_id: account_id.to_string(), + module_id: module_id.to_string(), + kind: ParamsKind::Layer, + position: 0, + params: params.clone(), + updated_at: change.at.clone(), + updated_by: change.operator.to_string(), + }); + } + tables.append( + version, + module_id, + Some(account_id), + previous, + params.unwrap_or_default(), + change, + ); + Ok(version) + }) + } + + async fn set_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result { + self.write(|tables| { + tables.check(Some(account_id), change.expected_version)?; + let previous: Vec = tables + .account_params + .iter() + .filter(|row| row.account_id == account_id && row.kind == ParamsKind::Assignment) + .cloned() + .collect(); + tables.account_params.retain(|row| { + !(row.account_id == account_id && row.kind == ParamsKind::Assignment) + }); + for (position, assigned) in modules.iter().enumerate() { + tables.account_params.push(AccountParamsRow { + account_id: account_id.to_string(), + module_id: assigned.module_id.clone(), + kind: ParamsKind::Assignment, + position: position as i32, + params: assigned.params.clone(), + updated_at: change.at.clone(), + updated_by: change.operator.to_string(), + }); + } + let version = tables.bump(Some(account_id)); + for (module_id, before, after) in assignment_changes(&previous, &modules) { + tables.append(version, &module_id, Some(account_id), before, after, change); + } + Ok(version) + }) + } + + async fn seed_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result { + self.write(|tables| { + let assigned = tables + .account_params + .iter() + .any(|row| row.account_id == account_id && row.kind == ParamsKind::Assignment); + if assigned || tables.account_version(account_id) != 0 || modules.is_empty() { + return Ok(false); + } + for (position, assigned) in modules.iter().enumerate() { + tables.account_params.push(AccountParamsRow { + account_id: account_id.to_string(), + module_id: assigned.module_id.clone(), + kind: ParamsKind::Assignment, + position: position as i32, + params: assigned.params.clone(), + updated_at: change.at.clone(), + updated_by: change.operator.to_string(), + }); + } + let version = tables.bump(Some(account_id)); + for (module_id, before, after) in assignment_changes(&[], &modules) { + tables.append(version, &module_id, Some(account_id), before, after, change); + } + Ok(true) + }) + } + + async fn history( + &self, + module_id: &str, + before: Option, + limit: usize, + ) -> Result, String> { + Ok(self.read(|tables| { + tables + .history + .iter() + .rev() + .filter(|entry| entry.module_id == module_id) + .filter(|entry| before.is_none_or(|before| entry.id < before)) + .take(limit) + .cloned() + .collect() + })) + } + + async fn instance_version(&self) -> Result { + Ok(self.read(Tables::instance_version)) + } +} + +/// `(module_id, previous, new)`: one history entry per module whose params or evaluation position the write changes: order +/// decides which module refuses first and which ones the budget cuts. +pub(crate) fn assignment_changes( + previous: &[AccountParamsRow], + modules: &[Assigned], +) -> Vec<(String, serde_json::Value, serde_json::Value)> { + let mut ids: Vec<&str> = previous.iter().map(|row| row.module_id.as_str()).collect(); + ids.extend(modules.iter().map(|assigned| assigned.module_id.as_str())); + ids.sort_unstable(); + ids.dedup(); + ids.into_iter() + .filter_map(|module_id| { + let old = previous.iter().find(|row| row.module_id == module_id); + let new = modules + .iter() + .position(|assigned| assigned.module_id == module_id); + let before = old.map(|row| row.params.clone()).unwrap_or_default(); + let after = new + .map(|index| modules[index].params.clone()) + .unwrap_or_default(); + let moved = + matches!((old, new), (Some(row), Some(index)) if row.position as usize != index); + (before != after || moved).then(|| (module_id.to_string(), before, after)) + }) + .collect() +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::*; + + fn change() -> Change<'static> { + Change { + operator: "0xop", + reason: "ticket", + at: "2026-10-15T00:00:00Z".into(), + expected_version: None, + } + } + + #[tokio::test] + async fn seeding_happens_once_and_api_changes_win() { + let store = FsModuleStore::in_memory(); + store + .seed_instance("caps", true, &json!({ "a": 1 }), &json!({ "a": 1 }), "t0") + .await + .unwrap(); + store + .set_global("caps", json!({ "a": 2 }), &change()) + .await + .unwrap(); + store + .seed_instance("caps", true, &json!({ "a": 3 }), &json!({ "a": 3 }), "t1") + .await + .unwrap(); + let rows = store.instances().await.unwrap(); + assert_eq!(rows[0].global_params, json!({ "a": 2 })); + assert_eq!(rows[0].seeded_params, json!({ "a": 1 })); + assert_eq!(store.instance_version().await.unwrap(), 2); + } + + async fn account_version(store: &FsModuleStore, account_id: &str) -> u64 { + store + .snapshot(account_id, None) + .await + .unwrap() + .account_version + } + + #[tokio::test] + async fn each_write_reports_the_version_it_committed_as() { + let store = FsModuleStore::in_memory(); + store + .seed_instance("caps", true, &json!({}), &json!({}), "t0") + .await + .unwrap(); + let assigned = || { + vec![Assigned { + module_id: "caps".into(), + params: json!({}), + }] + }; + let instance_writes = [ + store + .set_global("caps", json!({ "a": 1 }), &change()) + .await + .unwrap(), + store.set_enabled("caps", false, &change()).await.unwrap(), + store + .set_global_if("caps", &json!({ "a": 1 }), json!({ "a": 2 }), &change()) + .await + .unwrap() + .expect("the expectation holds"), + ]; + assert!( + instance_writes.windows(2).all(|pair| pair[0] < pair[1]), + "later instance writes commit as later versions: {instance_writes:?}" + ); + assert_eq!( + instance_writes.last(), + Some(&store.instance_version().await.unwrap()) + ); + let account_writes = [ + store + .set_layer("0xacc", "caps", Some(json!({})), &change()) + .await + .unwrap(), + store + .set_assignment("0xacc", assigned(), &change()) + .await + .unwrap(), + ]; + assert_eq!(account_writes, [1, 2], "each account counts its own writes"); + assert_eq!(account_version(&store, "0xacc").await, 2); + assert_eq!( + store + .set_global_if("caps", &json!({ "a": 1 }), json!({ "a": 3 }), &change()) + .await + .unwrap(), + None, + "a stale expectation writes nothing and reports no version" + ); + } + + #[tokio::test] + async fn a_write_moves_its_version_once_whatever_it_changes() { + let store = FsModuleStore::in_memory(); + let assigned = |ids: &[&str]| { + ids.iter() + .map(|id| Assigned { + module_id: id.to_string(), + params: json!({ "id": id }), + }) + .collect::>() + }; + let copied = store + .seed_assignment("0xacc", assigned(&["a", "b", "c"]), &change()) + .await + .unwrap(); + assert!(copied); + assert_eq!( + account_version(&store, "0xacc").await, + 1, + "one copy, one version" + ); + for id in ["a", "b", "c"] { + let entries = store.history(id, None, 1).await.unwrap(); + assert_eq!( + entries[0].version, 1, + "the entries of one write share its version" + ); + } + let unchanged = store + .set_assignment("0xacc", assigned(&["a", "b", "c"]), &change()) + .await + .unwrap(); + assert_eq!( + unchanged, 2, + "a write that changes nothing still commits as a version" + ); + } + + #[tokio::test] + async fn an_operator_write_that_changed_nothing_still_blocks_the_default_copy() { + let store = FsModuleStore::in_memory(); + store + .set_assignment("0xacc", Vec::new(), &change()) + .await + .unwrap(); + assert!( + store + .history("screening", None, 10) + .await + .unwrap() + .is_empty() + ); + let copied = store + .seed_assignment( + "0xacc", + vec![Assigned { + module_id: "screening".into(), + params: json!({}), + }], + &change(), + ) + .await + .unwrap(); + assert!(!copied, "the operator wrote the account first"); + assert!(store.account_params("0xacc").await.unwrap().is_empty()); + } + + #[tokio::test] + async fn an_account_write_moves_only_that_accounts_version() { + let store = FsModuleStore::in_memory(); + store + .seed_instance("caps", true, &json!({}), &json!({}), "t0") + .await + .unwrap(); + let instance_version = store.instance_version().await.unwrap(); + store + .set_layer("0xacc", "caps", Some(json!({ "b": 1 })), &change()) + .await + .unwrap(); + assert_eq!( + store.instance_version().await.unwrap(), + instance_version, + "replicas keep their instance cache" + ); + assert_eq!(account_version(&store, "0xacc").await, 1); + assert_eq!(account_version(&store, "0xother").await, 0); + let snapshot = store + .snapshot("0xacc", Some(instance_version)) + .await + .unwrap(); + assert!( + snapshot.instances.is_none(), + "the cached instance rows are current" + ); + store + .set_global("caps", json!({ "a": 1 }), &change()) + .await + .unwrap(); + assert_eq!( + account_version(&store, "0xacc").await, + 1, + "an instance write leaves every account's version" + ); + } + + #[tokio::test] + async fn the_enabled_switch_is_stored_and_moves_the_version() { + let store = FsModuleStore::in_memory(); + store + .seed_instance("caps", true, &json!({}), &json!({}), "t0") + .await + .unwrap(); + store.set_enabled("caps", false, &change()).await.unwrap(); + assert!(!store.instances().await.unwrap()[0].enabled); + let history = store.history("caps", None, 10).await.unwrap(); + assert_eq!(history[0].previous, json!({ "enabled": true })); + assert_eq!(history[0].new, json!({ "enabled": false })); + assert_eq!(store.instance_version().await.unwrap(), 2); + assert!( + store + .set_enabled("unknown", false, &change()) + .await + .is_err() + ); + } + + #[tokio::test] + async fn reordering_an_assignment_is_recorded_and_moves_the_version() { + let store = FsModuleStore::in_memory(); + let assigned = |ids: &[&str]| { + ids.iter() + .map(|id| Assigned { + module_id: id.to_string(), + params: json!({}), + }) + .collect::>() + }; + store + .set_assignment("0xacc", assigned(&["a", "b"]), &change()) + .await + .unwrap(); + let version = account_version(&store, "0xacc").await; + store + .set_assignment("0xacc", assigned(&["b", "a"]), &change()) + .await + .unwrap(); + assert_eq!( + account_version(&store, "0xacc").await, + version + 1, + "two modules moved, one write" + ); + assert_eq!(store.history("a", None, 10).await.unwrap().len(), 2); + let order: Vec<_> = store + .account_params("0xacc") + .await + .unwrap() + .into_iter() + .map(|row| row.module_id) + .collect(); + assert_eq!(order, ["b", "a"]); + } + + #[tokio::test] + async fn layers_and_assignments_share_the_account_table() { + let store = FsModuleStore::in_memory(); + store + .set_layer("0xacc", "blocklist", Some(json!({ "b": 1 })), &change()) + .await + .unwrap(); + store + .set_assignment( + "0xacc", + vec![Assigned { + module_id: "optional".into(), + params: json!({ "c": 1 }), + }], + &change(), + ) + .await + .unwrap(); + let rows = store.account_params("0xacc").await.unwrap(); + assert_eq!(rows.len(), 2); + assert!(rows.iter().any(|row| row.kind == ParamsKind::Layer)); + assert!(rows.iter().any(|row| row.kind == ParamsKind::Assignment)); + assert!(store.account_params("0xother").await.unwrap().is_empty()); + + store + .set_layer("0xacc", "blocklist", None, &change()) + .await + .unwrap(); + assert_eq!(store.account_params("0xacc").await.unwrap().len(), 1); + let history = store.history("blocklist", None, 10).await.unwrap(); + assert_eq!(history.len(), 2); + assert_eq!(history[0].previous, json!({ "b": 1 })); + let older = store + .history("blocklist", Some(history[0].id), 1) + .await + .unwrap(); + assert_eq!( + older, + vec![history[1].clone()], + "paged below an entry, newest first" + ); + } + + #[tokio::test] + async fn default_copies_never_overwrite_an_operator_write_or_refill_an_emptied_assignment() { + let store = FsModuleStore::in_memory(); + let change = |at: &str| Change { + operator: "catalog", + reason: "default", + at: at.into(), + expected_version: None, + }; + let copy = || { + vec![Assigned { + module_id: "screening".into(), + params: serde_json::json!({ "limit": 5 }), + }] + }; + assert!( + store + .seed_assignment("0xnew", copy(), &change("t1")) + .await + .unwrap() + ); + assert!( + !store + .seed_assignment("0xnew", copy(), &change("t2")) + .await + .unwrap(), + "an assignment already exists" + ); + store + .set_assignment("0xnew", Vec::new(), &change("t3")) + .await + .unwrap(); + assert!( + !store + .seed_assignment("0xnew", copy(), &change("t4")) + .await + .unwrap(), + "an assignment an operator emptied is not refilled" + ); + assert!(store.account_params("0xnew").await.unwrap().is_empty()); + } + + #[tokio::test] + async fn a_state_file_without_versions_takes_them_from_its_history() { + let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); + std::fs::create_dir_all(&dir).unwrap(); + let entry = |id: u64, version: u64, account_id: Option<&str>| { + json!({ + "id": id, "version": version, "module_id": "caps", "account_id": account_id, + "previous": null, "new": {}, "operator": "0xop", "reason": "r", "at": "t" + }) + }; + let old_file = json!({ + "instances": [], + "account_params": [], + "history": [entry(1, 1, None), entry(2, 2, Some("0xacc")), entry(3, 3, None)], + }); + std::fs::write(dir.join(STATE_FILE), old_file.to_string()).unwrap(); + let store = FsModuleStore::open(dir.clone()).unwrap(); + assert_eq!(store.instance_version().await.unwrap(), 3); + assert_eq!(account_version(&store, "0xacc").await, 2); + assert!( + !store + .seed_assignment( + "0xacc", + vec![Assigned { + module_id: "caps".into(), + params: json!({}), + }], + &change(), + ) + .await + .unwrap(), + "an account with history keeps its operator's choices" + ); + std::fs::remove_dir_all(dir).ok(); + } + + #[tokio::test] + async fn a_version_moved_by_a_write_that_changed_nothing_survives_a_restart() { + let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); + { + let store = FsModuleStore::open(dir.clone()).unwrap(); + store + .set_assignment("0xacc", Vec::new(), &change()) + .await + .unwrap(); + } + let reopened = FsModuleStore::open(dir.clone()).unwrap(); + assert_eq!(account_version(&reopened, "0xacc").await, 1); + std::fs::remove_dir_all(dir).ok(); + } + + #[tokio::test] + async fn tables_survive_a_restart() { + let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); + { + let store = FsModuleStore::open(dir.clone()).unwrap(); + store + .seed_instance("caps", true, &json!({ "a": 1 }), &json!({ "a": 1 }), "t0") + .await + .unwrap(); + store + .set_layer("0xacc", "caps", Some(json!({ "b": 1 })), &change()) + .await + .unwrap(); + } + assert!(dir.join(STATE_FILE).exists()); + assert!(!dir.join(STATE_FILE).with_extension("tmp").exists()); + let reopened = FsModuleStore::open(dir.clone()).unwrap(); + assert_eq!(reopened.instance_version().await.unwrap(), 1); + assert_eq!(account_version(&reopened, "0xacc").await, 1); + let ids: Vec = reopened + .history("caps", None, 10) + .await + .unwrap() + .iter() + .map(|entry| entry.id) + .collect(); + assert_eq!(ids, [2, 1], "entries keep their place across a restart"); + assert_eq!(reopened.account_params("0xacc").await.unwrap().len(), 1); + std::fs::remove_dir_all(dir).ok(); + } +} diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs new file mode 100644 index 000000000..ac56773a2 --- /dev/null +++ b/crates/server/src/modules/testing.rs @@ -0,0 +1,440 @@ +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::time::Duration; + +use async_trait::async_trait; +use guardian_module_sdk::{ + Decision, DescribeRequest, HookRequest, Module, ModuleError, ModuleInfo, PROTOCOL_VERSION, + ParamsVerdict, +}; + +use super::catalog::{HookName, InstanceConfig, OnError, Scope}; +use super::pipeline::ModulePipeline; +use super::registry::Instance; + +#[derive(Clone)] +pub enum Behaviour { + Decide(Decision), + Fail, + /// Refuses the request as one it cannot judge. + Reject, + Hang, + Panic, + /// Blocks its thread instead of awaiting, like a module doing synchronous work. + Block(Duration), +} + +pub struct StubModule { + behaviour: Behaviour, + pub calls: AtomicUsize, + pub last_request: std::sync::Mutex>, +} + +impl StubModule { + pub fn new(behaviour: Behaviour) -> Arc { + Arc::new(Self { + behaviour, + calls: AtomicUsize::new(0), + last_request: std::sync::Mutex::new(None), + }) + } + + pub fn allowing() -> Arc { + Self::new(Behaviour::Decide(Decision::allow())) + } + + pub fn denying(reason_code: &str) -> Arc { + Self::new(Behaviour::Decide(Decision::deny(reason_code, "stub"))) + } + + pub fn last_request(&self) -> Option { + self.last_request.lock().unwrap().clone() + } + + pub fn calls(&self) -> usize { + self.calls.load(Ordering::SeqCst) + } +} + +#[async_trait] +impl Module for StubModule { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(ModuleInfo { + name: "stub".into(), + version: "0".into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![], + ..Default::default() + }) + } + + async fn validate_params(&self, _params: &[u8]) -> Result { + Ok(ParamsVerdict::ok()) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + self.calls.fetch_add(1, Ordering::SeqCst); + *self.last_request.lock().unwrap() = Some(request.clone()); + match &self.behaviour { + Behaviour::Decide(decision) => Ok(decision.clone()), + Behaviour::Fail => Err(ModuleError::Unavailable("stub down".into())), + Behaviour::Reject => Err(ModuleError::InvalidRequest("stub cannot judge".into())), + Behaviour::Hang => { + tokio::time::sleep(Duration::from_secs(60)).await; + Ok(Decision::allow()) + } + Behaviour::Panic => panic!("stub module panicked"), + Behaviour::Block(duration) => { + std::thread::sleep(*duration); + Ok(Decision::allow()) + } + } + } +} + +pub fn instance( + id: &str, + hooks: &[HookName], + on_error: OnError, + module: Arc, +) -> Instance { + Instance { + config: InstanceConfig { + id: id.into(), + kind: "stub".into(), + endpoint: None, + scope: Scope::All, + hooks: hooks.to_vec(), + timeout: Duration::from_millis(50), + on_error, + enabled: true, + catalog_enabled: true, + operator_can_disable: true, + disclosure: Default::default(), + description: None, + client_reason: Default::default(), + dry_run: true, + secrets: Default::default(), + credentials: Ok(Default::default()), + params: serde_json::json!({}), + file_managed_params: false, + }, + module, + build: Some("stub 1".into()), + } +} + +pub fn instance_with_params( + id: &str, + hooks: &[HookName], + module: Arc, + params: serde_json::Value, +) -> Instance { + let mut instance = instance(id, hooks, OnError::Deny, module); + instance.config.params = params; + instance +} + +pub fn pipeline(instances: Vec) -> Arc { + Arc::new(ModulePipeline::from_instances(instances)) +} + +/// A module whose `describe` and `validate_params` answers are configurable, for the protocol +/// negotiation and params migration tests. It records what the Guardian sent in `Describe`. +pub struct ProtocolStub { + pub protocol_version: u32, + pub required_capabilities: Vec, + pub normalized: Option, + pub described_with: std::sync::Mutex>, +} + +impl Default for ProtocolStub { + fn default() -> Self { + Self::new() + } +} + +impl ProtocolStub { + pub fn new() -> Self { + Self { + protocol_version: PROTOCOL_VERSION, + required_capabilities: Vec::new(), + normalized: None, + described_with: std::sync::Mutex::new(None), + } + } +} + +#[async_trait] +impl Module for ProtocolStub { + async fn describe(&self, guardian: &DescribeRequest) -> Result { + *self.described_with.lock().unwrap() = Some(guardian.clone()); + Ok(ModuleInfo { + name: "protocol-stub".into(), + version: "1".into(), + protocol_version: self.protocol_version, + hooks: vec![guardian_module_sdk::Hook::BeforeTransactionApproved as i32], + required_capabilities: self.required_capabilities.clone(), + }) + } + + async fn validate_params(&self, _params: &[u8]) -> Result { + Ok(match &self.normalized { + Some(params) => ParamsVerdict::normalized(params), + None => ParamsVerdict::ok(), + }) + } + + async fn evaluate(&self, _request: &HookRequest) -> Result { + Ok(Decision::allow()) + } +} + +/// Allows every request while up; while `down`, answers nothing, like a module whose host is +/// gone. +pub struct Outage { + pub down: std::sync::atomic::AtomicBool, + pub evaluations: AtomicUsize, + /// The params `validate_params` answers as normalized, like a module that changed their + /// shape in a new release. + pub normalized: std::sync::Mutex>, +} + +impl Outage { + pub fn new(down: bool) -> Arc { + Arc::new(Self { + down: std::sync::atomic::AtomicBool::new(down), + evaluations: AtomicUsize::new(0), + normalized: std::sync::Mutex::new(None), + }) + } + + pub fn set_down(&self, down: bool) { + self.down.store(down, Ordering::SeqCst); + } + + fn reachable(&self) -> Result<(), ModuleError> { + if self.down.load(Ordering::SeqCst) { + Err(ModuleError::Unavailable("module host is down".into())) + } else { + Ok(()) + } + } +} + +#[async_trait] +impl Module for Outage { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + self.reachable()?; + Ok(ModuleInfo { + name: "outage-stub".into(), + version: "1".into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![guardian_module_sdk::Hook::BeforeTransactionApproved as i32], + ..Default::default() + }) + } + + async fn validate_params(&self, _params: &[u8]) -> Result { + self.reachable()?; + Ok(match self.normalized.lock().unwrap().as_ref() { + Some(params) => ParamsVerdict::normalized(params), + None => ParamsVerdict::ok(), + }) + } + + async fn evaluate(&self, _request: &HookRequest) -> Result { + self.reachable()?; + self.evaluations.fetch_add(1, Ordering::SeqCst); + Ok(Decision::allow()) + } +} + +/// Hands out one prepared module for every instance of its kind. +pub struct FixedFactory(pub Arc); + +impl guardian_module_sdk::ModuleFactory for FixedFactory { + fn create( + &self, + _instance: &guardian_module_sdk::ModuleInstanceConfig, + ) -> Result, ModuleError> { + Ok(self.0.clone()) + } +} + +/// An operator write a [`RacingStore`] commits at a chosen moment. +pub enum RacingWrite { + Global(&'static str, serde_json::Value), + Layer(&'static str, &'static str, Option), +} + +/// A module store that commits operator writes just before a chosen read or write of the +/// caller, to reproduce writes racing with an evaluation or a migration. +pub struct RacingStore { + pub inner: super::store::FsModuleStore, + pub before_account_params: std::sync::Mutex>, + pub before_set_global_if: std::sync::Mutex>, +} + +impl RacingStore { + pub fn new() -> Self { + Self { + inner: super::store::FsModuleStore::in_memory(), + before_account_params: Default::default(), + before_set_global_if: Default::default(), + } + } + + async fn commit(&self, writes: Vec) -> Result<(), String> { + use super::store::ModuleStore; + let change = super::store::Change { + operator: "0xracing-operator", + reason: "concurrent write", + at: "2026-10-16T00:00:01Z".into(), + expected_version: None, + }; + for write in writes { + match write { + RacingWrite::Global(module, params) => { + self.inner + .set_global(module, params, &change) + .await + .map_err(|e| e.to_string())?; + } + RacingWrite::Layer(account, module, params) => { + self.inner + .set_layer(account, module, params, &change) + .await + .map_err(|e| e.to_string())?; + } + } + } + Ok(()) + } +} + +impl Default for RacingStore { + fn default() -> Self { + Self::new() + } +} + +#[async_trait] +impl super::store::ModuleStore for RacingStore { + async fn seed_instance( + &self, + module_id: &str, + enabled: bool, + params: &serde_json::Value, + catalog_params: &serde_json::Value, + at: &str, + ) -> Result<(), String> { + self.inner + .seed_instance(module_id, enabled, params, catalog_params, at) + .await + } + + async fn instances(&self) -> Result, String> { + self.inner.instances().await + } + + async fn snapshot( + &self, + account_id: &str, + cached_version: Option, + ) -> Result { + let writes = std::mem::take(&mut *self.before_account_params.lock().unwrap()); + self.commit(writes).await?; + self.inner.snapshot(account_id, cached_version).await + } + + async fn set_enabled( + &self, + module_id: &str, + enabled: bool, + change: &super::store::Change<'_>, + ) -> Result { + self.inner.set_enabled(module_id, enabled, change).await + } + + async fn set_global( + &self, + module_id: &str, + params: serde_json::Value, + change: &super::store::Change<'_>, + ) -> Result { + self.inner.set_global(module_id, params, change).await + } + + async fn set_global_if( + &self, + module_id: &str, + expected: &serde_json::Value, + params: serde_json::Value, + change: &super::store::Change<'_>, + ) -> Result, String> { + let writes = std::mem::take(&mut *self.before_set_global_if.lock().unwrap()); + self.commit(writes).await?; + self.inner + .set_global_if(module_id, expected, params, change) + .await + } + + async fn account_params( + &self, + account_id: &str, + ) -> Result, String> { + let writes = std::mem::take(&mut *self.before_account_params.lock().unwrap()); + self.commit(writes).await?; + self.inner.account_params(account_id).await + } + + async fn account_modules(&self) -> Result, String> { + self.inner.account_modules().await + } + + async fn seed_assignment( + &self, + account_id: &str, + modules: Vec, + change: &super::store::Change<'_>, + ) -> Result { + self.inner + .seed_assignment(account_id, modules, change) + .await + } + + async fn set_layer( + &self, + account_id: &str, + module_id: &str, + params: Option, + change: &super::store::Change<'_>, + ) -> Result { + self.inner + .set_layer(account_id, module_id, params, change) + .await + } + + async fn set_assignment( + &self, + account_id: &str, + modules: Vec, + change: &super::store::Change<'_>, + ) -> Result { + self.inner.set_assignment(account_id, modules, change).await + } + + async fn history( + &self, + module_id: &str, + before: Option, + limit: usize, + ) -> Result, String> { + self.inner.history(module_id, before, limit).await + } + + async fn instance_version(&self) -> Result { + self.inner.instance_version().await + } +} diff --git a/crates/server/src/network/miden/execution/mod.rs b/crates/server/src/network/miden/execution/mod.rs index 91d84c6f7..8de947fb8 100644 --- a/crates/server/src/network/miden/execution/mod.rs +++ b/crates/server/src/network/miden/execution/mod.rs @@ -13,7 +13,7 @@ mod store; pub use attempt::MidenExecutor; pub use chain::{ChainViewError, build_chain_view}; pub use foreign::{ForeignAccountUnavailable, ForeignAccounts}; -pub use request::StoredRequest; +pub use request::{StoredRequest, approval_expiration_block}; pub use store::ExecutionDataStore; #[cfg(all(test, feature = "e2e"))] diff --git a/crates/server/src/network/miden/mod.rs b/crates/server/src/network/miden/mod.rs index 6a371500d..963592360 100644 --- a/crates/server/src/network/miden/mod.rs +++ b/crates/server/src/network/miden/mod.rs @@ -1,6 +1,7 @@ pub mod account_inspector; pub mod block_feed; pub mod execution; +pub mod module_views; use crate::metadata::auth::{Auth, Credentials}; use crate::network::miden::account_inspector::{ @@ -32,6 +33,87 @@ use miden_standards::account::auth::AuthGuardedMultisig; /// Miden network client for fetching on-chain account data pub struct MidenNetworkClient { client: MidenRpcClient, + /// The chain's fee faucet and the largest fee a transaction can owe, as last read by + /// [`NetworkClient::load_fee_faucet`]. + fee: FeeCache, +} + +/// How long a failed chain fee read waits before the next request tries again. +const CHAIN_FEE_RETRY: std::time::Duration = std::time::Duration::from_secs(10); + +/// The chain fee as last read, refreshed by one request at a time. Requests read on a +/// transaction's path before the module evaluation budget starts, so a refresh in flight or one +/// that just failed never makes another request wait on the network while a value is known. +#[derive(Default)] +struct FeeCache { + /// The last successful read and when it was made. + value: std::sync::RwLock>, + /// No read is tried before this, after one failed. + retry_at: std::sync::Mutex>, + /// Held by the request refreshing. + refreshing: tokio::sync::Mutex<()>, +} + +/// What a request does about the chain fee. +enum FeeRead { + /// The cached value is current, or a refresh is in flight or cooling down after a failure + /// and a value is known: use it. + Cached, + /// Nothing is known and the last read failed moments ago. + CoolingDown, + /// This request reads it. + Refresh, +} + +impl FeeCache { + fn get(&self) -> Option { + self.value + .read() + .ok() + .and_then(|fee| fee.as_ref().map(|(fee, _)| *fee)) + } + + fn known(&self) -> Option { + self.value + .read() + .ok() + .and_then(|fee| fee.as_ref().map(|(_, at)| at.elapsed())) + } + + fn cooling_down(&self) -> bool { + self.retry_at + .lock() + .ok() + .and_then(|retry_at| *retry_at) + .is_some_and(|retry_at| std::time::Instant::now() < retry_at) + } + + fn plan(&self) -> FeeRead { + let age = self.known(); + if age.is_some_and(|age| age < module_views::CHAIN_FEE_TTL) { + return FeeRead::Cached; + } + match (age.is_some(), self.cooling_down()) { + (true, true) => FeeRead::Cached, + (false, true) => FeeRead::CoolingDown, + (_, false) => FeeRead::Refresh, + } + } + + fn store(&self, fee: module_views::ChainFee) { + if let Ok(mut value) = self.value.write() { + *value = Some((fee, std::time::Instant::now())); + } + if let Ok(mut retry_at) = self.retry_at.lock() { + *retry_at = None; + } + } + + fn failed(&self) { + if let Ok(mut retry_at) = self.retry_at.lock() { + *retry_at = Some(std::time::Instant::now() + CHAIN_FEE_RETRY); + } + } } impl MidenNetworkClient { @@ -55,7 +137,10 @@ impl MidenNetworkClient { ) .increment(1); })); - Ok(Self { client }) + Ok(Self { + client, + fee: FeeCache::default(), + }) } /// Builds a client without contacting the network or loading TLS roots, for @@ -67,7 +152,10 @@ impl MidenNetworkClient { pub(crate) fn lazy_for_test(network: NetworkType) -> Self { let client = MidenRpcClient::lazy_unconnected(network.rpc_endpoint()) .expect("lazy client construction is infallible for a valid endpoint"); - Self { client } + Self { + client, + fee: FeeCache::default(), + } } /// True when an on-chain commitment is the empty-word digest the Miden @@ -292,6 +380,11 @@ impl MidenNetworkClient { Ok(account) } + /// The chain fee [`NetworkClient::load_fee_faucet`] last loaded, if any. + fn chain_fee(&self) -> Option { + self.fee.get() + } + fn ensure_prev_commitment(account: &Account, prev_commitment: &str) -> Result<(), String> { let current_commitment = account.to_commitment(); let current_commitment_hex = format!("0x{}", hex::encode(current_commitment.as_bytes())); @@ -314,6 +407,54 @@ impl MidenNetworkClient { prev_account: Result, tx_summary: &TransactionSummary, ) -> Result { + Ok(Self::applied_state(&Self::applied_account( + prev_account, + tx_summary, + )?)) + } + + fn applied_state(account: &Account) -> AppliedState { + let inspector = MidenAccountInspector::new(account); + AppliedState { + commitment: format!("0x{}", hex::encode(account.to_commitment().as_bytes())), + nonce: Some(account.nonce().as_canonical_u64()), + cosigners: inspector.extract_chain_cosigners(), + guardian_commitment: inspector.extract_guardian_public_key(), + state_json: account.to_json(), + } + } + + /// Verifies (when `prev_commitment` is given) and applies `delta_payload` to `account`, with + /// what policy modules receive about it built from the same decode. + fn apply_to_account_with_module_inputs( + &self, + prev_commitment: Option<&str>, + account: Account, + delta_payload: &serde_json::Value, + ) -> Result<(AppliedState, crate::network::ModuleInputs), String> { + let tx_summary = TransactionSummary::from_json(delta_payload)?; + if let Some(prev_commitment) = prev_commitment { + Self::ensure_prev_commitment(&account, prev_commitment)?; + } + let before = module_views::module_account_of(&account); + let transaction = module_views::module_transaction_of( + &tx_summary, + account.nonce().as_canonical_u64(), + self.chain_fee(), + ); + let applied = Self::applied_account(Ok(account), &tx_summary)?; + let inputs = crate::network::ModuleInputs { + before, + after: module_views::module_account_of(&applied), + transaction, + }; + Ok((Self::applied_state(&applied), inputs)) + } + + fn applied_account( + prev_account: Result, + tx_summary: &TransactionSummary, + ) -> Result { let account_delta = tx_summary.account_delta(); // An undecodable prior state skips the ID check: a creation delta then builds the @@ -388,15 +529,7 @@ impl MidenNetworkClient { )?; account }; - - let inspector = MidenAccountInspector::new(&account); - Ok(AppliedState { - commitment: format!("0x{}", hex::encode(account.to_commitment().as_bytes())), - nonce: Some(account.nonce().as_canonical_u64()), - cosigners: inspector.extract_chain_cosigners(), - guardian_commitment: inspector.extract_guardian_public_key(), - state_json: account.to_json(), - }) + Ok(account) } } @@ -552,6 +685,25 @@ impl NetworkClient for MidenNetworkClient { Self::apply_summary(Ok(prev_account), &tx_summary) } + fn apply_delta_with_module_inputs( + &self, + prev_commitment: Option<&str>, + prev_state_json: &serde_json::Value, + delta_payload: &serde_json::Value, + ) -> Result<(AppliedState, crate::network::ModuleInputs), String> { + let account = Account::from_json(prev_state_json)?; + self.apply_to_account_with_module_inputs(prev_commitment, account, delta_payload) + } + + fn verify_and_apply_delta_to_account_with_module_inputs( + &self, + prev_commitment: &str, + prev_account: Account, + delta_payload: &serde_json::Value, + ) -> Result<(AppliedState, crate::network::ModuleInputs), String> { + self.apply_to_account_with_module_inputs(Some(prev_commitment), prev_account, delta_payload) + } + fn merge_deltas( &self, delta_payloads: Vec, @@ -914,6 +1066,95 @@ impl NetworkClient for MidenNetworkClient { Ok(Some(MidenAccountInspector::new(&account).auth_binding())) } + fn module_account_view( + &self, + state_json: &serde_json::Value, + ) -> Result { + module_views::module_account_of(&Account::from_json(state_json)?) + } + + fn module_account_state( + &self, + state_json: &serde_json::Value, + ) -> Result { + module_views::account_state(state_json) + } + + fn module_account_inputs( + &self, + state_json: &serde_json::Value, + ) -> crate::network::ModuleAccountInputs { + match Account::from_json(state_json) { + Ok(account) => crate::network::ModuleAccountInputs { + view: module_views::module_account_of(&account), + state: module_views::account_state_of(&account), + }, + Err(error) => crate::network::ModuleAccountInputs { + view: Err(error.clone()), + state: Err(error), + }, + } + } + + fn module_transaction( + &self, + tx_summary: &serde_json::Value, + initial_nonce: u64, + ) -> Result { + module_views::module_transaction(tx_summary, initial_nonce, self.chain_fee()) + } + + async fn load_fee_faucet(&self) -> Result<(), String> { + let unknown = || "the chain's fee asset is unknown; the last read failed".to_string(); + let _refreshing = match self.fee.plan() { + FeeRead::Cached => return Ok(()), + FeeRead::CoolingDown => return Err(unknown()), + FeeRead::Refresh if self.fee.known().is_some() => { + match self.fee.refreshing.try_lock() { + Ok(guard) => guard, + Err(_) => return Ok(()), + } + } + FeeRead::Refresh => self.fee.refreshing.lock().await, + }; + match self.fee.plan() { + FeeRead::Cached => return Ok(()), + FeeRead::CoolingDown => return Err(unknown()), + FeeRead::Refresh => {} + } + let read = async { + let chain = self + .client + .get_chain_fee(RpcReadMode::Configured) + .await + .map_err(|e| format!("cannot read the chain's fee asset: {e}"))?; + let word = Word::try_from(chain.asset_id.as_str()) + .map_err(|e| format!("fee asset id is not a word: {e}"))?; + let faucet = AssetId::try_from(word) + .map_err(|e| format!("fee asset id does not decode: {e}"))? + .faucet_id(); + Ok::<_, String>(module_views::ChainFee::new( + faucet, + chain.verification_base_fee, + )) + }; + match read.await { + Ok(fee) => { + self.fee.store(fee); + Ok(()) + } + Err(error) => { + self.fee.failed(); + if self.fee.known().is_some() { + tracing::warn!(%error, "Chain fee not refreshed; keeping the last value read"); + Ok(()) + } else { + Err(error) + } + } + } + } + async fn should_update_auth( &self, state_json: &serde_json::Value, @@ -1042,6 +1283,69 @@ mod tests { use super::*; + fn fee() -> module_views::ChainFee { + module_views::ChainFee::new( + AccountId::from_hex(&history_account_id()).expect("account id"), + 100, + ) + } + + #[test] + fn the_fee_cache_refreshes_once_stale_and_waits_out_a_failure() { + let cache = FeeCache::default(); + assert!(matches!(cache.plan(), FeeRead::Refresh)); + cache.failed(); + assert!( + matches!(cache.plan(), FeeRead::CoolingDown), + "nothing known and a read just failed: no request tries again yet" + ); + cache.store(fee()); + assert!(matches!(cache.plan(), FeeRead::Cached)); + if let Ok(mut value) = cache.value.write() { + *value = Some(( + fee(), + std::time::Instant::now() - module_views::CHAIN_FEE_TTL, + )); + } + assert!(matches!(cache.plan(), FeeRead::Refresh)); + cache.failed(); + assert!( + matches!(cache.plan(), FeeRead::Cached), + "a stale value is used while a failed refresh cools down" + ); + } + + #[tokio::test] + async fn a_failed_fee_read_is_not_tried_again_by_the_next_request() { + let (client, _) = history_client(7, Vec::new()).await; + let first = client.load_fee_faucet().await.unwrap_err(); + assert!( + first.contains("cannot read the chain's fee asset"), + "{first}" + ); + let second = client.load_fee_faucet().await.unwrap_err(); + assert!( + second.contains("the last read failed"), + "the second request does not call the node: {second}" + ); + } + + #[tokio::test] + async fn a_request_does_not_wait_for_a_refresh_in_flight_when_a_value_is_known() { + let (client, _) = history_client(7, Vec::new()).await; + if let Ok(mut value) = client.fee.value.write() { + *value = Some(( + fee(), + std::time::Instant::now() - module_views::CHAIN_FEE_TTL, + )); + } + let _refreshing = client.fee.refreshing.lock().await; + let started = std::time::Instant::now(); + client.load_fee_faucet().await.unwrap(); + assert!(started.elapsed() < std::time::Duration::from_millis(100)); + assert!(client.chain_fee().is_some()); + } + #[test] fn test_network_type_rpc_endpoint() { let network = NetworkType::MidenTestnet; @@ -1545,7 +1849,13 @@ mod tests { let client = MidenRpcClient::connect(endpoint) .await .expect("the scripted node accepts connections"); - (MidenNetworkClient { client }, requests) + ( + MidenNetworkClient { + client, + fee: FeeCache::default(), + }, + requests, + ) } fn history_account_id() -> String { @@ -2268,6 +2578,58 @@ mod tests { /// The push path and promotion read the post-delta auth bindings off /// `AppliedState` instead of decoding the stored blob again (issue /// #328), so they must equal what a fresh decode of that blob reads. + #[tokio::test] + async fn module_views_from_the_apply_decode_match_separate_decodes() { + let client = MidenNetworkClient::lazy_for_test(NetworkType::MidenTestnet); + let account_json: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::ACCOUNT_JSON).unwrap(); + let delta_fixture: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::DELTA_1_JSON).unwrap(); + let delta_payload = &delta_fixture["delta_payload"]; + let prev_commitment = format!( + "0x{}", + hex::encode( + Account::from_json(&account_json) + .unwrap() + .to_commitment() + .as_bytes() + ) + ); + + let (applied, views) = client + .apply_delta_with_module_inputs(Some(&prev_commitment), &account_json, delta_payload) + .unwrap(); + assert_eq!( + applied, + client + .verify_and_apply_delta(&prev_commitment, &account_json, delta_payload) + .unwrap() + ); + assert!(views.before.is_ok()); + assert_eq!(views.before, client.module_account_view(&account_json)); + assert_eq!( + views.transaction, + client.module_transaction(delta_payload, views.before.as_ref().unwrap().nonce), + "the projection from the apply decode is the one a separate decode builds" + ); + // The fixture delta adds an approver key without its scheme entry, which the standard + // multisig always writes, so both paths must refuse the resulting view alike. + assert_eq!(views.after, client.module_account_view(&applied.state_json)); + let (unverified, _) = client + .apply_delta_with_module_inputs(None, &account_json, delta_payload) + .unwrap(); + assert_eq!(unverified, applied); + assert!( + client + .apply_delta_with_module_inputs( + Some("0xnot_the_base"), + &account_json, + delta_payload + ) + .is_err() + ); + } + #[tokio::test] async fn verify_and_apply_delta_matches_separate_passes() { let client = MidenNetworkClient::lazy_for_test(NetworkType::MidenTestnet); @@ -2460,6 +2822,16 @@ mod tests { .verify_and_apply_delta(&stored_commitment, &stored_json, payload) .map(|_| ()), client.verify_delta(&stored_commitment, &stored_json, payload), + client + .apply_delta_with_module_inputs(Some(&stored_commitment), &stored_json, payload) + .map(|_| ()), + client + .verify_and_apply_delta_to_account_with_module_inputs( + &stored_commitment, + stored.clone(), + payload, + ) + .map(|_| ()), client.apply_delta(&stored_json, payload).map(|_| ()), ] { let error = refused.expect_err("another account's delta must be refused"); diff --git a/crates/server/src/network/miden/module_views.rs b/crates/server/src/network/miden/module_views.rs new file mode 100644 index 000000000..03b825a7c --- /dev/null +++ b/crates/server/src/network/miden/module_views.rs @@ -0,0 +1,1128 @@ +//! Account views and transaction projections sent to policy modules. + +use guardian_module_sdk::proto::{MapChanges, MapEntry, StorageSlot, asset, storage_slot}; +use guardian_module_sdk::{ + AccountView, Asset as ModuleAsset, Direction, InputNote, MidenAccountState, MidenTransaction, + NoteType, OutputNote, StorageChange, StorageOp, StorageSlotKind, VaultChange, +}; +use guardian_shared::{FromJson, SignatureScheme}; +use miden_protocol::Felt; +use miden_protocol::Word; +use miden_protocol::account::AccountId; +use miden_protocol::account::{Account, StoragePatchOperation, StorageSlotContent}; +use miden_protocol::asset::Asset; +use miden_protocol::note::{Note, NoteId, NoteType as MidenNoteType}; +use miden_protocol::transaction::{RawOutputNote, TransactionSummary}; +use miden_protocol::utils::serde::Serializable; +use miden_standards::account::auth::AuthGuardedMultisig; +use miden_standards::note::{P2idNoteStorage, P2ideNoteStorage, StandardNote, TxFeeNote}; + +fn word_hex(word: &Word) -> String { + format!("0x{}", hex::encode(word.as_bytes())) +} + +fn felt_u32(felt: miden_protocol::Felt) -> Result { + u32::try_from(felt.as_canonical_u64()).map_err(|_| "value does not fit in u32".into()) +} + +/// Code, signers with their schemes, default threshold and effective procedure thresholds of an +/// account. An account without the multisig component is single-key: its view carries no signers +/// and no `default_threshold`, and the caller fills the signer and its scheme from the account's +/// verified auth configuration. A signer whose scheme entry is missing or names no supported +/// scheme is an error, never a signer without a scheme. +pub fn account_view(state_json: &serde_json::Value) -> Result { + account_view_of(&Account::from_json(state_json)?) +} + +/// [`account_view_of`] together with the account's nonce. +pub fn module_account_of(account: &Account) -> Result { + Ok(crate::network::ModuleAccount { + view: account_view_of(account)?, + nonce: account.nonce().as_canonical_u64(), + }) +} + +/// The whole vault and storage of an account, as a registration's subject carries them. +pub fn account_state(state_json: &serde_json::Value) -> Result { + account_state_of(&Account::from_json(state_json)?) +} + +/// [`account_state`] of an account already decoded. +pub fn account_state_of(account: &Account) -> Result { + Ok(MidenAccountState { + vault: account + .vault() + .assets() + .map(|asset| module_asset(&asset)) + .collect(), + storage: account + .storage() + .slots() + .iter() + .map(|slot| { + let (kind, content) = match slot.content() { + StorageSlotContent::Value(word) => ( + StorageSlotKind::Value, + storage_slot::Content::Value(word_hex(word)), + ), + StorageSlotContent::Map(map) => ( + StorageSlotKind::Map, + storage_slot::Content::Map(MapChanges { + entries: map + .entries() + .map(|(key, value)| MapEntry { + key: word_hex(&Word::from(*key)), + value: word_hex(value), + }) + .collect(), + }), + ), + }; + StorageSlot { + slot_name: slot.name().as_str().to_string(), + kind: kind as i32, + content: Some(content), + } + }) + .collect(), + }) +} + +/// [`account_view`] of an account already decoded. +pub fn account_view_of(account: &Account) -> Result { + let storage = account.storage(); + let code = account.code(); + let procedure_roots: Vec = code.procedure_roots().map(|root| word_hex(&root)).collect(); + + let Ok(threshold_config) = storage.get_item(AuthGuardedMultisig::threshold_config_slot()) + else { + return Ok(AccountView { + commitment: word_hex(&account.to_commitment()), + code_commitment: word_hex(&code.commitment()), + procedure_roots, + ..Default::default() + }); + }; + let default_threshold = felt_u32(threshold_config[0])?; + let num_approvers = felt_u32(threshold_config[1])?; + + let signer_commitments = (0..num_approvers) + .map(|index| { + storage + .get_map_item( + AuthGuardedMultisig::approver_public_keys_slot(), + miden_protocol::account::StorageMapKey::new(Word::from([index, 0, 0, 0])), + ) + .map_err(|e| format!("approver {index} unreadable: {e}")) + .and_then(|value| { + if value == Word::default() { + Err(format!("approver {index} missing")) + } else { + Ok(word_hex(&value)) + } + }) + }) + .collect::, _>>()?; + if signer_commitments.is_empty() { + return Err("multisig account has no approvers".into()); + } + let signer_schemes = signer_commitments + .iter() + .zip(0u32..) + .map(|(commitment, index)| { + let id = storage + .get_map_item( + AuthGuardedMultisig::approver_scheme_ids_slot(), + miden_protocol::account::StorageMapKey::new(Word::from([index, 0, 0, 0])), + ) + .map_err(|e| format!("approver {index} scheme unreadable: {e}"))?[0] + .as_canonical_u64(); + SignatureScheme::from_auth_scheme_id(id) + .map(|scheme| (commitment.clone(), scheme.as_str().to_string())) + .ok_or_else(|| format!("approver {index} has no supported scheme (id {id})")) + }) + .collect::>()?; + + // On chain an override applies only to a non-auth procedure the code exports, and zero means + // the default; other entries change nothing, so a threshold floor must not see them. + let auth_procedure = code.procedure_roots().next(); + let procedure_thresholds = match storage + .get(AuthGuardedMultisig::procedure_thresholds_slot()) + .map(|slot| slot.content()) + { + Some(StorageSlotContent::Map(map)) => map + .entries() + .map(|(root, value)| Ok((Word::from(*root), felt_u32(value[0])?))) + .filter(|entry| { + entry.as_ref().map_or(true, |(root, threshold)| { + *threshold != 0 && code.has_procedure(*root) && Some(*root) != auth_procedure + }) + }) + .map(|entry| entry.map(|(root, threshold)| (word_hex(&root), threshold))) + .collect::>()?, + Some(_) => return Err("procedure thresholds slot is not a map".into()), + None => Default::default(), + }; + + Ok(AccountView { + commitment: word_hex(&account.to_commitment()), + auth_scheme: String::new(), + signer_commitments, + default_threshold: Some(default_threshold), + procedure_thresholds, + code_commitment: word_hex(&code.commitment()), + procedure_roots, + signer_schemes, + }) +} + +fn module_asset(asset: &Asset) -> ModuleAsset { + match asset.as_fungible() { + Some(fungible) => ModuleAsset { + faucet_id: fungible.faucet_id().to_hex(), + value: Some(asset::Value::FungibleAmount(fungible.amount().to_string())), + }, + None => ModuleAsset { + faucet_id: asset.faucet_id().to_hex(), + value: Some(asset::Value::NftId(word_hex(&asset.to_id_word()))), + }, + } +} + +fn note_type(note_type: MidenNoteType) -> i32 { + match note_type { + MidenNoteType::Public => NoteType::Public as i32, + MidenNoteType::Private => NoteType::Private as i32, + } +} + +fn p2id_target(note: &Note) -> Option { + match StandardNote::from_script(note.script())? { + StandardNote::P2ID => P2idNoteStorage::try_from(note.storage().items()) + .ok() + .map(|storage| storage.target().to_hex()), + StandardNote::P2IDE => P2ideNoteStorage::try_from(note.storage().items()) + .ok() + .map(|storage| storage.target().to_hex()), + _ => None, + } +} + +fn p2ide_reclaimer(note: &Note) -> Option { + match StandardNote::from_script(note.script())? { + StandardNote::P2IDE => P2ideNoteStorage::try_from(note.storage().items()) + .ok() + .filter(|storage| storage.reclaim_height().is_some()) + .map(|storage| storage.reclaimer().to_hex()), + _ => None, + } +} + +/// How long a chain fee read is used before it is read again. +pub const CHAIN_FEE_TTL: std::time::Duration = std::time::Duration::from_secs(60); + +/// The fee is the base fee times a logarithmic measure of the transaction's cycle count, which +/// stays below 32 for any cycle count the kernel accepts; twice that leaves room for the cycle +/// margins `pay_fee` adds. +const MAX_FEE_VERIFICATION_CYCLES: u64 = 64; + +/// The chain's fee faucet and the largest amount of its asset one transaction can owe as a fee. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct ChainFee { + faucet: AccountId, + max_amount: u64, +} + +impl ChainFee { + pub fn new(faucet: AccountId, verification_base_fee: u32) -> Self { + Self { + faucet, + max_amount: u64::from(verification_base_fee) * MAX_FEE_VERIFICATION_CYCLES, + } + } +} + +fn tx_fee_notes(summary: &TransactionSummary) -> impl Iterator { + summary.output_notes().iter().filter_map(|raw| match raw { + RawOutputNote::Full(note) + if matches!( + StandardNote::from_script(note.script()), + Some(StandardNote::TX_FEE) + ) => + { + Some(note) + } + _ => None, + }) +} + +/// The transaction's fee note: a note with the TX_FEE script is a payment like any other, since +/// any transaction script can create one, with any assets, that anyone can consume. Only the note +/// `pay_fee` creates is the fee, and it is recognised by everything `pay_fee` fixes: it is the +/// only TX_FEE note, its serial number is derived from the account, the nonce the transaction +/// starts from and the block its summary binds, and it carries one fungible asset of the chain's +/// fee faucet, no more of it than a transaction can owe. On a chain that charges nothing `pay_fee` +/// creates no note, so no note qualifies there. +fn fee_note(summary: &TransactionSummary, initial_nonce: u64, fee: ChainFee) -> Option { + let mut tx_fee_notes = tx_fee_notes(summary); + let note = tx_fee_notes.next()?; + if tx_fee_notes.next().is_some() { + return None; + } + let serial_number = TxFeeNote::derive_serial_number( + summary.account_delta().id(), + Felt::new_unchecked(initial_nonce), + summary.block_number(), + ); + if note.recipient().serial_num() != serial_number { + return None; + } + let assets: Vec<&Asset> = note.assets().iter().collect(); + match assets.as_slice() { + [asset] => asset + .as_fungible() + .filter(|asset| { + asset.faucet_id() == fee.faucet && asset.amount().as_u64() <= fee.max_amount + }) + .map(|_| note.id()), + _ => None, + } +} + +fn output_note(raw: &RawOutputNote, fee_note: Option) -> OutputNote { + match raw { + RawOutputNote::Full(note) => OutputNote { + note_id: note.id().to_hex(), + note_type: note_type(note.metadata().note_type()), + partial: false, + recipient_digest: word_hex(¬e.recipient().digest()), + assets: note.assets().iter().map(module_asset).collect(), + script_root: word_hex(&Word::from(note.script().root())), + p2id_target: p2id_target(note), + tx_fee: fee_note == Some(note.id()), + reclaimer: p2ide_reclaimer(note), + }, + RawOutputNote::Partial(partial) => OutputNote { + note_id: partial.id().to_hex(), + note_type: note_type(partial.metadata().note_type()), + partial: true, + recipient_digest: word_hex(&partial.recipient_digest()), + assets: partial.assets().iter().map(module_asset).collect(), + script_root: String::new(), + p2id_target: None, + tx_fee: false, + reclaimer: None, + }, + } +} + +fn storage_op(op: StoragePatchOperation) -> i32 { + match op { + StoragePatchOperation::Create => StorageOp::Create as i32, + StoragePatchOperation::Update => StorageOp::Update as i32, + StoragePatchOperation::Remove => StorageOp::Remove as i32, + } +} + +/// Decodes exactly the summary the Guardian verifies and acks; a proposal wrapper is refused +/// rather than unwrapped, so a module never judges a different summary than the one signed. +pub fn module_transaction( + tx_summary: &serde_json::Value, + initial_nonce: u64, + fee: Option, +) -> Result { + let summary = TransactionSummary::from_json(tx_summary) + .map_err(|e| format!("transaction summary does not decode: {e}"))?; + module_transaction_of(&summary, initial_nonce, fee) +} + +/// [`module_transaction`] of a summary already decoded. +pub fn module_transaction_of( + summary: &TransactionSummary, + initial_nonce: u64, + fee: Option, +) -> Result { + let fee_note = match fee { + Some(fee) => fee_note(summary, initial_nonce, fee), + None if tx_fee_notes(summary).next().is_some() => { + return Err( + "the chain's fee asset is unknown, so the transaction's fee note cannot be told \ + from a payment" + .into(), + ); + } + None => None, + }; + Ok(crate::network::ModuleTransaction { + projection: projection_from_summary(summary, fee_note)?, + raw_tx_summary: summary.to_bytes(), + }) +} + +fn projection_from_summary( + summary: &TransactionSummary, + fee_note: Option, +) -> Result { + let delta = summary.account_delta(); + let vault = delta.vault(); + let vault_changes = vault + .added_assets() + .map(|asset| (asset, Direction::In)) + .chain(vault.removed_assets().map(|asset| (asset, Direction::Out))) + .map(|(asset, direction)| VaultChange { + asset: Some(module_asset(&asset)), + direction: direction as i32, + }) + .collect(); + + let storage = delta.storage(); + let mut storage_changes: Vec = storage + .values() + .map(|(slot_name, patch)| StorageChange { + slot_name: slot_name.as_str().to_string(), + kind: StorageSlotKind::Value as i32, + op: storage_op(patch.patch_op()), + value: patch + .value() + .map(|word| word_hex(&word)) + .unwrap_or_default(), + map: None, + }) + .collect(); + storage_changes.extend(storage.maps().map(|(slot_name, patch)| StorageChange { + slot_name: slot_name.as_str().to_string(), + kind: StorageSlotKind::Map as i32, + op: storage_op(patch.patch_op()), + value: String::new(), + map: patch.entries().map(|entries| { + MapChanges { + entries: entries + .as_map() + .iter() + .map(|(key, value)| MapEntry { + key: word_hex(&Word::from(*key)), + value: word_hex(value), + }) + .collect(), + } + }), + })); + + Ok(MidenTransaction { + nonce_delta: delta.nonce_delta().as_canonical_u64(), + bound_block: summary.block_number().as_u32(), + expiration_delta: Some(u32::from(summary.expiration_delta())).filter(|delta| *delta != 0), + approval_expiration_block: Some(super::execution::approval_expiration_block(summary)) + .filter(|block| *block != 0), + new_code_commitment: delta + .code() + .as_code() + .map(|code| word_hex(&code.commitment())), + vault_changes, + output_notes: summary + .output_notes() + .iter() + .map(|note| output_note(note, fee_note)) + .collect(), + input_notes: summary + .input_notes() + .iter() + .map(|input| InputNote { + note_id: input.note().id().to_hex(), + assets: input.note().assets().iter().map(module_asset).collect(), + }) + .collect(), + storage_changes, + }) +} + +#[cfg(test)] +mod tests { + use guardian_shared::ToJson; + use miden_protocol::account::{ + AccountCode, AccountId, AccountIdVersion, AccountStorage, AccountType, StorageMap, + StorageMapKey, StorageSlot, + }; + use miden_protocol::asset::AssetVault; + + use super::*; + + fn map_slot( + name: &miden_protocol::account::StorageSlotName, + entries: Vec<(Word, Word)>, + ) -> StorageSlot { + let entries = entries + .into_iter() + .map(|(key, value)| (StorageMapKey::new(key), value)); + StorageSlot::with_map(name.clone(), StorageMap::with_entries(entries).unwrap()) + } + + fn account(slots: Vec) -> serde_json::Value { + let account = Account::new_existing( + AccountId::dummy( + [3u8; 15], + AccountIdVersion::Version1, + AccountType::Private, + miden_protocol::account::AssetCallbackFlag::Disabled, + ), + AssetVault::new(&[]).unwrap(), + AccountStorage::new(slots).unwrap(), + AccountCode::mock(), + miden_protocol::Felt::new_unchecked(1), + ); + account.to_json() + } + + fn multisig( + threshold: u32, + approvers: u32, + keys: u32, + procedures: Vec<(Word, Word)>, + ) -> serde_json::Value { + let schemes = vec![SignatureScheme::Falcon.auth_scheme() as u64; keys as usize]; + multisig_with_schemes(threshold, approvers, keys, procedures, &schemes) + } + + /// `schemes[i]` is the auth scheme id stored for approver `i`. + fn multisig_with_schemes( + threshold: u32, + approvers: u32, + keys: u32, + procedures: Vec<(Word, Word)>, + schemes: &[u64], + ) -> serde_json::Value { + account(vec![ + StorageSlot::with_value( + AuthGuardedMultisig::threshold_config_slot().clone(), + Word::from([threshold, approvers, 0, 0]), + ), + map_slot( + AuthGuardedMultisig::approver_public_keys_slot(), + (0..keys) + .map(|i| (Word::from([i, 0, 0, 0]), Word::from([100 + i, 1, 1, 1]))) + .collect(), + ), + map_slot(AuthGuardedMultisig::procedure_thresholds_slot(), procedures), + map_slot( + AuthGuardedMultisig::approver_scheme_ids_slot(), + schemes + .iter() + .zip(0u32..) + .map(|(id, i)| { + ( + Word::from([i, 0, 0, 0]), + Word::from([ + miden_protocol::Felt::new_unchecked(*id), + 0u32.into(), + 0u32.into(), + 0u32.into(), + ]), + ) + }) + .collect(), + ), + ]) + } + + #[test] + fn view_of_the_fixture_account_has_signers_and_a_threshold() { + let state: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::ACCOUNT_JSON).unwrap(); + let view = account_view(&state).unwrap(); + assert!(!view.signer_commitments.is_empty()); + assert!(view.default_threshold.is_some()); + assert!(view.commitment.starts_with("0x")); + } + + fn mock_roots() -> Vec { + AccountCode::mock().procedure_roots().collect() + } + + #[test] + fn view_reads_signers_default_and_only_effective_procedure_thresholds() { + let roots = mock_roots(); + assert!(roots.len() >= 3, "mock code: auth plus two procedures"); + let (auth, effective, zeroed) = (roots[0], roots[1], roots[2]); + let unexported = Word::from([7u32, 7, 7, 7]); + let view = account_view(&multisig( + 2, + 3, + 3, + vec![ + (effective, Word::from([3u32, 0, 0, 0])), + (zeroed, Word::from([0u32, 0, 0, 0])), + (auth, Word::from([1u32, 0, 0, 0])), + (unexported, Word::from([3u32, 0, 0, 0])), + ], + )) + .unwrap(); + assert_eq!(view.signer_commitments.len(), 3); + assert_eq!(view.default_threshold, Some(2)); + assert_eq!( + view.procedure_thresholds, + [(word_hex(&effective), 3)].into(), + "zero, auth and unexported overrides change nothing on chain" + ); + assert_eq!( + view.procedure_roots, + roots.iter().map(word_hex).collect::>() + ); + assert_eq!( + view.code_commitment, + word_hex(&AccountCode::mock().commitment()) + ); + assert_eq!(view.signer_schemes.len(), 3); + assert!( + view.signer_schemes + .values() + .all(|scheme| scheme == "falcon") + ); + } + + #[test] + fn view_reads_each_signers_scheme_of_a_mixed_account() { + let falcon = SignatureScheme::Falcon.auth_scheme() as u64; + let ecdsa = SignatureScheme::Ecdsa.auth_scheme() as u64; + let view = account_view(&multisig_with_schemes(2, 2, 2, vec![], &[falcon, ecdsa])).unwrap(); + assert_eq!( + view.signer_schemes + .get(&view.signer_commitments[0]) + .map(String::as_str), + Some("falcon") + ); + assert_eq!( + view.signer_schemes + .get(&view.signer_commitments[1]) + .map(String::as_str), + Some("ecdsa") + ); + } + + #[test] + fn a_missing_or_unknown_approver_scheme_is_an_error_not_a_signer_without_one() { + let falcon = SignatureScheme::Falcon.auth_scheme() as u64; + assert!(account_view(&multisig_with_schemes(1, 2, 2, vec![], &[falcon])).is_err()); + assert!(account_view(&multisig_with_schemes(1, 2, 2, vec![], &[falcon, 99])).is_err()); + } + + #[test] + fn missing_approver_key_is_an_error_not_a_shorter_list() { + assert!(account_view(&multisig(1, 2, 1, vec![])).is_err()); + } + + #[test] + fn account_without_multisig_auth_is_single_key() { + let state = account(vec![StorageSlot::with_value( + miden_protocol::account::StorageSlotName::new("example::other::slot").unwrap(), + Word::default(), + )]); + let view = account_view(&state).unwrap(); + assert!(!view.commitment.is_empty()); + assert!(view.signer_commitments.is_empty()); + assert_eq!(view.default_threshold, None); + assert_eq!( + view.code_commitment, + word_hex(&AccountCode::mock().commitment()) + ); + assert_eq!(view.procedure_roots.len(), mock_roots().len()); + } + + #[test] + fn projection_decodes_every_delta_fixture() { + for fixture in [ + crate::testing::fixtures::DELTA_1_JSON, + crate::testing::fixtures::DELTA_2_JSON, + crate::testing::fixtures::DELTA_3_JSON, + ] { + let delta: serde_json::Value = serde_json::from_str(fixture).unwrap(); + let transaction = module_transaction(&delta["delta_payload"], 0, None).unwrap(); + let projection = transaction.projection; + for change in &projection.storage_changes { + assert!(!change.slot_name.is_empty()); + assert_ne!(change.op, StorageOp::Unspecified as i32); + } + assert!(!transaction.raw_tx_summary.is_empty()); + let wrapped = serde_json::json!({ "tx_summary": delta["delta_payload"].clone() }); + assert!(module_transaction(&wrapped, 0, None).is_err()); + } + } + + #[test] + fn an_embedded_tx_summary_key_cannot_replace_the_signed_summary() { + let signed: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::DELTA_1_JSON).unwrap(); + let decoy: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::DELTA_2_JSON).unwrap(); + let mut payload = signed["delta_payload"].clone(); + payload["tx_summary"] = decoy["delta_payload"].clone(); + assert_eq!( + module_transaction(&payload, 0, None).unwrap(), + module_transaction(&signed["delta_payload"], 0, None).unwrap() + ); + } + + fn summary(code: Option, expiration_delta: u16) -> TransactionSummary { + use miden_protocol::account::{ + AccountCodePatch, AccountDelta, AccountStoragePatch, AccountVaultDelta, + }; + use miden_protocol::transaction::{InputNotes, RawOutputNotes}; + let delta = AccountDelta::new( + AccountId::dummy( + [3u8; 15], + AccountIdVersion::Version1, + AccountType::Private, + miden_protocol::account::AssetCallbackFlag::Disabled, + ), + AccountStoragePatch::default(), + AccountVaultDelta::default(), + AccountCodePatch::new(code), + miden_protocol::Felt::new_unchecked(1), + ) + .unwrap(); + TransactionSummary::new( + delta, + InputNotes::new(vec![]).unwrap(), + RawOutputNotes::new(vec![]).unwrap(), + miden_protocol::block::BlockNumber::from(100u32), + Word::default(), + expiration_delta, + Default::default(), + ) + } + + fn dummy_id(byte: u8) -> AccountId { + AccountId::dummy( + [byte; 15], + AccountIdVersion::Version1, + AccountType::Private, + miden_protocol::account::AssetCallbackFlag::Disabled, + ) + } + + const NONCE: u64 = 7; + const BLOCK: u32 = 100; + + fn fee_note_with(serial: Word, assets: Vec) -> RawOutputNote { + let note = TxFeeNote::builder() + .sender(dummy_id(3)) + .serial_number(serial) + .assets(assets) + .build() + .unwrap(); + RawOutputNote::Full(note.into()) + } + + fn canonical_serial() -> Word { + TxFeeNote::derive_serial_number( + dummy_id(3), + Felt::new_unchecked(NONCE), + miden_protocol::block::BlockNumber::from(BLOCK), + ) + } + + fn fungible(faucet: u8, amount: u64) -> Asset { + miden_protocol::asset::FungibleAsset::new(dummy_id(faucet), amount) + .unwrap() + .into() + } + + fn summary_with(notes: Vec) -> TransactionSummary { + use miden_protocol::account::{ + AccountCodePatch, AccountDelta, AccountStoragePatch, AccountVaultDelta, + }; + use miden_protocol::transaction::{InputNotes, RawOutputNotes}; + TransactionSummary::new( + AccountDelta::new( + dummy_id(3), + AccountStoragePatch::default(), + AccountVaultDelta::default(), + AccountCodePatch::new(None), + Felt::new_unchecked(1), + ) + .unwrap(), + InputNotes::new(vec![]).unwrap(), + RawOutputNotes::new(notes).unwrap(), + miden_protocol::block::BlockNumber::from(BLOCK), + Word::default(), + 0, + Default::default(), + ) + } + + fn p2ide(reclaimer: Option, reclaim_height: Option) -> RawOutputNote { + let note = miden_standards::note::P2ideNote::builder() + .sender(dummy_id(3)) + .target(dummy_id(4)) + .maybe_reclaimer(reclaimer) + .maybe_reclaim_height(reclaim_height.map(miden_protocol::block::BlockNumber::from)) + .serial_number(canonical_serial()) + .assets(vec![fungible(9, 5)]) + .build() + .unwrap(); + RawOutputNote::Full(note.into()) + } + + #[test] + fn a_reclaimable_p2ide_note_names_its_reclaimer_beside_its_target() { + let summary = summary_with(vec![ + p2ide(Some(dummy_id(5)), Some(1)), + p2ide(Some(dummy_id(5)), None), + p2ide(None, Some(1)), + ]); + let notes = projection_from_summary(&summary, None) + .unwrap() + .output_notes; + let target = Some(dummy_id(4).to_hex()); + assert!(notes.iter().all(|note| note.p2id_target == target)); + assert_eq!( + notes + .iter() + .map(|note| note.reclaimer.clone()) + .collect::>(), + vec![Some(dummy_id(5).to_hex()), None, Some(dummy_id(3).to_hex()),], + "a reclaimer is named only when a reclaim height enables it; it defaults to the sender" + ); + } + + fn fee_flags(notes: Vec, fee: Option) -> Vec { + let summary = summary_with(notes); + projection_from_summary(&summary, fee.and_then(|fee| fee_note(&summary, NONCE, fee))) + .unwrap() + .output_notes + .iter() + .map(|note| note.tx_fee) + .collect() + } + + #[test] + fn a_fee_note_cannot_be_judged_while_the_fee_asset_is_unknown() { + use guardian_shared::ToJson; + let with_fee_note = summary_with(vec![fee_note_with( + canonical_serial(), + vec![fungible(9, 5)], + )]) + .to_json(); + let error = module_transaction(&with_fee_note, NONCE, None).unwrap_err(); + assert!(error.contains("fee asset is unknown"), "{error}"); + let without = summary_with(vec![]).to_json(); + assert!(module_transaction(&without, NONCE, None).is_ok()); + } + + #[test] + fn only_the_note_pay_fee_creates_is_the_fee_note() { + let fee_faucet = Some(ChainFee::new(dummy_id(9), 1)); + let canonical = || fee_note_with(canonical_serial(), vec![fungible(9, 5)]); + assert_eq!(fee_flags(vec![canonical()], fee_faucet), [true]); + assert_eq!( + fee_flags( + vec![fee_note_with( + canonical_serial(), + vec![fungible(9, MAX_FEE_VERIFICATION_CYCLES)] + )], + fee_faucet + ), + [true], + "the largest fee a transaction can owe" + ); + assert_eq!( + fee_flags( + vec![fee_note_with( + canonical_serial(), + vec![fungible(9, MAX_FEE_VERIFICATION_CYCLES + 1)] + )], + fee_faucet + ), + [false], + "more of the fee asset than a transaction can owe is a payment" + ); + assert_eq!( + fee_flags(vec![canonical()], Some(ChainFee::new(dummy_id(9), 0))), + [false], + "a chain that charges nothing has no fee note" + ); + assert_eq!( + fee_flags(vec![canonical()], None), + [false], + "unknown fee faucet" + ); + assert_eq!( + fee_flags( + vec![ + canonical(), + fee_note_with(canonical_serial(), vec![fungible(9, 1_000_000)]) + ], + fee_faucet + ), + [false, false], + "a second note with the same serial number makes neither the fee" + ); + assert_eq!( + fee_flags( + vec![ + fee_note_with(Word::from([1u32, 2, 3, 4]), vec![fungible(9, 5)]), + canonical() + ], + fee_faucet + ), + [false, false], + "an extra TX_FEE note with another serial number" + ); + assert_eq!( + fee_flags( + vec![fee_note_with( + Word::from([1u32, 2, 3, 4]), + vec![fungible(9, 5)] + )], + fee_faucet + ), + [false], + "not the serial number pay_fee derives" + ); + assert_eq!( + fee_flags( + vec![fee_note_with( + canonical_serial(), + vec![fungible(4, 1_000_000)] + )], + fee_faucet + ), + [false], + "an asset of another faucet" + ); + assert_eq!( + fee_flags( + vec![fee_note_with( + canonical_serial(), + vec![fungible(9, 5), fungible(4, 1_000_000)] + )], + fee_faucet + ), + [false], + "more than the fee asset" + ); + } + + #[test] + fn projection_carries_the_bound_block_and_expirations_only_when_set() { + let expiring = projection_from_summary(&summary(None, 20), None).unwrap(); + assert_eq!(expiring.bound_block, 100); + assert_eq!(expiring.expiration_delta, Some(20)); + let open = projection_from_summary(&summary(None, 0), None).unwrap(); + assert_eq!(open.bound_block, 100); + assert_eq!(open.expiration_delta, None); + assert_eq!(open.approval_expiration_block, None); + } + + #[test] + fn projection_carries_the_approval_expiry_from_the_user_params() { + use miden_protocol::transaction::TransactionSummaryUserParams; + let open = summary(None, 0); + let mut user_params = [Felt::ZERO; 6]; + user_params[0] = Felt::new_unchecked(500); + let approved_until = TransactionSummary::new( + open.account_delta().clone(), + open.input_notes().clone(), + open.output_notes().clone(), + open.block_number(), + Word::default(), + 0, + TransactionSummaryUserParams::new(user_params), + ); + assert_eq!( + projection_from_summary(&approved_until, None) + .unwrap() + .approval_expiration_block, + Some(500) + ); + } + + #[test] + fn an_account_state_lists_every_storage_slot_with_its_content() { + let account: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::ACCOUNT_JSON).unwrap(); + let state = account_state(&account).unwrap(); + assert!(!state.storage.is_empty()); + for slot in &state.storage { + assert!(!slot.slot_name.is_empty()); + assert!(slot.content.is_some()); + assert_ne!(slot.kind, StorageSlotKind::Unspecified as i32); + } + assert_eq!( + state.vault.len(), + Account::from_json(&account) + .unwrap() + .vault() + .assets() + .count() + ); + } + + #[test] + fn a_code_replacement_names_the_new_code_commitment() { + let code = AccountCode::mock(); + assert_eq!( + projection_from_summary(&summary(Some(code.clone()), 0), None) + .unwrap() + .new_code_commitment, + Some(word_hex(&code.commitment())) + ); + assert_eq!( + projection_from_summary(&summary(None, 0), None) + .unwrap() + .new_code_commitment, + None + ); + } + + #[test] + #[ignore = "timing report for the prototype gates; run with --ignored --nocapture"] + fn view_and_projection_decode_cost() { + let state: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::ACCOUNT_JSON).unwrap(); + let delta: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::DELTA_1_JSON).unwrap(); + let runs = 200; + let started = std::time::Instant::now(); + for _ in 0..runs { + account_view(&state).unwrap(); + } + let view = started.elapsed() / runs; + let started = std::time::Instant::now(); + for _ in 0..runs { + module_transaction(&delta["delta_payload"], 0, None).unwrap(); + } + let projection = started.elapsed() / runs; + println!("account_view: {view:?} per call, tx_projection: {projection:?} per call"); + } +} + +#[cfg(test)] +mod standard_account_tests { + use guardian_shared::SignatureScheme::{self, Ecdsa, Falcon}; + use guardian_shared::ToJson; + use miden_protocol::account::Account; + + use super::*; + use crate::testing::helpers::{build_guarded_multisig_account, build_single_key_account}; + + fn key(n: u32) -> Word { + Word::from([n, n + 1, n + 2, n + 3]) + } + + fn assert_code_fields(view: &AccountView, account: &Account) { + assert_eq!(view.code_commitment, word_hex(&account.code().commitment())); + assert_eq!( + view.procedure_roots, + account + .code() + .procedure_roots() + .map(|root| word_hex(&root)) + .collect::>() + ); + } + + fn guarded_multisig_with_overrides( + seed: [u8; 32], + threshold: u32, + approvers: &[(Word, SignatureScheme)], + guardian: (Word, SignatureScheme), + overrides: impl Fn(&Account) -> Vec<(miden_protocol::account::AccountProcedureRoot, u32)>, + ) -> Account { + use miden_protocol::account::AccountBuilder; + use miden_protocol::account::auth::PublicKeyCommitment; + use miden_standards::account::auth::{ + Approver, ApproverSet, AuthGuardedMultisigConfig, GuardianConfig, + }; + use miden_standards::account::wallets::BasicWallet; + + let plain = build_guarded_multisig_account(seed, threshold, approvers, guardian); + let approver = |(commitment, scheme): (Word, SignatureScheme)| { + Approver::new(PublicKeyCommitment::from(commitment), scheme.auth_scheme()) + }; + let config = AuthGuardedMultisigConfig::new( + ApproverSet::new(approvers.iter().copied().map(approver).collect(), threshold).unwrap(), + GuardianConfig::new(approver(guardian)), + ) + .unwrap() + .with_proc_thresholds(overrides(&plain)) + .unwrap(); + AccountBuilder::new(seed) + .with_component(miden_protocol::account::AccountComponent::from( + AuthGuardedMultisig::new(config).unwrap(), + )) + .with_component(BasicWallet) + .build() + .unwrap() + } + + #[test] + fn single_key_accounts_carry_their_code_and_leave_the_signer_to_the_registration() { + for scheme in [Falcon, Ecdsa] { + let account = build_single_key_account([1; 32], (key(9), scheme)); + let view = account_view(&account.to_json()).unwrap(); + assert!(view.signer_commitments.is_empty()); + assert!(view.signer_schemes.is_empty()); + assert_eq!(view.default_threshold, None); + assert!(view.procedure_thresholds.is_empty()); + assert_code_fields(&view, &account); + } + } + + #[test] + fn a_two_of_three_falcon_multisig_reads_back_as_built() { + let approvers = [(key(1), Falcon), (key(2), Falcon), (key(3), Falcon)]; + let account = build_guarded_multisig_account([2; 32], 2, &approvers, (key(7), Falcon)); + let view = account_view(&account.to_json()).unwrap(); + assert_eq!( + view.signer_commitments, + approvers + .iter() + .map(|(commitment, _)| word_hex(commitment)) + .collect::>() + ); + assert_eq!(view.signer_schemes.len(), 3); + assert!( + view.signer_schemes + .values() + .all(|scheme| scheme == "falcon") + ); + assert_eq!(view.default_threshold, Some(2)); + assert!(view.procedure_thresholds.is_empty()); + assert_code_fields(&view, &account); + } + + #[test] + fn a_mixed_scheme_multisig_keeps_each_scheme_and_its_effective_override() { + let approvers = [(key(1), Falcon), (key(2), Ecdsa), (key(3), Falcon)]; + let account = + guarded_multisig_with_overrides([3; 32], 2, &approvers, (key(7), Ecdsa), |plain| { + vec![(plain.code().procedures()[1], 1)] + }); + let view = account_view(&account.to_json()).unwrap(); + for (commitment, scheme) in approvers { + assert_eq!( + view.signer_schemes + .get(&word_hex(&commitment)) + .map(String::as_str), + Some(scheme.as_str()) + ); + } + let overridden = Word::from(account.code().procedures()[1]); + assert_eq!( + view.procedure_thresholds, + [(word_hex(&overridden), 1)].into() + ); + assert_code_fields(&view, &account); + } + + #[test] + fn an_override_on_the_auth_procedure_changes_nothing_and_is_left_out() { + let approvers = [(key(1), Falcon), (key(2), Falcon)]; + let account = + guarded_multisig_with_overrides([4; 32], 2, &approvers, (key(7), Falcon), |plain| { + vec![(plain.code().procedures()[0], 1)] + }); + let view = account_view(&account.to_json()).unwrap(); + assert!(view.procedure_thresholds.is_empty()); + } +} diff --git a/crates/server/src/network/mod.rs b/crates/server/src/network/mod.rs index fb808e33e..dbe85966e 100644 --- a/crates/server/src/network/mod.rs +++ b/crates/server/src/network/mod.rs @@ -272,6 +272,35 @@ pub struct TransactionSearch { pub resume_from_block: u32, } +/// An account as policy modules see it, with its nonce: the fee note a transaction creates +/// derives its serial number from the nonce of the state it starts from. +#[derive(Debug, Clone, PartialEq)] +pub struct ModuleAccount { + pub view: guardian_module_sdk::AccountView, + pub nonce: u64, +} + +/// What policy modules receive about a delta, built from the decode that verifies and applies +/// it: the account views of its base state and of the state it produces, and the transaction. +/// Each part that cannot be extracted is kept as its error, so the decode itself still +/// succeeds; a request that needs a missing part cannot be built, and the pipeline then refuses +/// as unavailable whatever the modules' `on_error` says (RFC 0002 section 4.2), since a +/// requester could otherwise switch fail-open modules off with a delta they cannot read. +#[derive(Debug, Clone)] +pub struct ModuleInputs { + pub before: Result, + pub after: Result, + pub transaction: Result, +} + +/// What policy modules receive about an account state at registration, from one decode: the +/// account view and the whole vault and storage. +#[derive(Debug, Clone)] +pub struct ModuleAccountInputs { + pub view: Result, + pub state: Result, +} + /// The state [`NetworkClient::apply_delta`] produced: the new state blob, /// plus the commitment, nonce, and auth bindings of the account it encodes, /// read off the account the method already holds so a caller persisting or @@ -320,6 +349,14 @@ pub struct AuthBinding { pub guardian_scheme: Option, } +/// What a policy module receives about one transaction: the projection and the summary's +/// binary encoding, both decoded from the same bytes the Guardian signs. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct ModuleTransaction { + pub projection: guardian_module_sdk::MidenTransaction, + pub raw_tx_summary: Vec, +} + #[async_trait] pub trait NetworkClient: Send + Sync { /// Commitment (hex) and nonce of the account encoded in `state_json`, @@ -389,6 +426,52 @@ pub trait NetworkClient: Send + Sync { delta_payload: &serde_json::Value, ) -> Result; + /// Verifies (when `prev_commitment` is given) and applies `delta_payload`, and builds what + /// policy modules receive about it from the same decode. Called inside the reconstruction + /// task, so request assembly decodes nothing. The transaction's fee note is told apart with + /// the chain fee [`Self::load_fee_faucet`] loaded before. + fn apply_delta_with_module_inputs( + &self, + prev_commitment: Option<&str>, + prev_state_json: &serde_json::Value, + delta_payload: &serde_json::Value, + ) -> Result<(AppliedState, ModuleInputs), String> { + let applied = match prev_commitment { + Some(prev_commitment) => { + self.verify_and_apply_delta(prev_commitment, prev_state_json, delta_payload)? + } + None => self.apply_delta(prev_state_json, delta_payload)?, + }; + let before = self.module_account_view(prev_state_json); + let transaction = before + .as_ref() + .map_err(Clone::clone) + .and_then(|before| self.module_transaction(delta_payload, before.nonce)); + let inputs = ModuleInputs { + before, + after: self.module_account_view(&applied.state_json), + transaction, + }; + Ok((applied, inputs)) + } + + /// [`Self::apply_delta_with_module_inputs`] on a previous state the caller has already + /// decoded, as [`Self::verify_and_apply_delta_to_account`] is to + /// [`Self::verify_and_apply_delta`]. + fn verify_and_apply_delta_to_account_with_module_inputs( + &self, + prev_proof: &str, + prev_account: miden_protocol::account::Account, + delta_payload: &serde_json::Value, + ) -> Result<(AppliedState, ModuleInputs), String> { + use guardian_shared::ToJson; + self.apply_delta_with_module_inputs( + Some(prev_proof), + &prev_account.to_json(), + delta_payload, + ) + } + /// Merge multiple deltas fn merge_deltas( &self, @@ -526,6 +609,50 @@ pub trait NetworkClient: Send + Sync { Ok(None) } + /// The account's signers and thresholds as policy modules see them. Errors on auth state + /// this network cannot interpret; an empty view is never returned. + fn module_account_view(&self, state_json: &serde_json::Value) -> Result { + let _ = state_json; + Err("policy modules are not supported on this network".into()) + } + + /// The account view and the whole vault and storage of one state, from one decode, as a + /// registration's request carries them. Called inside the reconstruction task. + fn module_account_inputs(&self, state_json: &serde_json::Value) -> ModuleAccountInputs { + ModuleAccountInputs { + view: self.module_account_view(state_json), + state: self.module_account_state(state_json), + } + } + + /// The account's whole vault and storage, as a registration's subject carries them. + fn module_account_state( + &self, + state_json: &serde_json::Value, + ) -> Result { + let _ = state_json; + Err("policy modules are not supported on this network".into()) + } + + /// The decoded effects of a transaction as policy modules see them. `tx_summary` is the + /// bare summary the Guardian verifies and signs, never a proposal wrapper; `initial_nonce` + /// is the nonce of the state it starts from, which identifies its fee note. + fn module_transaction( + &self, + tx_summary: &serde_json::Value, + initial_nonce: u64, + ) -> Result { + let _ = (tx_summary, initial_nonce); + Err("policy modules are not supported on this network".into()) + } + + /// Reads the chain's fee faucet and base fee, again once the last read is stale, so module + /// projections can tell the transaction's fee note from a payment. Until a first read + /// succeeds a transaction carrying a fee-script note cannot be projected. + async fn load_fee_faucet(&self) -> Result<(), String> { + Ok(()) + } + /// Determine if account auth should be updated given the state async fn should_update_auth( &self, diff --git a/crates/server/src/openapi.rs b/crates/server/src/openapi.rs index 553c6bf8c..7d3e44e3b 100644 --- a/crates/server/src/openapi.rs +++ b/crates/server/src/openapi.rs @@ -219,6 +219,8 @@ impl Modify for CommonResponsesAddon { crate::api::http::status, crate::api::http::status_root, crate::api::http::push_delta_proposal, + crate::api::http::check_delta_proposal, + crate::api::http::get_policies, crate::api::http::get_delta_proposals, crate::api::http::get_delta_proposal, crate::api::http::sign_delta_proposal, @@ -262,6 +264,15 @@ pub struct ClientApiDoc; crate::api::dashboard_feeds::list_account_proposals_handler, crate::api::dashboard_feeds::list_global_deltas_handler, crate::api::dashboard_feeds::list_global_proposals_handler, + crate::api::dashboard_modules::list_modules, + crate::api::dashboard_modules::account_modules, + crate::api::dashboard_modules::params_history, + crate::api::dashboard_modules::set_global_params, + crate::api::dashboard_modules::enable_module, + crate::api::dashboard_modules::disable_module, + crate::api::dashboard_modules::set_account_layer, + crate::api::dashboard_modules::remove_account_layer, + crate::api::dashboard_modules::set_assignment, ), components(schemas(ApiErrorResponse, ApiErrorMeta)), modifiers(&DashboardSecurityAddon, &CommonResponsesAddon), diff --git a/crates/server/src/services/account_status.rs b/crates/server/src/services/account_status.rs index 46669438c..0f1ca3a8b 100644 --- a/crates/server/src/services/account_status.rs +++ b/crates/server/src/services/account_status.rs @@ -127,6 +127,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/ack_delta_internal.rs b/crates/server/src/services/ack_delta_internal.rs index b61af2916..80f9ed608 100644 --- a/crates/server/src/services/ack_delta_internal.rs +++ b/crates/server/src/services/ack_delta_internal.rs @@ -4,8 +4,13 @@ use std::sync::Arc; use guardian_shared::SignatureScheme; use crate::delta_object::DeltaObject; +use crate::delta_summary::ModuleApproval; use crate::error::{GuardianError, Result}; -use crate::network::AppliedState; +use crate::metadata::AccountMetadata; +use crate::modules::HookName; +use crate::modules::pipeline::Plan; +use crate::modules::request::{self, StateRef, TransactionInput}; +use crate::network::{AppliedState, ModuleInputs}; use crate::state::AppState; /// A delta verified against the account's current state and acknowledged by Guardian, not yet @@ -16,22 +21,95 @@ pub(crate) struct AcknowledgedDelta { pub matched_proposal: bool, } -/// Verifies `delta` against the state it builds on, derives its metadata, and signs Guardian's -/// acknowledgment. The base is the canonical state for a Guardian execution and the queue tail -/// for a pushed delta. Persists nothing and sets no pending-candidate flag: the public push path -/// commits the result itself, and a Guardian execution admits it only at its boundary commit. +/// The cosigner a Guardian acknowledgment is evaluated for, the one calling `push_delta` or the +/// one whose request started a Guardian execution, and the account it acts on. +pub(crate) struct Submitter<'a> { + pub commitment: &'a str, + /// Whether the request was signed by a delegated session key rather than the wallet. + pub session: bool, + pub account: &'a AccountMetadata, +} + +/// Verifies `delta` against the state it builds on, runs the policy modules, derives its +/// metadata, and signs Guardian's acknowledgment. The base is the canonical state for a Guardian +/// execution and the queue tail for a pushed delta. Persists nothing and sets no +/// pending-candidate flag: the public push path commits the result itself, and a Guardian +/// execution admits it only at its boundary commit. pub(crate) async fn acknowledge_delta( state: &AppState, scheme: &SignatureScheme, - base_commitment: &str, - base_state_json: &serde_json::Value, + base: StateRef<'_>, delta: &DeltaObject, + submitter: Submitter<'_>, ) -> Result { - let applied = apply_to_base(state, base_commitment, base_state_json, delta).await?; - ensure_labelled_with_applied_nonce(delta, &applied)?; + let applied = apply_to_base(state, base.commitment, base.json, delta).await?; + ensure_labelled_with_applied_nonce(delta, &applied.state)?; let proposal_match = lookup_matching_proposal(state, &delta.account_id, delta.nonce, &delta.delta_payload).await; - acknowledge_applied(state, scheme, delta, applied, proposal_match.payload()).await + acknowledge_applied(state, scheme, delta, applied, submitter, &proposal_match).await +} + +/// A delta applied to the state it builds on, with the `before_transaction_approved` plan for +/// the account and, when there is one, the inputs its modules receive, built from the same +/// decode. Only [`ApprovalPlan::applied`] builds it, so no caller can reach the ack with a delta +/// whose modules were left out. +pub(crate) struct Applied<'a> { + pub state: AppliedState, + modules: Option<(Plan<'a>, ModuleInputs)>, +} + +/// The `before_transaction_approved` plan for an account, read before its delta is applied so +/// the reconstruction task that applies it knows whether to build the module inputs from the +/// same decode. +pub(crate) struct ApprovalPlan<'a>(Option>); + +impl<'a> ApprovalPlan<'a> { + /// The plan for `account_id`. When a module applies, the chain fee is loaded first, so the + /// fee note is told apart inside the reconstruction task without a network call. + pub(crate) async fn for_account(state: &'a AppState, account_id: &str) -> Result { + let plan = match state.modules.as_deref() { + Some(modules) => { + modules + .plan(HookName::BeforeTransactionApproved, account_id) + .await? + } + None => None, + }; + if plan.is_some() + && let Err(error) = state.network_client.load_fee_faucet().await + { + tracing::warn!(%error, "Fee faucet unknown; no output note is treated as the fee note"); + } + Ok(Self(plan)) + } + + /// Whether the apply must also build the module inputs. + pub(crate) fn wants_inputs(&self) -> bool { + self.0.is_some() + } + + /// The applied delta, with the inputs the plan's modules receive. A plan without inputs is + /// refused as unavailable rather than acknowledged unevaluated. + pub(crate) fn applied( + self, + state: AppliedState, + inputs: Option, + ) -> Result> { + match (self.0, inputs) { + (Some(plan), Some(inputs)) => Ok(Applied { + state, + modules: Some((plan, inputs)), + }), + (Some(_), None) => { + tracing::error!("Delta applied without the inputs its modules need; refusing it"); + Err(GuardianError::ModuleUnavailable { module: None }) + } + (None, _) => Ok(Applied { + state, + modules: None, + }), + } + } } /// Refuses a delta whose `nonce` is not the account nonce it leaves the account at (issue @@ -65,35 +143,71 @@ pub(crate) fn ensure_labelled_with_applied_nonce( } /// Verifies `delta` against the state it builds on and applies it, without signing anything. -pub(crate) async fn apply_to_base( - state: &AppState, +/// When a module applies to the account, the same decode builds what it receives, after the +/// chain fee is loaded, so request assembly decodes nothing. +pub(crate) async fn apply_to_base<'a>( + state: &'a AppState, base_commitment: &str, base_state_json: &serde_json::Value, delta: &DeltaObject, -) -> Result { +) -> Result> { + let plan = ApprovalPlan::for_account(state, &delta.account_id).await?; let client = state.network_client.clone(); let prev_commitment = base_commitment.to_string(); let prev_state_json = base_state_json.clone(); let delta_payload = Arc::new(delta.delta_payload.clone()); - crate::network::reconstructor() + let with_inputs = plan.wants_inputs(); + let (applied, inputs) = crate::network::reconstructor() .run(move || { - client.verify_and_apply_delta(&prev_commitment, &prev_state_json, &delta_payload) + if with_inputs { + client + .apply_delta_with_module_inputs( + Some(&prev_commitment), + &prev_state_json, + &delta_payload, + ) + .map(|(state, inputs)| (state, Some(inputs))) + } else { + client + .verify_and_apply_delta(&prev_commitment, &prev_state_json, &delta_payload) + .map(|state| (state, None)) + } }) - .await - .map_err(Into::into) + .await?; + plan.applied(applied, inputs) } -/// Derives the metadata of a delta already applied by [`apply_to_base`], lifting operator -/// intent from `matching_proposal` when one matched, and signs Guardian's acknowledgment of it. +/// Runs the `before_transaction_approved` policy modules on a delta already applied by +/// [`apply_to_base`], derives its metadata, lifting operator intent from the matching proposal +/// when one matched, and signs Guardian's acknowledgment of it. Every Guardian ack is produced +/// here, so no caller acknowledges a delta the modules have not approved. pub(crate) async fn acknowledge_applied( state: &AppState, scheme: &SignatureScheme, delta: &DeltaObject, - applied: AppliedState, - matching_proposal: Option<&Value>, + applied: Applied<'_>, + submitter: Submitter<'_>, + proposal_match: &ProposalMatch, ) -> Result { - let derived_metadata = + let Applied { + state: applied, + modules, + } = applied; + let approval = approve(state, delta, modules, submitter, proposal_match).await?; + let matching_proposal = proposal_match.payload(); + let mut derived_metadata = crate::delta_summary::build_metadata(&delta.delta_payload, matching_proposal); + match (derived_metadata.as_mut(), approval) { + (Some(metadata), approval) => metadata.modules = approval, + (None, Some(approval)) => tracing::warn!( + account_id = %delta.account_id, + catalog_hash = %approval.catalog_hash, + params_version = approval.params_version, + account_params_version = approval.account_params_version, + "Delta has no metadata to record its module approval in" + ), + (None, None) => {} + } let mut acknowledged = delta.clone(); acknowledged.new_commitment = Some(applied.commitment.clone()); @@ -109,6 +223,58 @@ pub(crate) async fn acknowledge_applied( }) } +/// The `before_transaction_approved` decision for `delta`, or `None` when no module applies to +/// the account. A proposal lookup that failed is a module failure, never an absent proposer. +async fn approve( + state: &AppState, + delta: &DeltaObject, + modules: Option<(Plan<'_>, ModuleInputs)>, + submitter: Submitter<'_>, + proposal_match: &ProposalMatch, +) -> Result> { + let Some((plan, inputs)) = modules else { + return Ok(None); + }; + let proposal = match proposal_match { + ProposalMatch::Found(proposal) => Ok(request::proposal_context(proposal)), + ProposalMatch::Missing => Ok(None), + ProposalMatch::Unavailable(error) => Err(format!("proposal lookup failed: {error}")), + }; + let proposer = proposal + .as_ref() + .ok() + .and_then(|context| context.as_ref()) + .map(|context| context.proposer.clone()) + .unwrap_or_default(); + let signed_at = state.clock.now(); + let network_id = plan.network_id(); + plan.run(|| { + request::transaction_request(TransactionInput { + network_id, + account_id: &delta.account_id, + submitter: submitter.commitment, + submitter_session: submitter.session, + auth: &submitter.account.auth, + network_config: &submitter.account.network_config, + inputs, + proposal: proposal?, + accounting_time: signed_at, + }) + }) + .await + .map(|evaluation| { + Some(ModuleApproval { + catalog_hash: evaluation.catalog_hash, + params_version: evaluation.params_version, + account_params_version: evaluation.account_params_version, + failed_open: evaluation.failed_open, + signed_at: signed_at.to_rfc3339(), + submitter: submitter.commitment.to_string(), + proposer, + }) + }) +} + /// The `delta_proposals` row matching a delta, as far as storage could tell. #[derive(Clone)] pub(crate) enum ProposalMatch { @@ -174,8 +340,10 @@ pub(crate) async fn lookup_matching_proposal( nonce, proposal_id = %proposal_id, error = %err, - "delta_proposals lookup errored; a multisig push is refused, and a \ - single-key push or a Guardian execution continues without proposal metadata" + "delta_proposals lookup errored; a multisig push is refused, a delta a \ + policy module evaluates is refused as unavailable, and a single-key push or \ + a Guardian execution with no module to run continues without proposal \ + metadata" ); ProposalMatch::Unavailable(err) } diff --git a/crates/server/src/services/configure_account.rs b/crates/server/src/services/configure_account.rs index c05aa985e..3dce84c81 100644 --- a/crates/server/src/services/configure_account.rs +++ b/crates/server/src/services/configure_account.rs @@ -2,6 +2,8 @@ use crate::error::{GuardianError, Result}; use crate::metadata::NetworkConfig; use crate::metadata::auth::{Auth, Credentials}; use crate::metadata::{AccountMetadata, ClearTransition}; +use crate::modules::HookName; +use crate::modules::request::{self, RegistrationInput}; use crate::network::{RpcReadMode, StateVerification}; use crate::services::{consume_auth_timestamp, validate_request_timestamp}; use crate::state::AppState; @@ -95,25 +97,7 @@ pub async fn configure_account( // it is held to the scheme policy for new accounts and counted as a // creation. A failed state read keeps the reconfiguration treatment, so // it can never block an account that does have state. - let unfinished_claim = match &existing { - Some(_) => match state - .storage - .pull_state_commitment(¶ms.account_id) - .await - { - Ok(_) => false, - Err(e) if crate::storage::is_storage_not_found(&e) => true, - Err(e) => { - tracing::warn!( - account_id = %params.account_id, - error = %e, - "Could not check for a stored state; treating the account as configured" - ); - false - } - }, - None => false, - }; + let unfinished_claim = existing.is_some() && !has_stored_state(state, ¶ms.account_id).await; // The GUARDIAN's scheme selects this server's ACK identity for the // account; every scheme the account uses, its cosigners' included, is // held to the policy for new accounts. A reconfiguration is held to it @@ -252,6 +236,44 @@ pub async fn configure_account( (head, signer_commitment) }; + // A key the registered account does not list is checked before any module judges its + // state (see `vouch_outsider`); its timestamp is consumed first, so a replay is still refused + // before any chain read. + let outsider = existing + .as_ref() + .filter(|existing| is_outsider(existing, &signer_commitment)); + let mut early_vouch = match outsider { + Some(_) => { + consume_auth_timestamp( + state, + ¶ms.account_id, + &signer_commitment, + request_timestamp, + crate::metadata::auth::MAX_TIMESTAMP_SKEW_MS, + ) + .await?; + Some(vouch_outsider(state, ¶ms, &head).await?) + } + None => None, + }; + + // A new account, or a claim whose account has no module history yet, is evaluated with the + // default modules and receives copies of them below. One an operator already configured + // (a layer, an assignment, even an emptied one) is evaluated as it is configured, since the + // copy below never overrides that. + let first_registration = match &existing { + None => true, + Some(_) => unfinished_claim && !has_module_history(state, ¶ms.account_id).await?, + }; + let default_copies = approve_registration( + state, + ¶ms, + &signer_commitment, + existing.is_some() && !unfinished_claim, + first_registration, + ) + .await?; + let now = state.clock.now_rfc3339(); // A first configuration claims the account before anything else: of two @@ -288,26 +310,82 @@ pub async fn configure_account( let claimed = state.metadata.get(¶ms.account_id).await.map_err(|e| { GuardianError::StorageError(format!("Failed to re-read account metadata: {e}")) })?; - Some(claimed.ok_or_else(|| { + let claimed = claimed.ok_or_else(|| { GuardianError::StorageError( "Account metadata vanished after a concurrent first configuration".to_string(), ) - })?) + })?; + // The modules judged this request as a new account; it is now a reconfiguration of the + // account it lost to, whose modules and stored state differ, so they judge it again + // before it consumes anything. A key that account does not list is an outsider to it, + // vouched for first like any other. + if is_outsider(&claimed, &signer_commitment) { + consume_auth_timestamp( + state, + ¶ms.account_id, + &signer_commitment, + request_timestamp, + crate::metadata::auth::MAX_TIMESTAMP_SKEW_MS, + ) + .await?; + early_vouch = Some(vouch_outsider(state, ¶ms, &head).await?); + } + approve_registration( + state, + ¶ms, + &signer_commitment, + has_stored_state(state, ¶ms.account_id).await, + false, + ) + .await?; + Some(claimed) } else { existing }; + // The account is now claimed by this request: copy the default modules it was evaluated + // with. Only an account without any assignment history receives them, so an operator's + // earlier write wins, and a crash before this point is repaired by the retry, which finds + // an unfinished claim with no history and copies again. + if (created || first_registration && existing.is_some()) + && !default_copies.is_empty() + && let Some(modules) = state.modules.as_deref() + { + let copied = modules + .store() + .seed_assignment( + ¶ms.account_id.to_ascii_lowercase(), + default_copies, + &crate::modules::store::Change { + operator: "catalog", + reason: "default modules copied at registration", + at: now.clone(), + expected_version: None, + }, + ) + .await + .map_err(GuardianError::StorageError)?; + if !copied { + tracing::warn!( + account_id = %params.account_id, + "Default modules not copied: an operator configured the account's modules while it registered; the account keeps that configuration" + ); + } + } + // The replay-state row has an FK to account metadata, which the claim // above guarantees, so every configuration consumes its timestamp - // before it writes any state. - consume_auth_timestamp( - state, - ¶ms.account_id, - &signer_commitment, - request_timestamp, - crate::metadata::auth::MAX_TIMESTAMP_SKEW_MS, - ) - .await?; + // before it writes any state (an outsider's was consumed above). + if early_vouch.is_none() { + consume_auth_timestamp( + state, + ¶ms.account_id, + &signer_commitment, + request_timestamp, + crate::metadata::auth::MAX_TIMESTAMP_SKEW_MS, + ) + .await?; + } // The stored state this re-onboarding replaces, read only once the // request is authenticated and fresh. The write below refuses to @@ -326,6 +404,7 @@ pub async fn configure_account( // may have changed since; the requesting key is not one of its stored // signers; or the submitted state is not the stored one. let vouch = match (&existing, &stored_base) { + _ if early_vouch == Some(Vouch::Chain) => Vouch::ChainBeforeModules, (_, None) if head.nonce == Some(0) => Vouch::FirstState, (Some(existing), _) if existing.released_at.is_some() @@ -358,7 +437,7 @@ pub async fn configure_account( ); GuardianError::InvalidInput(format!("Invalid first state in initial_state: {e}")) })?, - Vouch::StoredState => {} + Vouch::StoredState | Vouch::ChainBeforeModules => {} } // A state older than the stored one may replace it only while the stored @@ -482,7 +561,7 @@ pub async fn configure_account( // previous state) is undone only once the submitted state proves to be // the account's on-chain state, and stands otherwise. let chain_vouched = match vouch { - Vouch::Chain => true, + Vouch::Chain | Vouch::ChainBeforeModules => true, Vouch::StoredState | Vouch::FirstState if created => false, Vouch::StoredState | Vouch::FirstState => { let current = state.metadata.get(¶ms.account_id).await.map_err(|e| { @@ -581,6 +660,105 @@ fn reject_disallowed_scheme(state: &AppState, scheme: SignatureScheme) -> Result }) } +/// Runs `before_account_registered` for this request: with the stored state as `before` when +/// `stored`, without one for a first configuration or a claim whose state was never stored. +async fn approve_registration( + state: &AppState, + params: &ConfigureAccountParams, + signer_commitment: &str, + stored: bool, + first_registration: bool, +) -> Result> { + let (plan, default_copies) = match state.modules.as_deref() { + Some(modules) if first_registration => { + modules.plan_first_registration(¶ms.account_id).await? + } + Some(modules) => ( + modules + .plan(HookName::BeforeAccountRegistered, ¶ms.account_id) + .await?, + Vec::new(), + ), + None => (None, Vec::new()), + }; + if let Some(plan) = plan { + let stored_state = if stored { + Some( + state + .storage + .pull_state(¶ms.account_id) + .await + .map_err(|e| format!("stored state unavailable: {e}")), + ) + } else { + None + }; + // Both states are decoded once, inside the reconstruction task, so request assembly + // decodes nothing on the async path. + let client = state.network_client.clone(); + let initial_json = params.initial_state.clone(); + let stored_json = stored_state.map(|stored| stored.map(|stored| stored.state_json)); + let (initial, stored) = crate::network::reconstructor() + .run(move || { + Ok(( + client.module_account_inputs(&initial_json), + stored_json + .map(|stored| stored.and_then(|json| client.module_account_view(&json))), + )) + }) + .await?; + let network_id = plan.network_id(); + let evaluation = plan + .run(|| { + request::registration_request(RegistrationInput { + network_id, + account_id: ¶ms.account_id, + submitter: signer_commitment, + submitter_session: false, + auth: ¶ms.auth, + network_config: ¶ms.network_config, + stored, + initial, + accounting_time: state.clock.now(), + }) + }) + .await?; + evaluation.audit_failed_open( + state.auditor.as_ref(), + HookName::BeforeAccountRegistered, + ¶ms.account_id, + signer_commitment, + serde_json::Map::new(), + ); + } + Ok(default_copies) +} + +/// Whether the account already holds module assignments. +async fn has_module_history(state: &AppState, account_id: &str) -> Result { + match state.modules.as_deref() { + Some(modules) => modules.has_account_history(account_id).await, + None => Ok(false), + } +} + +/// Whether the account has a stored state. A failed read counts as stored, so it can never make +/// an account with state look unconfigured. +async fn has_stored_state(state: &AppState, account_id: &str) -> bool { + match state.storage.pull_state_commitment(account_id).await { + Ok(_) => true, + Err(e) if crate::storage::is_storage_not_found(&e) => false, + Err(e) => { + tracing::warn!( + account_id = %account_id, + error = %e, + "Could not check for a stored state; treating the account as configured" + ); + true + } + } +} + /// The stored state's commitment and nonce, or `None` when the account has /// no stored state. A row written before the server stored nonces carries /// none: it is decoded from the stored state, and the commitment is taken @@ -630,7 +808,10 @@ async fn stored_head(state: &AppState, account_id: &str) -> Result bool { + existing.auth.signer_scheme(signer_commitment).is_none() +} + +/// Vouches for an outsider's state before any module judges it. Without this, anyone could +/// submit a made-up state for someone else's account and read that account's module verdicts, +/// or hand remote modules forged states under its id. A first state is checked on its own, as +/// the vouch after the claim does; any other state against the chain, which the vouch after the +/// claim then does not repeat. +async fn vouch_outsider( + state: &AppState, + params: &ConfigureAccountParams, + head: &StateHead, +) -> Result { + let first_state = + head.nonce == Some(0) && stored_head(state, ¶ms.account_id).await?.is_none(); + if first_state { + state + .network_client + .validate_first_state(¶ms.initial_state) + .map_err(|e| { + GuardianError::InvalidInput(format!("Invalid first state in initial_state: {e}")) + })?; + return Ok(Vouch::FirstState); + } + ensure_on_chain_state(state, ¶ms.account_id, &head.commitment, None).await?; + Ok(Vouch::Chain) +} + async fn ensure_on_chain_state( state: &AppState, account_id: &str, @@ -736,6 +949,7 @@ async fn stored_state_landed(state: &AppState, account_id: &str, commitment: &st mod tests { use super::*; use crate::ack::AckRegistry; + use crate::modules::testing::StubModule; use crate::state_object::StateHead; use crate::storage::StorageBackend; use crate::testing::mocks::{MockMetadataStore, MockNetworkClient, MockStorageBackend}; @@ -767,6 +981,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage, metadata: Arc::new(metadata_store), network_client: Arc::new(network_client), @@ -3405,4 +3620,672 @@ mod tests { assert!(result.is_ok(), "got: {result:?}"); } + + struct ModuleRun { + result: Result, + storage: MockStorageBackend, + metadata: MockMetadataStore, + module: Arc, + modules: Arc, + audited: Vec, + } + + async fn configure_with_module( + existing: impl FnOnce(String) -> Option, + module: Arc, + ) -> ModuleRun { + let signers = crate::modules::testing::instance( + "signers", + &[HookName::BeforeAccountRegistered], + crate::modules::catalog::OnError::Deny, + module.clone(), + ); + configure_with_modules(existing, vec![signers], module).await + } + + /// `module` is the stub the caller inspects; `instances` is the whole catalog. + async fn configure_with_modules( + existing: impl FnOnce(String) -> Option, + instances: Vec, + module: Arc, + ) -> ModuleRun { + configure_on_chain(existing, instances, module, StateVerification::Match).await + } + + /// As [`configure_with_modules`], with the chain answering every state check with `chain`. + async fn configure_on_chain( + existing: impl FnOnce(String) -> Option, + instances: Vec, + module: Arc, + chain: StateVerification, + ) -> ModuleRun { + use crate::modules::testing::pipeline; + use crate::testing::helpers::generate_falcon_signature; + + let account_id_hex = "0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d"; + let (pubkey_hex, commitment_hex, signature_hex, timestamp) = + generate_falcon_signature(account_id_hex); + let existing = existing(commitment_hex.clone()); + let account_json = include_str!("../testing/fixtures/account.json"); + let initial_state: serde_json::Value = serde_json::from_str(account_json).unwrap(); + + let network_client = MockNetworkClient::new() + .with_validate_credential(Ok(())) + .with_get_state_head(Ok(head("0x5678", 3))) + .with_verify_commitment(Ok(chain.clone())) + .with_verify_commitment(Ok(chain)) + .with_module_views( + guardian_module_sdk::AccountView { + signer_commitments: vec![commitment_hex.clone()], + ..Default::default() + }, + guardian_module_sdk::MidenTransaction::default(), + ); + let storage = MockStorageBackend::new() + .with_submit_state(Ok(())) + .with_pull_state(Ok(crate::state_object::StateObject { + account_id: account_id_hex.into(), + state_json: initial_state.clone(), + commitment: "0x5678".into(), + nonce: Some(3), + created_at: "2024-01-01T00:00:00Z".into(), + updated_at: "2024-01-01T00:00:00Z".into(), + auth_scheme: "falcon".into(), + })); + let metadata = MockMetadataStore::new() + .with_get(Ok(existing)) + .with_set(Ok(())); + let mut state = + create_test_app_state(network_client, storage.clone(), metadata.clone()).await; + let modules = pipeline(instances); + state.modules = Some(modules.clone()); + let auditor = crate::testing::helpers::CapturingAuditor::new(); + state.auditor = Arc::new(auditor.clone()); + + let result = configure_account( + &state, + ConfigureAccountParams { + account_id: account_id_hex.to_string(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec![commitment_hex], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + initial_state, + credential: Credentials::signature(pubkey_hex, signature_hex, timestamp), + }, + ) + .await; + ModuleRun { + result, + storage, + metadata, + module, + modules, + audited: auditor.snapshot(), + } + } + + #[tokio::test] + async fn a_failure_let_through_at_registration_is_audited() { + use crate::modules::catalog::OnError; + use crate::modules::testing::{Behaviour, StubModule, instance}; + + let module = StubModule::new(Behaviour::Fail); + let failing = instance( + "signers", + &[HookName::BeforeAccountRegistered], + OnError::Allow, + module.clone(), + ); + let run = configure_with_modules(|_| None, vec![failing], module).await; + assert!(run.result.is_ok(), "{:?}", run.result); + let skipped: Vec<_> = run + .audited + .iter() + .filter(|event| event.action_kind == crate::audit::kinds::MODULES_FAILED_OPEN) + .collect(); + assert_eq!(skipped.len(), 1, "{:?}", run.audited); + assert_eq!(skipped[0].payload["hook"], "before_account_registered"); + assert_eq!(skipped[0].payload["failed_open"][0]["module_id"], "signers"); + + let clean = configure_with_module(|_| None, StubModule::allowing()).await; + assert!(clean.result.is_ok()); + assert!( + clean + .audited + .iter() + .all(|event| event.action_kind != crate::audit::kinds::MODULES_FAILED_OPEN) + ); + } + + fn existing_account( + paused: bool, + released: bool, + ) -> impl FnOnce(String) -> Option { + use chrono::TimeZone; + move |commitment| { + let at = chrono::Utc + .with_ymd_and_hms(2026, 5, 19, 14, 30, 0) + .unwrap(); + Some(AccountMetadata { + account_id: "0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d".into(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec![commitment], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + created_at: "2024-01-01T00:00:00Z".into(), + updated_at: "2024-01-01T00:00:00Z".into(), + has_pending_candidate: false, + paused_at: paused.then_some(at), + paused_reason: paused.then(|| "compliance".to_string()), + released_at: released.then_some(at), + }) + } + } + + fn assert_nothing_written(run: &ModuleRun) { + assert!(matches!( + run.result, + Err(GuardianError::ModuleDenied { .. }) + )); + assert!(run.storage.get_submit_state_calls().is_empty()); + assert!(run.metadata.get_set_calls().is_empty()); + assert!(run.metadata.clear_released_calls.lock().unwrap().is_empty()); + } + + #[tokio::test] + async fn denied_new_registration_writes_nothing_and_has_no_before_view() { + let run = configure_with_module(|_| None, StubModule::denying("signer_not_allowed")).await; + assert_nothing_written(&run); + let request = run.module.last_request().expect("module was called"); + assert!(request.before.is_none()); + assert!(request.after.is_some()); + } + + #[tokio::test] + async fn allowed_reconfiguration_keeps_the_pause_and_sees_the_stored_state() { + let run = + configure_with_module(existing_account(true, false), StubModule::allowing()).await; + run.result.expect("reconfiguration succeeds"); + let set_calls = run.metadata.get_set_calls(); + assert_eq!(set_calls.len(), 1); + assert!(set_calls[0].paused_at.is_some()); + assert!(run.module.last_request().unwrap().before.is_some()); + } + + #[tokio::test] + async fn denied_reconfiguration_of_a_paused_account_changes_nothing() { + let run = + configure_with_module(existing_account(true, false), StubModule::denying("no")).await; + assert_nothing_written(&run); + } + + /// A key the stored account does not list could otherwise submit a made-up state and read + /// the account's module verdicts: its state is checked against the chain before any module + /// runs, and a stored cosigner's request takes no extra chain read. + #[tokio::test] + async fn an_outsiders_state_is_vouched_for_before_any_module_judges_it() { + let module = StubModule::denying("signer_not_allowed"); + let outsider = configure_on_chain( + |_| existing_account(false, false)("0xother".to_string()), + vec![crate::modules::testing::instance( + "signers", + &[HookName::BeforeAccountRegistered], + crate::modules::catalog::OnError::Deny, + module.clone(), + )], + module.clone(), + StateVerification::Absent, + ) + .await; + assert!( + matches!(outsider.result, Err(GuardianError::StateNotOnChain { .. })), + "{:?}", + outsider.result + ); + assert_eq!(module.calls(), 0, "no module saw the outsider's state"); + + let cosigner = + configure_with_module(existing_account(false, false), StubModule::allowing()).await; + assert!(cosigner.result.is_ok(), "{:?}", cosigner.result); + } + + #[tokio::test] + async fn released_account_is_reactivated_only_when_modules_allow() { + let run = + configure_with_module(existing_account(false, true), StubModule::allowing()).await; + run.result.expect("re-onboarding succeeds"); + assert_eq!(run.metadata.clear_released_calls.lock().unwrap().len(), 1); + + let run = + configure_with_module(existing_account(false, true), StubModule::denying("no")).await; + assert_nothing_written(&run); + } + + /// Allows the first evaluation and denies every later one. + #[derive(Default)] + struct AllowsOnce { + calls: std::sync::atomic::AtomicUsize, + } + + #[async_trait::async_trait] + impl guardian_module_sdk::Module for AllowsOnce { + async fn describe( + &self, + _guardian: &guardian_module_sdk::DescribeRequest, + ) -> std::result::Result + { + Ok(Default::default()) + } + + async fn validate_params( + &self, + _params: &[u8], + ) -> std::result::Result + { + Ok(guardian_module_sdk::ParamsVerdict::ok()) + } + + async fn evaluate( + &self, + _request: &guardian_module_sdk::HookRequest, + ) -> std::result::Result + { + Ok( + match self.calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst) { + 0 => guardian_module_sdk::Decision::allow(), + _ => guardian_module_sdk::Decision::deny("signer_not_allowed", "re-run"), + }, + ) + } + } + + /// A first configuration that loses its claim to an account another request created + /// meanwhile, judged by `module` at `before_account_registered`. + async fn lose_the_claim_under( + module: Arc, + ) -> ( + Result, + MockMetadataStore, + MockStorageBackend, + ) { + lose_the_claim_to(module, None).await + } + + /// As [`lose_the_claim_under`]; with `winner_signer`, the account it loses to lists that + /// signer instead of the requester's key, and the chain does not hold the submitted state. + async fn lose_the_claim_to( + module: Arc, + winner_signer: Option<&str>, + ) -> ( + Result, + MockMetadataStore, + MockStorageBackend, + ) { + use crate::modules::catalog::OnError; + use crate::modules::testing::{instance, pipeline}; + use crate::testing::helpers::generate_falcon_signature; + + let account_id = "0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d"; + let (pubkey, commitment, signature, timestamp) = generate_falcon_signature(account_id); + let winner = AccountMetadata { + created_at: "2023-06-01T00:00:00Z".into(), + ..claimed_metadata(account_id, winner_signer.unwrap_or(&commitment)) + }; + let metadata = MockMetadataStore::new() + .with_get(Ok(Some(winner))) + .with_get(Ok(None)) + .with_create(Ok(false)) + .with_update_timestamp_cas(Ok(true)); + let storage = MockStorageBackend::new(); + let mut state = create_test_app_state( + MockNetworkClient::new() + .with_validate_credential(Ok(())) + .with_get_state_head(Ok(head("0x1234", 3))) + .with_verify_commitment(Ok(match winner_signer { + Some(_) => StateVerification::Absent, + None => StateVerification::Match, + })) + .with_module_views( + guardian_module_sdk::AccountView { + signer_commitments: vec![commitment.clone()], + ..Default::default() + }, + guardian_module_sdk::MidenTransaction::default(), + ), + storage.clone(), + metadata.clone(), + ) + .await; + state.modules = Some(pipeline(vec![instance( + "signers", + &[HookName::BeforeAccountRegistered], + OnError::Deny, + module, + )])); + let initial_state = + serde_json::from_str(include_str!("../testing/fixtures/account.json")).unwrap(); + let result = configure_account( + &state, + ConfigureAccountParams { + account_id: account_id.to_string(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec![commitment], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + initial_state, + credential: Credentials::signature(pubkey, signature, timestamp), + }, + ) + .await; + (result, metadata, storage) + } + + #[tokio::test] + async fn a_lost_claim_is_judged_again_against_the_winners_account() { + let module = crate::modules::testing::StubModule::allowing(); + let (result, _, storage) = lose_the_claim_under(module.clone()).await; + assert!(result.is_ok(), "{result:?}"); + assert_eq!( + module.calls(), + 2, + "once as a new account, once as a reconfiguration of the winner's" + ); + assert_eq!(storage.get_submit_state_calls().len(), 1); + } + + #[tokio::test] + async fn a_lost_claim_refused_on_the_second_judgement_consumes_and_stores_nothing() { + let (result, metadata, storage) = + lose_the_claim_under(Arc::new(AllowsOnce::default())).await; + assert!( + matches!(&result, Err(GuardianError::ModuleDenied { reason_code, .. }) if reason_code == "signer_not_allowed"), + "{result:?}" + ); + assert!( + metadata.get_update_timestamp_cas_calls().is_empty(), + "the replay timestamp is not consumed, so the request can be sent again" + ); + assert!(storage.get_submit_state_calls().is_empty()); + assert!(metadata.get_set_calls().is_empty()); + } + + fn default_instance( + id: &str, + hooks: &[HookName], + module: Arc, + ) -> crate::modules::registry::Instance { + let mut instance = crate::modules::testing::instance_with_params( + id, + hooks, + module, + serde_json::json!({ "limit": 5 }), + ); + instance.config.scope = crate::modules::catalog::Scope::Default; + instance + } + + async fn assignment_of( + modules: &crate::modules::ModulePipeline, + ) -> Vec<(String, serde_json::Value)> { + modules + .store() + .account_params("0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d") + .await + .unwrap() + .into_iter() + .filter(|row| row.kind == crate::modules::store::ParamsKind::Assignment) + .map(|row| (row.module_id, row.params)) + .collect() + } + + #[tokio::test] + async fn a_new_account_is_judged_by_default_modules_and_receives_copies_of_them() { + let module = crate::modules::testing::StubModule::allowing(); + let elsewhere = crate::modules::testing::StubModule::allowing(); + let run = configure_with_modules( + |_| None, + vec![ + default_instance( + "screening", + &[HookName::BeforeAccountRegistered], + module.clone(), + ), + default_instance( + "caps", + &[HookName::BeforeTransactionApproved], + elsewhere.clone(), + ), + ], + module.clone(), + ) + .await; + assert!(run.result.is_ok(), "{:?}", run.result); + assert_eq!( + module.calls(), + 1, + "a default instance judges the registration" + ); + assert_eq!(elsewhere.calls(), 0, "one on other hooks is not called"); + assert_eq!( + assignment_of(&run.modules).await, + vec![ + ("screening".to_string(), serde_json::json!({ "limit": 5 })), + ("caps".to_string(), serde_json::json!({ "limit": 5 })), + ], + "every default is copied with the params evaluated" + ); + } + + /// Disabling a `default` instance during an incident must not leave every account that + /// registers meanwhile without it for good: it is copied, and runs once re-enabled. + #[tokio::test] + async fn a_default_instance_disabled_at_registration_is_still_copied() { + let module = crate::modules::testing::StubModule::allowing(); + let mut disabled = default_instance( + "screening", + &[HookName::BeforeAccountRegistered], + module.clone(), + ); + disabled.config.enabled = false; + let run = configure_with_modules(|_| None, vec![disabled], module.clone()).await; + assert!(run.result.is_ok(), "{:?}", run.result); + assert_eq!(module.calls(), 0, "a disabled instance judges nothing"); + assert_eq!( + assignment_of(&run.modules).await, + vec![("screening".to_string(), serde_json::json!({ "limit": 5 }))], + ); + } + + #[tokio::test] + async fn a_refused_registration_receives_no_default_copies() { + let module = crate::modules::testing::StubModule::denying("signer_not_allowed"); + let run = configure_with_modules( + |_| None, + vec![default_instance( + "screening", + &[HookName::BeforeAccountRegistered], + module.clone(), + )], + module, + ) + .await; + assert!(matches!( + run.result, + Err(GuardianError::ModuleDenied { .. }) + )); + assert!(assignment_of(&run.modules).await.is_empty()); + } + + /// A first registration that loses the claim to an account listing other signers is an + /// outsider to that account: its state is vouched for before the modules judge it again. + #[tokio::test] + async fn losing_the_claim_to_another_signer_set_vouches_before_judging_again() { + let module = crate::modules::testing::StubModule::allowing(); + let (result, _, _) = lose_the_claim_to(module.clone(), Some("0xother")).await; + assert!( + matches!(result, Err(GuardianError::StateNotOnChain { .. })), + "{result:?}" + ); + assert_eq!( + module.calls(), + 1, + "judged once as a new account, not again on the unvouched state" + ); + } + + /// What an operator wrote to an account's modules between its claim and the retry that + /// finishes its registration. + enum Prior { + Nothing, + Layer, + EmptyAssignment, + } + + /// The retry of a first configuration that claimed the account but stored no state, after + /// `prior`. The catalog holds a `default` instance judging registrations (`module`) and an + /// `all` instance an operator can layer. + async fn finish_claim_after( + prior: Prior, + ) -> ( + Result, + Arc, + Arc, + ) { + use crate::testing::helpers::generate_falcon_signature; + + let account_id = "0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d"; + let (pubkey, commitment, signature, timestamp) = generate_falcon_signature(account_id); + let module = crate::modules::testing::StubModule::allowing(); + let mut caps = crate::modules::testing::instance( + "caps", + &[HookName::BeforeTransactionApproved], + crate::modules::catalog::OnError::Deny, + crate::modules::testing::StubModule::allowing(), + ); + caps.config.scope = crate::modules::catalog::Scope::All; + let modules = crate::modules::testing::pipeline(vec![ + default_instance( + "screening", + &[HookName::BeforeAccountRegistered], + module.clone(), + ), + caps, + ]); + let change = crate::modules::store::Change { + operator: "0xoperator", + reason: "OPS-1", + at: "2026-11-12T00:00:00Z".to_string(), + expected_version: None, + }; + match prior { + Prior::Nothing => {} + Prior::Layer => { + modules + .store() + .set_layer( + account_id, + "caps", + Some(serde_json::json!({ "limit": 1 })), + &change, + ) + .await + .unwrap(); + } + Prior::EmptyAssignment => { + modules + .store() + .set_assignment(account_id, Vec::new(), &change) + .await + .unwrap(); + } + } + let mut state = create_test_app_state( + MockNetworkClient::new() + .with_validate_credential(Ok(())) + .with_get_state_head(Ok(head("0x1234", 3))) + .with_module_views( + guardian_module_sdk::AccountView { + signer_commitments: vec![commitment.clone()], + ..Default::default() + }, + guardian_module_sdk::MidenTransaction::default(), + ), + MockStorageBackend::new() + .with_pull_state(Err("Failed to pull state: Record not found".to_string())) + .with_submit_state(Ok(())), + MockMetadataStore::new() + .with_get(Ok(Some(claimed_metadata(account_id, &commitment)))) + .with_set(Ok(())), + ) + .await; + state.modules = Some(modules.clone()); + let result = configure_account( + &state, + ConfigureAccountParams { + account_id: account_id.to_string(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec![commitment], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + initial_state: serde_json::from_str(include_str!( + "../testing/fixtures/account.json" + )) + .unwrap(), + credential: Credentials::signature(pubkey, signature, timestamp), + }, + ) + .await; + (result, modules, module) + } + + #[tokio::test] + async fn finishing_a_claim_without_module_history_copies_the_defaults_it_was_judged_by() { + let (result, modules, module) = finish_claim_after(Prior::Nothing).await; + assert!(result.is_ok(), "{result:?}"); + assert_eq!(module.calls(), 1); + assert_eq!( + assignment_of(&modules).await, + vec![("screening".to_string(), serde_json::json!({ "limit": 5 }))] + ); + } + + #[tokio::test] + async fn finishing_a_claim_an_operator_configured_meanwhile_judges_it_as_configured() { + for prior in [Prior::Layer, Prior::EmptyAssignment] { + let (result, modules, module) = finish_claim_after(prior).await; + assert!(result.is_ok(), "{result:?}"); + assert_eq!( + module.calls(), + 0, + "the defaults are not judged, since they would never be copied" + ); + assert!( + assignment_of(&modules).await.is_empty(), + "the operator's configuration stays as it was" + ); + } + } + + #[tokio::test] + async fn a_reregistering_account_keeps_its_assignment_and_gets_no_defaults() { + let module = crate::modules::testing::StubModule::allowing(); + let run = configure_with_modules( + existing_account(false, false), + vec![default_instance( + "screening", + &[HookName::BeforeAccountRegistered], + module.clone(), + )], + module.clone(), + ) + .await; + assert!(run.result.is_ok(), "{:?}", run.result); + assert_eq!( + module.calls(), + 0, + "defaults apply only to accounts that never had them" + ); + assert!(assignment_of(&run.modules).await.is_empty()); + } } diff --git a/crates/server/src/services/dashboard_account_delta_detail.rs b/crates/server/src/services/dashboard_account_delta_detail.rs index 596ec0576..7c45c33a2 100644 --- a/crates/server/src/services/dashboard_account_delta_detail.rs +++ b/crates/server/src/services/dashboard_account_delta_detail.rs @@ -10,8 +10,8 @@ use serde::Serialize; use crate::delta_object::{DeltaObject, DeltaStatus}; use crate::delta_summary::{ - DashboardDeltaCategory, DecodeWarning, DecodedNote, ProposalMetadata, StorageChange, - VaultChange, decode_full as project_detail_sections, decode_transaction_summary, + DashboardDeltaCategory, DecodeWarning, DecodedNote, ModuleApproval, ProposalMetadata, + StorageChange, VaultChange, decode_full as project_detail_sections, decode_transaction_summary, }; use crate::error::{GuardianError, Result}; use crate::services::dashboard_account_deltas::{DashboardDeltaStatus, decode_delta_status}; @@ -58,6 +58,11 @@ pub struct DashboardDeltaDetail { pub category: Option, #[serde(skip_serializing_if = "Option::is_none")] pub proposal: Option, + /// The policy module configuration that approved this delta: the catalog and params version + /// it was judged under and the module failures an `on_error = allow` instance let through. + /// Absent when no module ran. + #[serde(skip_serializing_if = "Option::is_none")] + pub modules: Option, pub input_notes: Vec, pub output_notes: Vec, @@ -188,11 +193,11 @@ fn project_delta_to_detail( ), }; - let (category, proposal) = delta + let (category, proposal, modules) = delta .metadata .as_ref() - .map(|m| (Some(m.category), m.proposal.clone())) - .unwrap_or((None, None)); + .map(|m| (Some(m.category), m.proposal.clone(), m.modules.clone())) + .unwrap_or((None, None, None)); let raw_transaction_summary = if include.raw { let extracted = extract_raw_tx_summary_base64(&delta.delta_payload); @@ -222,6 +227,7 @@ fn project_delta_to_detail( base_matches_stored_state: None, category, proposal, + modules, input_notes, output_notes, vault_changes, @@ -308,6 +314,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -494,18 +501,37 @@ mod tests { async fn canonical_delta_projects_with_metadata_header_and_decoded_sections() { let payload = create_test_delta_payload(TEST_ACCOUNT_ID); let mut delta = canonical_delta_with_payload(7, payload); + let approval = ModuleApproval { + catalog_hash: "0xcatalog".into(), + params_version: 4, + account_params_version: 2, + failed_open: vec![crate::delta_summary::FailedOpen { + module_id: "screening".into(), + layer: "global".into(), + failure: "timeout".into(), + }], + signed_at: "2026-11-09T10:00:00+00:00".into(), + submitter: "0xsigner".into(), + proposer: String::new(), + }; delta.metadata = Some(crate::delta_summary::DeltaMetadata { category: crate::delta_summary::DashboardDeltaCategory::AccountStorageChange, assets: Vec::new(), counterparty: None, note_counts: crate::delta_summary::NoteCounts::default(), proposal: None, + modules: Some(approval.clone()), }); let state = build_state(Ok(Some(falcon_metadata())), Ok(delta.clone())).await; let detail = get_account_delta_detail(&state, TEST_ACCOUNT_ID, 7, DetailIncludeFlags::default()) .await .expect("happy path"); + assert_eq!( + detail.modules, + Some(approval), + "operators read which module configuration approved the delta" + ); assert_eq!(detail.account_id, TEST_ACCOUNT_ID); assert_eq!(detail.nonce, 7); assert_eq!(detail.status, DashboardDeltaStatus::Canonical); @@ -619,6 +645,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_account_deltas.rs b/crates/server/src/services/dashboard_account_deltas.rs index 49ee7d0db..78b59617c 100644 --- a/crates/server/src/services/dashboard_account_deltas.rs +++ b/crates/server/src/services/dashboard_account_deltas.rs @@ -342,6 +342,7 @@ mod tests { proposal_type: "p2id".to_string(), ..ProposalMetadata::default() }), + modules: None, }); let entry = DashboardDeltaEntry::from_delta(&d).expect("canonical delta maps"); assert_eq!(entry.category, Some(DashboardDeltaCategory::AssetTransfer)); @@ -367,6 +368,7 @@ mod tests { proposal_type: "remove_signer".to_string(), ..ProposalMetadata::default() }), + modules: None, }); let entry = DashboardDeltaEntry::from_delta(&d).expect("canonical delta maps"); assert!(entry.note_counts.is_none()); @@ -424,6 +426,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata_store), network_client: Arc::new(MockNetworkClient::new()), @@ -532,6 +535,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -624,6 +628,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(svc), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_account_proposals.rs b/crates/server/src/services/dashboard_account_proposals.rs index e3ebf610b..47fcf87d3 100644 --- a/crates/server/src/services/dashboard_account_proposals.rs +++ b/crates/server/src/services/dashboard_account_proposals.rs @@ -321,6 +321,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata_store), network_client: Arc::new(MockNetworkClient::new()), @@ -455,6 +456,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_account_snapshot.rs b/crates/server/src/services/dashboard_account_snapshot.rs index 93d69d5a1..99a63b49a 100644 --- a/crates/server/src/services/dashboard_account_snapshot.rs +++ b/crates/server/src/services/dashboard_account_snapshot.rs @@ -183,6 +183,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(mock_storage), metadata: Arc::new(mock_metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_accounts.rs b/crates/server/src/services/dashboard_accounts.rs index a7871eba1..27d134445 100644 --- a/crates/server/src/services/dashboard_accounts.rs +++ b/crates/server/src/services/dashboard_accounts.rs @@ -526,6 +526,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(svc), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_global_deltas.rs b/crates/server/src/services/dashboard_global_deltas.rs index edd34b072..709fb3189 100644 --- a/crates/server/src/services/dashboard_global_deltas.rs +++ b/crates/server/src/services/dashboard_global_deltas.rs @@ -251,6 +251,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -359,6 +360,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -412,6 +414,7 @@ mod tests { output: 1, }, proposal: None, + modules: None, }); let d = canonical_with_metadata("0xacc1", 1, metadata); let entry = entry_from(&d, "0xacc1").expect("canonical delta maps"); diff --git a/crates/server/src/services/dashboard_global_proposals.rs b/crates/server/src/services/dashboard_global_proposals.rs index 9c4ec28ea..ef3e0e03a 100644 --- a/crates/server/src/services/dashboard_global_proposals.rs +++ b/crates/server/src/services/dashboard_global_proposals.rs @@ -281,6 +281,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -327,6 +328,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_info.rs b/crates/server/src/services/dashboard_info.rs index f83459fe3..04abb6846 100644 --- a/crates/server/src/services/dashboard_info.rs +++ b/crates/server/src/services/dashboard_info.rs @@ -171,6 +171,9 @@ pub struct DashboardBackendInfo { /// `None` when running in optimistic-commit mode; `Some(_)` when /// the canonicalization worker is active. pub canonicalization: Option, + /// Hash of the policy module catalog this replica loaded; `None` when + /// no catalog is configured. Replicas of one deploy report the same hash. + pub module_catalog_hash: Option, } #[derive(Debug, Clone, PartialEq, Eq, Serialize, utoipa::ToSchema)] @@ -300,6 +303,10 @@ pub async fn get_dashboard_info(state: &AppState) -> Result = report + let mut mine: Vec<_> = report .into_iter() .filter(|(record, _)| record.reservation.account_id == ACCOUNT) .map(|(_, outcome)| outcome) .collect(); assert_eq!(mine.len(), 1, "{mine:?}"); - mine[0] + mine.remove(0) } async fn state(&self) -> ExecutionState { diff --git a/crates/server/src/services/execute_proposal/service.rs b/crates/server/src/services/execute_proposal/service.rs index b27d56529..3c54c2db7 100644 --- a/crates/server/src/services/execute_proposal/service.rs +++ b/crates/server/src/services/execute_proposal/service.rs @@ -11,7 +11,7 @@ use crate::config::execution::{ExecutionConfig, ExecutionUnavailable}; use crate::coordination::{ExecutionLeases, InMemoryExecutionLeases, release_quietly}; use crate::delta_object::DeltaStatus; use crate::error::{GuardianError, LocalExecutionReason, Result}; -use crate::metadata::auth::Credentials; +use crate::metadata::auth::{Credentials, RequestAuthFormat}; use crate::services::account_status::ensure_account_active_metadata; use crate::services::execution_status::ExecutionEnvelope; use crate::services::resolve_account_allowing_session; @@ -346,6 +346,8 @@ pub async fn request_execution( nonce: proposal.nonce, base_commitment: proposal.prev_commitment, scheme: resolved.metadata.auth.guardian_scheme(), + requester: resolved.signer_commitment.clone(), + requester_session: credentials.auth_format() == RequestAuthFormat::Session, fence, lease, elector, diff --git a/crates/server/src/services/execute_proposal/tests.rs b/crates/server/src/services/execute_proposal/tests.rs index 8872f3e51..b2d865bc5 100644 --- a/crates/server/src/services/execute_proposal/tests.rs +++ b/crates/server/src/services/execute_proposal/tests.rs @@ -1269,3 +1269,181 @@ async fn an_unknown_submission_outcome_stays_submitted_and_holds_the_account() { .is_some() ); } + +/// A fixture whose account is evaluated by one `before_transaction_approved` instance. +async fn gated( + module: Arc, + on_error: crate::modules::catalog::OnError, + client_reason: crate::modules::catalog::ClientReason, +) -> Fixture { + use crate::modules::catalog::HookName; + let mut caps = crate::modules::testing::instance( + "caps", + &[HookName::BeforeTransactionApproved], + on_error, + module, + ); + caps.config.client_reason = client_reason; + gated_by(caps, guardian_module_sdk::MidenTransaction::default()).await +} + +/// A fixture whose account is evaluated by `module`, the executed transaction's decoded effect +/// being `projection`. +async fn gated_by( + module: crate::modules::registry::Instance, + projection: guardian_module_sdk::MidenTransaction, +) -> Fixture { + let mut f = Fixture::new(Script::default()).await; + let _ = f + .chain + .clone() + .with_module_views(guardian_module_sdk::AccountView::default(), projection); + f.state.modules = Some(crate::modules::testing::pipeline(vec![module])); + f +} + +async fn failed_with(f: &Fixture) -> ExecutionFailureCode { + f.request().await.unwrap(); + let (failed, _) = f.settle(|state| state == ExecutionState::Failed).await; + assert!( + failed.proposal_exists, + "a module refusal keeps the proposal" + ); + assert!( + f.state.storage.pull_delta(ACCOUNT, 1).await.is_err(), + "nothing is acknowledged or admitted" + ); + assert_eq!(f.calls.lock().unwrap().proved, 0, "nothing is proved"); + let error = failed.error.expect("a failed execution carries its cause"); + ExecutionFailureCode::from_parts(&error.code, error.meta.as_ref()) + .expect("the wire failure decodes to a known code") +} + +#[tokio::test] +async fn a_module_denial_ends_the_execution_before_the_ack_with_the_denial() { + use guardian_shared::execution::ModuleDenial; + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let f = gated( + module.clone(), + crate::modules::catalog::OnError::Deny, + crate::modules::catalog::ClientReason::Full, + ) + .await; + assert_eq!( + failed_with(&f).await, + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("global".into()), + client_message: None, + }) + ); + assert_eq!(module.calls(), 1); + assert_eq!( + module.last_request().map(|request| request.submitter), + Some(f.signer_commitment.clone()), + "the module evaluates the cosigner whose request started the execution" + ); +} + +#[tokio::test] +async fn a_generic_denial_on_the_execution_path_names_no_module() { + use guardian_shared::execution::ModuleDenial; + let f = gated( + crate::modules::testing::StubModule::denying("amount_cap_exceeded"), + crate::modules::catalog::OnError::Deny, + crate::modules::catalog::ClientReason::Generic, + ) + .await; + assert_eq!( + failed_with(&f).await, + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: None, + reason_code: "policy_denied".into(), + layer: None, + client_message: None, + }) + ); +} + +#[tokio::test] +async fn a_failing_fail_closed_module_ends_the_execution_as_unavailable() { + let f = gated( + crate::modules::testing::StubModule::new(crate::modules::testing::Behaviour::Fail), + crate::modules::catalog::OnError::Deny, + crate::modules::catalog::ClientReason::Full, + ) + .await; + assert_eq!( + failed_with(&f).await, + ExecutionFailureCode::ModuleUnavailable { + module: Some("caps".into()) + } + ); +} + +#[tokio::test] +async fn an_approving_module_lets_the_execution_through_and_is_recorded_on_the_delta() { + let module = crate::modules::testing::StubModule::allowing(); + let f = gated( + module.clone(), + crate::modules::catalog::OnError::Deny, + crate::modules::catalog::ClientReason::Full, + ) + .await; + f.request().await.unwrap(); + f.settle(is_submitted_or_terminal).await; + assert_eq!(module.calls(), 1); + let candidate = f + .state + .storage + .pull_delta(ACCOUNT, 1) + .await + .expect("the boundary admitted a candidate"); + assert!( + candidate + .metadata + .and_then(|metadata| metadata.modules) + .is_some(), + "the approval is recorded on the acknowledged delta" + ); +} + +#[tokio::test] +async fn a_guardian_execution_over_a_mandatory_cap_is_refused_before_anything_is_proved() { + use guardian_shared::execution::ModuleDenial; + const USDC: &str = "0x00000000000000000000000000aa00"; + let cap = crate::modules::testing::instance_with_params( + "caps", + &[crate::modules::catalog::HookName::BeforeTransactionApproved], + Arc::new(guardian_module_sdk::policies::SpendingLimit), + serde_json::json!({ "max_per_transaction": { USDC: "1000" } }), + ); + let paying_5000 = guardian_module_sdk::MidenTransaction { + output_notes: vec![guardian_module_sdk::OutputNote { + note_id: "0xnote".into(), + assets: vec![guardian_module_sdk::Asset { + faucet_id: USDC.into(), + value: Some(guardian_module_sdk::proto::asset::Value::FungibleAmount( + "5000".into(), + )), + }], + p2id_target: Some("0xrecipient".into()), + ..Default::default() + }], + ..Default::default() + }; + let f = gated_by(cap, paying_5000).await; + assert_eq!( + failed_with(&f).await, + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("global".into()), + client_message: Some( + "The transaction sends more than this Guardian allows per transaction.".into() + ), + }) + ); + assert_eq!(f.calls.lock().unwrap().submitted, 0, "nothing is submitted"); +} diff --git a/crates/server/src/services/execute_proposal/worker.rs b/crates/server/src/services/execute_proposal/worker.rs index d26168d97..6278f7855 100644 --- a/crates/server/src/services/execute_proposal/worker.rs +++ b/crates/server/src/services/execute_proposal/worker.rs @@ -7,6 +7,7 @@ use std::sync::Arc; use chrono::{DateTime, Utc}; use guardian_shared::SignatureScheme; +use guardian_shared::execution::ModuleDenial; use super::executor::{ ExecutedTransactionInfo, ExecutionAttempt, GuardianAck, ProvenTransactionInfo, @@ -14,9 +15,10 @@ use super::executor::{ }; use crate::coordination::{LeaderElector, Lease, Renewal, release_quietly}; use crate::delta_object::{DeltaObject, DeltaStatus}; -use crate::error::GuardianError; +use crate::error::{GENERIC_REASON_CODE, GuardianError}; +use crate::modules::request::StateRef; use crate::services::account_status::ensure_account_active_metadata; -use crate::services::ack_delta_internal::{AcknowledgedDelta, acknowledge_delta}; +use crate::services::ack_delta_internal::{AcknowledgedDelta, Submitter, acknowledge_delta}; use crate::state::AppState; use crate::storage::execution::ExpirationBound; use crate::storage::{ @@ -31,6 +33,12 @@ pub(super) struct ExecutionJob { pub nonce: u64, pub base_commitment: String, pub scheme: SignatureScheme, + /// The cosigner whose authenticated request started this attempt: the submitter the policy + /// modules evaluate the acknowledgement for. A repeated request joins the running attempt, + /// which keeps it. + pub requester: String, + /// Whether that request was signed by a delegated session key. + pub requester_session: bool, pub fence: LeaseFence, pub lease: Lease, pub elector: Arc, @@ -440,16 +448,69 @@ async fn acknowledge( status: DeltaStatus::candidate(Utc::now().to_rfc3339()), metadata: None, }; + let registered = state + .metadata + .get(&job.account_id) + .await + .map_err(|e| { + ExecutionFailure::with_logged_cause( + ExecutionFailureCode::AccountInadmissible, + "Guardian could not read the account's registration", + &e, + ) + })? + .ok_or_else(|| { + ExecutionFailure::new( + ExecutionFailureCode::AccountInadmissible, + "the account is no longer registered with Guardian", + ) + })?; acknowledge_delta( state, &job.scheme, - ¤t_state.commitment, - ¤t_state.state_json, + StateRef { + commitment: ¤t_state.commitment, + json: ¤t_state.state_json, + }, &delta, + Submitter { + commitment: &job.requester, + session: job.requester_session, + account: ®istered, + }, ) .await .map_err(|error| { let failure = match error { + GuardianError::ModuleDenied { + ref module, + ref reason_code, + ref layer, + ref client_message, + } => ExecutionFailure::new( + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: Some(module.clone()), + reason_code: reason_code.clone(), + layer: Some(layer.clone()), + client_message: client_message.clone(), + }), + error.user_message(), + ), + GuardianError::ModuleDeniedGeneric => ExecutionFailure::new( + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: None, + reason_code: GENERIC_REASON_CODE.to_string(), + layer: None, + client_message: None, + }), + error.user_message(), + ), + GuardianError::ModuleUnavailable { ref module } => ExecutionFailure::new( + ExecutionFailureCode::ModuleUnavailable { + module: module.clone(), + }, + error.user_message(), + ), GuardianError::SigningError(_) | GuardianError::StorageError(_) | GuardianError::ConfigurationError(_) => ExecutionFailure::with_logged_cause( @@ -769,7 +830,7 @@ async fn submit( /// Resolves a send the node refused: its candidate is dropped, and its proposal with it unless /// the cause leaves the proposal executable (`ExecutionFailureCode::ends_proposal`). async fn resolve_refused_send(state: &AppState, job: &ExecutionJob, failure: ExecutionFailure) { - let code = failure.code; + let code = failure.code.clone(); match state .storage .resolve_execution(state.metadata.as_ref(), resolution(job, failure)) @@ -801,7 +862,7 @@ async fn fail( total_ms = timings.total_ms(), "Guardian execution failed before submission" ); - let code = failure.code; + let code = failure.code.clone(); match state.storage.fail_execution(resolution(job, failure)).await { Ok(ResolveWrite::Resolved) => crate::metrics::execution::record_outcome(Some(&code)), Ok(ResolveWrite::AlreadyResolved) => {} diff --git a/crates/server/src/services/get_delta_history.rs b/crates/server/src/services/get_delta_history.rs index 401adeab9..75701cbd1 100644 --- a/crates/server/src/services/get_delta_history.rs +++ b/crates/server/src/services/get_delta_history.rs @@ -264,6 +264,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(MockStorageBackend::new()), metadata: Arc::new(MockMetadataStore::new()), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/get_policies.rs b/crates/server/src/services/get_policies.rs new file mode 100644 index 000000000..57907090f --- /dev/null +++ b/crates/server/src/services/get_policies.rs @@ -0,0 +1,47 @@ +use crate::error::{GuardianError, Result}; +use crate::metadata::auth::Credentials; +use crate::modules::disclosure::PolicyEntry; +use crate::services::resolve_account_for_read; +use crate::state::AppState; + +#[derive(Debug, Clone)] +pub struct GetPoliciesParams { + pub account_id: String, + pub credentials: Credentials, +} + +#[derive(Debug, Clone)] +pub struct GetPoliciesResult { + pub account_id: String, + pub policies: Vec, +} + +/// The policies that apply to the account, for its cosigners, filtered by each instance's +/// disclosure (RFC 0002 section 2.7). Empty when no modules are configured. +#[tracing::instrument(level = "info", skip(state, params), fields(account_id = %params.account_id))] +pub async fn get_policies( + state: &AppState, + params: GetPoliciesParams, +) -> Result { + let resolved = resolve_account_for_read( + state, + ¶ms.account_id, + ¶ms.credentials, + guardian_shared::session_request::SessionOperation::GetPolicies, + ) + .await?; + if resolved.metadata.network_config.is_evm() { + return Err(GuardianError::UnsupportedForNetwork { + network: "evm".to_string(), + operation: "get_policies".to_string(), + }); + } + let policies = match state.modules.as_deref() { + Some(modules) => modules.disclosed(¶ms.account_id).await?, + None => Vec::new(), + }; + Ok(GetPoliciesResult { + account_id: params.account_id.to_ascii_lowercase(), + policies, + }) +} diff --git a/crates/server/src/services/mod.rs b/crates/server/src/services/mod.rs index 8cef05649..035f96546 100644 --- a/crates/server/src/services/mod.rs +++ b/crates/server/src/services/mod.rs @@ -43,6 +43,7 @@ mod get_delta_history; mod get_delta_proposal; mod get_delta_proposals; mod get_delta_since; +mod get_policies; mod get_state; mod get_state_tail; mod lookup_account; @@ -113,12 +114,14 @@ pub use get_delta_proposals::{ GetDeltaProposalsParams, GetDeltaProposalsResult, get_delta_proposals, }; pub use get_delta_since::{GetDeltaSinceParams, GetDeltaSinceResult, get_delta_since}; +pub use get_policies::{GetPoliciesParams, GetPoliciesResult, get_policies}; pub use get_state::{GetStateParams, GetStateResult, get_state}; pub use get_state_tail::{GetStateTailParams, QueuedCandidate, StateTail, get_state_tail}; pub use lookup_account::{LookupAccountParams, LookupAccountResult, lookup_account}; pub use push_delta::{PushDeltaParams, PushDeltaResult, push_delta}; pub use push_delta_proposal::{ - PushDeltaProposalParams, PushDeltaProposalResult, push_delta_proposal, + CheckProposalResult, PushDeltaProposalParams, PushDeltaProposalResult, check_proposal, + push_delta_proposal, }; pub use revoke_all_sessions::{ RevokeAllSessionsParams, RevokeAllSessionsResult, revoke_all_sessions, @@ -370,6 +373,8 @@ impl SessionReadKind { | SessionOperation::GetDeltaProposal | SessionOperation::GetDeltaProposalExecution | SessionOperation::GetCurrentExecution + | SessionOperation::GetPolicies + | SessionOperation::CheckDeltaProposal | SessionOperation::PushDelta | SessionOperation::PushDeltaProposal | SessionOperation::SignDeltaProposal @@ -1180,6 +1185,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(network), diff --git a/crates/server/src/services/push_delta.rs b/crates/server/src/services/push_delta.rs index 76e876e45..2cc7dd227 100644 --- a/crates/server/src/services/push_delta.rs +++ b/crates/server/src/services/push_delta.rs @@ -1,11 +1,11 @@ use crate::delta_object::DeltaObject; use crate::error::{GuardianError, Result}; use crate::metadata::auth::{Credentials, RequestAuthFormat}; -use crate::network::{AppliedState, NetworkClient}; +use crate::network::{AppliedState, ModuleInputs, NetworkClient}; use crate::services::account_status::ensure_account_active_metadata; use crate::services::ack_delta_internal::{ - ProposalMatch, acknowledge_applied, ensure_labelled_with_applied_nonce, - lookup_matching_proposal, + ApprovalPlan, ProposalMatch, Submitter, acknowledge_applied, + ensure_labelled_with_applied_nonce, lookup_matching_proposal, }; use crate::services::candidate_chain::{self, CandidateChain}; use crate::services::delta_commit::{CommitContext, DeltaCommitStrategy}; @@ -162,19 +162,21 @@ pub async fn push_delta(state: &AppState, params: PushDeltaParams) -> Result Result Result { + /// The applied tail, with the policy module inputs built from the same + /// decode when `with_module_inputs`, or why the push is refused. A delta + /// that does not verify or apply is `invalid_delta`, as before. + fn run(self) -> Result<(AppliedState, Option)> { match TailAccount::decode(&self.tail_json) { TailAccount::Multisig(multisig) => { let proposal = match &self.proposal { @@ -268,17 +277,42 @@ impl TailAdmission { Err(GuardianError::WalletSignatureRequired) } TailAccount::SingleKey(account) => self.apply_to(account), + TailAccount::Undecodable if self.with_module_inputs => self + .client + .apply_delta_with_module_inputs( + Some(&self.tail_commitment), + &self.tail_json, + &self.delta_payload, + ) + .map(|(applied, inputs)| (applied, Some(inputs))) + .map_err(GuardianError::InvalidDelta), TailAccount::Undecodable => self .client .verify_and_apply_delta(&self.tail_commitment, &self.tail_json, &self.delta_payload) + .map(|applied| (applied, None)) .map_err(GuardianError::InvalidDelta), } } - fn apply_to(&self, account: Account) -> Result { - self.client - .verify_and_apply_delta_to_account(&self.tail_commitment, account, &self.delta_payload) - .map_err(GuardianError::InvalidDelta) + fn apply_to(&self, account: Account) -> Result<(AppliedState, Option)> { + let applied = if self.with_module_inputs { + self.client + .verify_and_apply_delta_to_account_with_module_inputs( + &self.tail_commitment, + account, + &self.delta_payload, + ) + .map(|(applied, inputs)| (applied, Some(inputs))) + } else { + self.client + .verify_and_apply_delta_to_account( + &self.tail_commitment, + account, + &self.delta_payload, + ) + .map(|applied| (applied, None)) + }; + applied.map_err(GuardianError::InvalidDelta) } } @@ -287,6 +321,7 @@ mod tests { use super::*; use crate::metadata::AccountMetadata; use crate::metadata::auth::Auth; + use crate::modules::HookName; use crate::testing::helpers::create_test_app_state_with_mocks; use crate::testing::mocks::{MockMetadataStore, MockNetworkClient, MockStorageBackend}; use chrono::TimeZone; @@ -1587,6 +1622,28 @@ mod tests { threshold: u32, procedure_overrides: &[(miden_protocol::Word, u32)], lookup: ProposalLookup, + ) -> (Result, MockStorageBackend) { + push_on_multisig_gated_by( + request_signer, + approvers, + approver_schemes, + threshold, + procedure_overrides, + lookup, + None, + ) + .await + } + + /// As `push_on_multisig_signed_by`, with `modules` evaluating the push. + async fn push_on_multisig_gated_by( + request_signer: RequestSigner, + approvers: &[String], + approver_schemes: &[guardian_shared::SignatureScheme], + threshold: u32, + procedure_overrides: &[(miden_protocol::Word, u32)], + lookup: ProposalLookup, + modules: Option>, ) -> (Result, MockStorageBackend) { let (result, storage, _network) = push_on_multisig_observed( request_signer, @@ -1595,6 +1652,7 @@ mod tests { threshold, procedure_overrides, lookup, + modules, ) .await; (result, storage) @@ -1607,6 +1665,7 @@ mod tests { threshold: u32, procedure_overrides: &[(miden_protocol::Word, u32)], lookup: ProposalLookup, + modules: Option>, ) -> ( Result, MockStorageBackend, @@ -1673,7 +1732,19 @@ mod tests { .with_apply_delta(Ok(( serde_json::json!({"new_state": true}), "0xnew_commitment".to_string(), - ))); + ))) + .with_module_views( + guardian_module_sdk::AccountView { + signer_commitments: approvers.to_vec(), + signer_schemes: approvers + .iter() + .map(|approver| (approver.clone(), "falcon".to_string())) + .collect(), + default_threshold: Some(threshold), + ..Default::default() + }, + guardian_module_sdk::MidenTransaction::default(), + ); let metadata = MockMetadataStore::new().with_get(Ok(Some(AccountMetadata { account_id: account_id.clone(), auth: Auth::MidenFalconRpo { @@ -1687,11 +1758,12 @@ mod tests { paused_reason: None, released_at: None, }))); - let state = create_test_app_state_with_mocks( + let mut state = create_test_app_state_with_mocks( Arc::new(storage.clone()), Arc::new(network.clone()), Arc::new(metadata), ); + state.modules = modules; let credentials = match request_signer { RequestSigner::Wallet => { let (signature, timestamp) = caller.sign(&account_id); @@ -1813,6 +1885,7 @@ mod tests { falcon_approval(&first, &summary), falcon_approval(&second, &summary), ]), + None, ) .await; assert!(result.is_ok(), "{result:?}"); @@ -1832,6 +1905,63 @@ mod tests { ); } + #[tokio::test] + async fn a_gated_multisig_push_builds_module_inputs_from_the_account_its_gate_decoded() { + use crate::testing::helpers::TestSigner; + + let first = TestSigner::new(); + let second = TestSigner::new(); + let summary = pushed_summary(); + let (result, _storage, network) = push_on_multisig_observed( + RequestSigner::Wallet, + &[first.commitment_hex.clone(), second.commitment_hex.clone()], + &[], + 2, + &[], + ProposalLookup::Signatures(vec![ + falcon_approval(&first, &summary), + falcon_approval(&second, &summary), + ]), + Some(crate::modules::testing::pipeline(vec![ + crate::modules::testing::instance( + "approvals", + &[HookName::BeforeTransactionApproved], + crate::modules::catalog::OnError::Deny, + crate::modules::testing::StubModule::allowing(), + ), + ])), + ) + .await; + let pushed = result.expect("an allowing module acknowledges the push"); + assert!( + pushed + .delta + .metadata + .is_some_and(|metadata| metadata.modules.is_some()), + "the approval is recorded" + ); + assert_eq!( + network + .verify_and_apply_delta_to_account_calls + .lock() + .unwrap() + .len(), + 1, + "the account the gate decoded is the one applied and viewed" + ); + assert_eq!( + *network.verify_and_apply_delta_json_calls.lock().unwrap(), + 0, + "the tail is never decoded again from its JSON" + ); + assert_eq!( + network + .module_decodes + .load(std::sync::atomic::Ordering::SeqCst), + 3 + ); + } + #[tokio::test] async fn multisig_push_counts_a_verified_ecdsa_approver() { let approver = crate::testing::helpers::TestEcdsaSigner::new(); @@ -2407,4 +2537,497 @@ mod tests { assert!(result.is_ok(), "{result:?}"); assert_eq!(storage.get_submit_delta_calls().len(), 1); } + + #[tokio::test] + async fn modules_learn_whether_the_submitter_signed_through_a_session() { + use crate::modules::testing::{StubModule, instance, pipeline}; + use crate::testing::helpers::TestSigner; + + for (request_signer, through_session) in [ + (RequestSigner::Wallet, false), + (RequestSigner::Session, true), + ] { + let first = TestSigner::new(); + let second = TestSigner::new(); + let summary = pushed_summary(); + let module = StubModule::allowing(); + let (result, _) = push_on_multisig_gated_by( + request_signer, + &[first.commitment_hex.clone(), second.commitment_hex.clone()], + &[], + 2, + &[], + ProposalLookup::Signatures(vec![ + falcon_approval(&first, &summary), + falcon_approval(&second, &summary), + ]), + Some(pipeline(vec![instance( + "caps", + &[HookName::BeforeTransactionApproved], + crate::modules::catalog::OnError::Deny, + module.clone(), + )])), + ) + .await; + assert!(result.is_ok(), "{result:?}"); + let request = module.last_request().expect("the module was called"); + assert_eq!(request.submitter_session, through_session); + assert_eq!(request.network_id, "local"); + } + } + + async fn push_with_modules( + module: Arc, + ) -> (Result, MockStorageBackend, String) { + push_with_modules_when( + module, + |_| Err("proposal not found".to_string()), + crate::modules::catalog::OnError::Deny, + ) + .await + } + + /// `proposal` builds the proposal lookup's result from the account id. + async fn push_with_modules_when( + module: Arc, + proposal: impl FnOnce(&str) -> std::result::Result, + on_error: crate::modules::catalog::OnError, + ) -> (Result, MockStorageBackend, String) { + push_through( + crate::modules::testing::instance( + "caps", + &[HookName::BeforeTransactionApproved], + on_error, + module, + ), + guardian_module_sdk::MidenTransaction::default(), + proposal, + ) + .await + } + + /// Pushes a delta whose decoded effect is `projection` to a Guardian running `module`. + async fn push_through( + module: crate::modules::registry::Instance, + projection: guardian_module_sdk::MidenTransaction, + proposal: impl FnOnce(&str) -> std::result::Result, + ) -> (Result, MockStorageBackend, String) { + let (result, storage, signer, _) = push_on(Some(module), projection, proposal).await; + (result, storage, signer) + } + + async fn push_on( + module: Option, + projection: guardian_module_sdk::MidenTransaction, + proposal: impl FnOnce(&str) -> std::result::Result, + ) -> ( + Result, + MockStorageBackend, + String, + MockNetworkClient, + ) { + push_on_projected(module, Some(projection), proposal).await + } + + /// [`push_on`] where the network decodes the transaction to `projection`, or fails to + /// project it when `None`. + async fn push_on_projected( + module: Option, + projection: Option, + proposal: impl FnOnce(&str) -> std::result::Result, + ) -> ( + Result, + MockStorageBackend, + String, + MockNetworkClient, + ) { + use crate::delta_object::DeltaStatus; + use crate::modules::testing::pipeline; + use crate::state_object::StateObject; + use crate::testing::helpers::create_test_delta_payload; + + let account_id = "0x7b7b7b7a7b7b7b017b7b7b7b7b7b7b".to_string(); + let (signer_pubkey, signer_commitment, signer_signature, signer_timestamp) = + crate::testing::helpers::generate_falcon_signature(&account_id); + let storage = MockStorageBackend::new() + .with_pull_state(Ok(StateObject { + account_id: account_id.clone(), + state_json: serde_json::json!({}), + commitment: "0xprev".into(), + nonce: None, + created_at: "2026-05-25T08:00:00Z".into(), + updated_at: "2026-05-25T08:00:00Z".into(), + auth_scheme: String::new(), + })) + .with_pull_deltas_after(Ok(Vec::new())) + .with_pull_delta_proposal(proposal(&account_id)) + .with_submit_state(Ok(())) + .with_submit_delta(Ok(())); + let network = MockNetworkClient::new() + .with_validate_credential(Ok(())) + .with_verify_delta(Ok(())) + .with_apply_delta(Ok(( + serde_json::json!({"new_state": true}), + "0xnew".to_string(), + ))) + .with_module_views( + guardian_module_sdk::AccountView { + signer_commitments: vec![signer_commitment.clone()], + ..Default::default() + }, + projection.clone().unwrap_or_default(), + ); + if projection.is_none() { + *network.module_projection.lock().unwrap() = None; + } + let metadata = MockMetadataStore::new().with_get(Ok(Some(AccountMetadata { + account_id: account_id.clone(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec![signer_commitment.clone()], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + created_at: "2026-05-01T00:00:00Z".into(), + updated_at: "2026-05-01T00:00:00Z".into(), + has_pending_candidate: false, + paused_at: None, + paused_reason: None, + released_at: None, + }))); + let mut state = create_test_app_state_with_mocks( + Arc::new(storage.clone()), + Arc::new(network.clone()), + Arc::new(metadata), + ); + state.modules = module.map(|module| pipeline(vec![module])); + let params = PushDeltaParams { + delta: DeltaObject { + account_id: account_id.clone(), + nonce: 1, + prev_commitment: "0xprev".into(), + new_commitment: None, + delta_payload: create_test_delta_payload(&account_id), + ack_sig: String::new(), + ack_pubkey: String::new(), + ack_scheme: String::new(), + status: DeltaStatus::default(), + metadata: None, + }, + credentials: Credentials::signature(signer_pubkey, signer_signature, signer_timestamp), + }; + ( + push_delta(&state, params).await, + storage, + signer_commitment, + network, + ) + } + + #[tokio::test] + async fn without_modules_a_push_builds_no_view_or_projection_and_records_no_approval() { + let (result, storage, _, network) = + push_on(None, paying(5_000), stored_proposal_labelled("p2id")).await; + let pushed = result.expect("acknowledged as before modules existed"); + assert_eq!(storage.get_submit_delta_calls().len(), 1); + assert_eq!( + network + .module_decodes + .load(std::sync::atomic::Ordering::SeqCst), + 0 + ); + assert!( + pushed + .delta + .metadata + .is_none_or(|metadata| metadata.modules.is_none()) + ); + let (_, _, _, gated) = push_on( + Some(cap_of_1000()), + paying(500), + stored_proposal_labelled("p2id"), + ) + .await; + assert_eq!( + gated + .module_decodes + .load(std::sync::atomic::Ordering::SeqCst), + 3, + "the same push with a module builds both views and the projection, once each" + ); + let (_, _, _, elsewhere) = push_on( + Some(crate::modules::testing::instance( + "proposals-only", + &[HookName::BeforeProposalCreated], + crate::modules::catalog::OnError::Deny, + crate::modules::testing::StubModule::allowing(), + )), + paying(500), + stored_proposal_labelled("p2id"), + ) + .await; + assert_eq!( + elsewhere + .module_decodes + .load(std::sync::atomic::Ordering::SeqCst), + 0, + "a module on another hook builds nothing for a push" + ); + } + + /// A transaction the network cannot project for the modules is refused as unavailable, a + /// retryable module refusal rather than a hard error of the push, and a fail-open instance + /// does not let it through: the requester shapes the transaction. + #[tokio::test] + async fn a_transaction_that_cannot_be_projected_is_refused_even_by_a_fail_open_module() { + let (refused, storage, _, _) = + push_on_projected(Some(cap_of_1000()), None, stored_proposal_labelled("p2id")).await; + assert!( + matches!(refused, Err(GuardianError::ModuleUnavailable { .. })), + "{refused:?}" + ); + assert!(storage.get_submit_delta_calls().is_empty()); + + let mut lenient = cap_of_1000(); + lenient.config.on_error = crate::modules::catalog::OnError::Allow; + let (still_refused, storage, _, _) = + push_on_projected(Some(lenient), None, stored_proposal_labelled("p2id")).await; + assert!( + matches!(still_refused, Err(GuardianError::ModuleUnavailable { .. })), + "{still_refused:?}" + ); + assert!(storage.get_submit_delta_calls().is_empty()); + } + + const USDC: &str = "0x00000000000000000000000000aa00"; + + fn cap_of_1000() -> crate::modules::registry::Instance { + crate::modules::testing::instance_with_params( + "caps", + &[HookName::BeforeTransactionApproved], + Arc::new(guardian_module_sdk::policies::SpendingLimit), + serde_json::json!({ "max_per_transaction": { USDC: "1000" } }), + ) + } + + fn paying(amount: u64) -> guardian_module_sdk::MidenTransaction { + guardian_module_sdk::MidenTransaction { + output_notes: vec![guardian_module_sdk::OutputNote { + note_id: "0xnote".into(), + assets: vec![guardian_module_sdk::Asset { + faucet_id: USDC.into(), + value: Some(guardian_module_sdk::proto::asset::Value::FungibleAmount( + amount.to_string(), + )), + }], + p2id_target: Some("0xrecipient".into()), + ..Default::default() + }], + ..Default::default() + } + } + + fn stored_proposal_labelled( + proposal_type: &'static str, + ) -> impl FnOnce(&str) -> std::result::Result { + move |account_id| { + Ok(DeltaObject { + account_id: account_id.to_string(), + nonce: 1, + status: crate::delta_object::DeltaStatus::Pending { + timestamp: "2026-05-25T08:00:00Z".into(), + proposer_id: "0xproposer".into(), + cosigner_sigs: Vec::new(), + }, + delta_payload: serde_json::json!({ "metadata": { "proposal_type": proposal_type } }), + ..Default::default() + }) + } + } + + fn no_stored_proposal(_: &str) -> std::result::Result { + Err("proposal not found".to_string()) + } + + fn assert_refused_by_the_cap(result: &Result, storage: &MockStorageBackend) { + assert!( + matches!( + result, + Err(GuardianError::ModuleDenied { module, reason_code, layer, .. }) + if module == "caps" && reason_code == "amount_cap_exceeded" && layer == "global" + ), + "{result:?}" + ); + assert!( + storage.get_submit_delta_calls().is_empty(), + "nothing signed or stored" + ); + } + + #[tokio::test] + async fn a_payment_under_a_mandatory_cap_is_acknowledged_as_without_modules() { + let (result, storage, _) = + push_through(cap_of_1000(), paying(500), stored_proposal_labelled("p2id")).await; + assert!(result.is_ok(), "{result:?}"); + assert_eq!(storage.get_submit_delta_calls().len(), 1); + } + + #[tokio::test] + async fn a_payment_over_a_mandatory_cap_is_refused_through_a_stored_proposal() { + let (result, storage, _) = push_through( + cap_of_1000(), + paying(5_000), + stored_proposal_labelled("p2id"), + ) + .await; + assert_refused_by_the_cap(&result, &storage); + } + + #[tokio::test] + async fn a_payment_over_a_mandatory_cap_signed_offline_is_refused_without_a_proposal() { + let (result, storage, _) = + push_through(cap_of_1000(), paying(5_000), no_stored_proposal).await; + assert_refused_by_the_cap(&result, &storage); + } + + #[tokio::test] + async fn the_decision_follows_the_effect_not_the_proposal_label() { + let (result, storage, _) = push_through( + cap_of_1000(), + paying(5_000), + stored_proposal_labelled("change_threshold"), + ) + .await; + assert_refused_by_the_cap(&result, &storage); + } + + #[tokio::test] + async fn a_failed_proposal_lookup_is_a_module_failure_not_an_empty_proposer() { + use crate::modules::catalog::OnError; + let lookup_fails = |_: &str| Err("connection reset by peer".to_string()); + + let module = crate::modules::testing::StubModule::allowing(); + let (result, storage, _) = + push_with_modules_when(module.clone(), lookup_fails, OnError::Deny).await; + assert!(matches!( + result, + Err(GuardianError::ModuleUnavailable { module }) if module.as_deref() == Some("caps") + )); + assert_eq!( + module.calls(), + 0, + "the module never sees a request without its proposer" + ); + assert!(storage.get_submit_delta_calls().is_empty()); + + let module = crate::modules::testing::StubModule::allowing(); + let (result, storage, _) = + push_with_modules_when(module.clone(), lookup_fails, OnError::Allow).await; + assert!( + matches!(result, Err(GuardianError::ModuleUnavailable { .. })), + "a request that cannot be built is refused even by a fail-open module: {result:?}" + ); + assert_eq!(module.calls(), 0); + assert!(storage.get_submit_delta_calls().is_empty()); + } + + #[tokio::test] + async fn the_one_proposal_read_gives_modules_the_proposer() { + use crate::delta_object::DeltaStatus; + let module = crate::modules::testing::StubModule::allowing(); + let pending = |account_id: &str| { + Ok(DeltaObject { + account_id: account_id.to_string(), + nonce: 1, + status: DeltaStatus::Pending { + timestamp: "2026-05-25T08:00:00Z".into(), + proposer_id: "0xproposer".into(), + cosigner_sigs: Vec::new(), + }, + delta_payload: serde_json::json!({ "metadata": { "proposal_type": "p2id" } }), + ..Default::default() + }) + }; + let (result, storage, _) = push_with_modules_when( + module.clone(), + pending, + crate::modules::catalog::OnError::Deny, + ) + .await; + let pushed = result.expect("allowed push succeeds"); + assert_eq!( + pushed + .delta + .metadata + .and_then(|metadata| metadata.modules) + .map(|approval| approval.proposer), + Some("0xproposer".to_string()), + "the approval records the proposer the modules saw" + ); + assert_eq!( + storage.get_pull_delta_proposal_calls().len(), + 2, + "one read for metadata and modules, one by the optimistic commit to delete the proposal" + ); + let request = module.last_request().expect("module was called"); + match request.subject { + Some(guardian_module_sdk::proto::hook_request::Subject::Transaction(subject)) => { + assert_eq!(subject.proposer, "0xproposer"); + } + other => panic!("unexpected subject {other:?}"), + } + } + + #[tokio::test] + async fn module_denial_refuses_the_ack_and_stores_nothing() { + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let (result, storage, _) = push_with_modules(module.clone()).await; + assert!(matches!( + result, + Err(GuardianError::ModuleDenied { module, reason_code, .. }) + if module == "caps" && reason_code == "amount_cap_exceeded" + )); + assert!(storage.get_submit_delta_calls().is_empty()); + assert_eq!(module.calls(), 1); + } + + #[tokio::test] + async fn module_allow_acks_and_receives_the_submitter_and_views() { + let module = crate::modules::testing::StubModule::allowing(); + let (result, storage, signer) = push_with_modules(module.clone()).await; + let pushed = result.expect("allowed push succeeds"); + assert_eq!(storage.get_submit_delta_calls().len(), 1); + let approval = pushed + .delta + .metadata + .and_then(|metadata| metadata.modules) + .expect("the approving module configuration is recorded"); + assert_eq!(approval.params_version, 0); + assert_eq!(approval.proposer, "", "no stored proposal matched"); + assert!(approval.failed_open.is_empty()); + let request = module.last_request().expect("module was called"); + assert_eq!(request.submitter, signer); + assert_eq!(approval.submitter, signer); + let accounting_time = request.accounting_time.expect("accounting time is sent"); + assert_eq!( + chrono::DateTime::parse_from_rfc3339(&approval.signed_at) + .expect("signed_at is RFC 3339") + .timestamp_nanos_opt(), + Some(accounting_time.seconds * 1_000_000_000 + i64::from(accounting_time.nanos)), + "signed_at is the accounting time the modules evaluated with" + ); + let Some(guardian_module_sdk::proto::hook_request::Subject::Transaction(subject)) = + &request.subject + else { + panic!("transaction subject expected"); + }; + assert!( + subject.miden().is_some(), + "the projection is tagged as Miden" + ); + assert_eq!( + subject.raw.as_ref().map(|raw| raw.encoding.as_str()), + Some(guardian_module_sdk::RawTransaction::MIDEN_TRANSACTION_SUMMARY) + ); + assert_eq!(request.after.unwrap().signer_commitments, vec![signer]); + assert!(request.before.is_some()); + } } diff --git a/crates/server/src/services/push_delta_proposal.rs b/crates/server/src/services/push_delta_proposal.rs index da9085b27..ead89496d 100644 --- a/crates/server/src/services/push_delta_proposal.rs +++ b/crates/server/src/services/push_delta_proposal.rs @@ -1,16 +1,21 @@ use crate::builder::state::AppState; use crate::delta_object::{CosignerSignature, DeltaObject, DeltaStatus}; use crate::error::{GuardianError, Result}; -use crate::metadata::auth::Credentials; +use crate::metadata::auth::{Credentials, RequestAuthFormat}; +use crate::modules::HookName; +use crate::modules::request::{self, ProposalContext, TransactionInput}; use crate::services::account_status::ensure_account_active_metadata; use crate::services::candidate_chain::{self, CandidateChain}; use crate::services::execution_codec::TransactionRequestEnvelope; use crate::services::proposal_signature::{ ensure_cosigner_approval, proposal_tx_summary, verify_proposal_signature, }; -use crate::services::{normalize_payload, resolve_account_allowing_session}; +use crate::services::{ + normalize_payload, resolve_account_allowing_session, resolve_account_for_read, +}; use crate::storage::{ChainPosition, ProposalAdmission, ProposalWrite}; use guardian_shared::DeltaSignature; +use guardian_shared::session_request::SessionOperation; use serde::Deserialize; use std::sync::Arc; @@ -85,21 +90,65 @@ pub struct PushDeltaProposalResult { pub commitment: String, } +/// The answer of a dry-run check that passed. A denial or an unavailable module is the same +/// error proposal creation returns. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct CheckProposalResult { + /// False when an instance that opts out of dry runs was skipped. + pub complete: bool, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Mode { + Create, + DryRun, +} + +enum Outcome { + Created(Box), + Checked(CheckProposalResult), +} + +pub async fn push_delta_proposal( + state: &AppState, + params: PushDeltaProposalParams, +) -> Result { + match propose(state, params, Mode::Create).await? { + Outcome::Created(result) => Ok(*result), + Outcome::Checked(_) => Err(GuardianError::StorageError( + "proposal creation ended as a check".into(), + )), + } +} + +/// Runs proposal creation up to the `before_proposal_created` modules without storing +/// anything (RFC 0002 section 2.7). Advisory: approval still decides. +pub async fn check_proposal( + state: &AppState, + params: PushDeltaProposalParams, +) -> Result { + match propose(state, params, Mode::DryRun).await? { + Outcome::Checked(result) => Ok(result), + Outcome::Created(_) => Err(GuardianError::StorageError( + "a proposal check stored a proposal".into(), + )), + } +} + #[tracing::instrument( + name = "push_delta_proposal", level = "info", skip(state, params), fields( account_id = %params.account_id, nonce = params.nonce, + ?mode, proposer_id = tracing::field::Empty, commitment = tracing::field::Empty, signer_count = tracing::field::Empty ) )] -pub async fn push_delta_proposal( - state: &AppState, - params: PushDeltaProposalParams, -) -> Result { +async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) -> Result { tracing::debug!("Pushing delta proposal"); if crate::metadata::network::is_evm_account_id(¶ms.account_id) @@ -125,14 +174,38 @@ pub async fn push_delta_proposal( let delta_payload = normalize_payload(delta_payload)?; let base_commitment = proposal_base_commitment(&delta_payload)?; - let resolved = resolve_account_allowing_session( - state, - &account_id, - &credentials, - guardian_shared::session_request::SessionOperation::PushDeltaProposal, - ) - .await?; + let resolved = match mode { + Mode::Create => { + resolve_account_allowing_session( + state, + &account_id, + &credentials, + SessionOperation::PushDeltaProposal, + ) + .await? + } + Mode::DryRun => { + resolve_account_for_read( + state, + &account_id, + &credentials, + SessionOperation::CheckDeltaProposal, + ) + .await? + } + }; ensure_account_active_metadata(&resolved.metadata)?; + let credentials_session = credentials.auth_format() == RequestAuthFormat::Session; + // A dry run is admitted against its rate limit before any reconstruction work, whether + // or not modules are configured. + if mode == Mode::DryRun { + crate::modules::check_limit::admit(&account_id, &resolved.signer_commitment)?; + } + let dry_run = match (mode, state.modules.as_deref()) { + (Mode::DryRun, Some(modules)) => Some(modules.plan_dry_run(&account_id).await?), + (Mode::DryRun, None) => Some((Vec::new(), true)), + (Mode::Create, _) => None, + }; if resolved.metadata.network_config.is_evm() { return Err(GuardianError::UnsupportedForNetwork { network: "evm".to_string(), @@ -372,16 +445,49 @@ pub async fn push_delta_proposal( .cloned() .unwrap_or_default(); - // Validate delta using network client (check validity but don't apply) + let (plans, complete) = match (dry_run, state.modules.as_deref()) { + (Some(planned), _) => planned, + (None, Some(modules)) => ( + modules + .plan(HookName::BeforeProposalCreated, &account_id) + .await? + .into_iter() + .collect(), + true, + ), + (None, None) => (Vec::new(), true), + }; + // With modules to run, one decode verifies the delta against the tail and builds what they + // receive, after the chain fee is loaded; without, the delta is only verified. + if !plans.is_empty() + && let Err(error) = state.network_client.load_fee_faucet().await { + tracing::warn!(%error, "Fee faucet unknown; no output note is treated as the fee note"); + } + let applied = { let client = state.network_client.clone(); let prev_commitment = tail.commitment.clone(); let prev_state_json = tail.state_json.clone(); let tx_summary = Arc::new(tx_summary.clone()); + let evaluate = !plans.is_empty(); crate::network::reconstructor() - .run(move || client.verify_delta(&prev_commitment, &prev_state_json, &tx_summary)) - .await?; - } + .run(move || { + if evaluate { + client + .apply_delta_with_module_inputs( + Some(&prev_commitment), + &prev_state_json, + &tx_summary, + ) + .map(Some) + } else { + client + .verify_delta(&prev_commitment, &prev_state_json, &tx_summary) + .map(|()| None) + } + }) + .await? + }; let commitment = proposal_id.map_err(GuardianError::InvalidDelta)?; tracing::Span::current().record("commitment", tracing::field::display(&commitment)); @@ -421,6 +527,44 @@ pub async fn push_delta_proposal( }); } tracing::Span::current().record("signer_count", cosigner_sigs.len()); + + let mut evaluations = Vec::new(); + if let Some((_, inputs)) = applied { + let proposal = ProposalContext { + proposer: proposer_id.clone(), + metadata: delta_payload + .get("metadata") + .cloned() + .unwrap_or(serde_json::Value::Null), + }; + for plan in plans { + let network_id = plan.network_id(); + plan.run(|| { + request::transaction_request(TransactionInput { + network_id, + account_id: &account_id, + submitter: &proposer_id, + submitter_session: credentials_session, + auth: &resolved.metadata.auth, + network_config: &resolved.metadata.network_config, + inputs: inputs.clone(), + proposal: Some(proposal.clone()), + accounting_time: state.clock.now(), + }) + }) + .await + .map(|evaluation| evaluations.push(evaluation))?; + } + } + if mode == Mode::DryRun { + tracing::info!( + account_id = %account_id, + signer = %proposer_id, + complete, + "Proposal dry-run check passed" + ); + return Ok(Outcome::Checked(CheckProposalResult { complete })); + } // Create delta object with Pending status including any provided signatures let timestamp = state.clock.now_rfc3339(); let delta_proposal = DeltaObject { @@ -461,6 +605,19 @@ pub async fn push_delta_proposal( ) .increment(1); tracing::info!("Delta proposal created"); + if let DeltaStatus::Pending { proposer_id, .. } = &delta_proposal.status { + for evaluation in &evaluations { + evaluation.audit_failed_open( + state.auditor.as_ref(), + HookName::BeforeProposalCreated, + &account_id, + proposer_id, + [("proposal_id".to_string(), commitment.clone().into())] + .into_iter() + .collect(), + ); + } + } delta_proposal } ProposalWrite::AlreadyStored => { @@ -484,7 +641,10 @@ pub async fn push_delta_proposal( } }; - Ok(PushDeltaProposalResult { delta, commitment }) + Ok(Outcome::Created(Box::new(PushDeltaProposalResult { + delta, + commitment, + }))) } /// A proposal is identified by its summary alone, so pushing it again stores nothing: the @@ -2866,4 +3026,286 @@ mod tests { "judged on the replayed tail" ); } + + async fn propose_with_module( + module: Arc, + hook: HookName, + ) -> (Result, MockStorageBackend, String) { + let (state, storage, params, commitment) = module_setup(module, hook, |_| {}); + ( + push_delta_proposal(&state, params).await, + storage, + commitment, + ) + } + + /// State, storage, request and proposer for one module at `hook`, after `configure` adjusts + /// the instance. + fn module_setup( + module: Arc, + hook: HookName, + configure: impl FnOnce(&mut crate::modules::registry::Instance), + ) -> ( + AppState, + MockStorageBackend, + PushDeltaProposalParams, + String, + ) { + use crate::modules::catalog::OnError; + use crate::modules::testing::{instance, pipeline}; + + let (mut state, storage, network, metadata) = create_test_state(); + let account_json: serde_json::Value = serde_json::from_str(fixtures::ACCOUNT_JSON).unwrap(); + let delta_fixture: serde_json::Value = + serde_json::from_str(fixtures::DELTA_1_JSON).unwrap(); + let account_id = delta_fixture["account_id"].as_str().unwrap().to_string(); + let (pubkey, commitment, signature, timestamp) = + crate::testing::helpers::generate_falcon_signature(&account_id); + + let _ = metadata.with_get(Ok(Some(create_account_metadata( + account_id.clone(), + Auth::MidenFalconRpo { + cosigner_commitments: vec![commitment.clone()], + }, + )))); + let storage = storage.with_pull_state(Ok(create_state_object( + account_id.clone(), + "0x780aa2edb983c1baab3c81edcfe400bc54b516d5cb51f2a7cec4690667329392".into(), + account_json, + ))); + let _ = network + .with_verify_delta(Ok(())) + .with_validate_credential(Ok(())) + .with_apply_delta(Ok((serde_json::json!({ "after": true }), "0xafter".into()))) + .with_module_views( + guardian_module_sdk::AccountView::default(), + guardian_module_sdk::MidenTransaction::default(), + ); + let mut configured = instance("caps", &[hook], OnError::Deny, module); + configure(&mut configured); + state.modules = Some(pipeline(vec![configured])); + + let params = PushDeltaProposalParams { + account_id, + nonce: 1, + delta_payload: serde_json::json!({ + "tx_summary": delta_fixture["delta_payload"].clone(), + "signatures": [], + "metadata": { "proposal_type": "p2id", "description": "pay rent" } + }), + credentials: Credentials::signature(pubkey, signature, timestamp), + }; + (state, storage, params, commitment) + } + + #[tokio::test] + async fn a_check_runs_the_creation_modules_and_stores_nothing() { + let module = crate::modules::testing::StubModule::allowing(); + let (state, storage, params, _) = + module_setup(module.clone(), HookName::BeforeProposalCreated, |_| {}); + let result = check_proposal(&state, params).await.unwrap(); + assert!(result.complete); + assert_eq!(module.calls(), 1); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let (state, storage, params, _) = + module_setup(module, HookName::BeforeProposalCreated, |_| {}); + assert!(matches!( + check_proposal(&state, params).await, + Err(GuardianError::ModuleDenied { .. }) + )); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + } + + #[tokio::test] + async fn a_check_runs_approval_only_rules_too_and_marks_every_request_as_a_check() { + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let (state, storage, params, _) = + module_setup(module.clone(), HookName::BeforeTransactionApproved, |_| {}); + assert!(matches!( + check_proposal(&state, params).await, + Err(GuardianError::ModuleDenied { .. }) + )); + let request = module.last_request().expect("the approval rule ran"); + assert!(request.dry_run); + assert_eq!( + request.hook, + guardian_module_sdk::Hook::BeforeTransactionApproved as i32 + ); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + } + + #[tokio::test] + async fn an_instance_on_both_transaction_hooks_runs_once_in_a_check() { + let module = crate::modules::testing::StubModule::allowing(); + let (state, _, params, _) = module_setup( + module.clone(), + HookName::BeforeProposalCreated, + |instance| { + instance.config.hooks = vec![ + HookName::BeforeProposalCreated, + HookName::BeforeTransactionApproved, + ]; + }, + ); + check_proposal(&state, params).await.unwrap(); + assert_eq!(module.calls(), 1); + assert_eq!( + module.last_request().unwrap().hook, + guardian_module_sdk::Hook::BeforeProposalCreated as i32 + ); + } + + #[tokio::test] + async fn an_opted_out_instance_makes_every_check_incomplete_even_where_it_does_not_apply() { + let (state, _, params, _) = module_setup( + crate::modules::testing::StubModule::allowing(), + HookName::BeforeTransactionApproved, + |instance| { + instance.config.scope = crate::modules::catalog::Scope::Assigned; + instance.config.dry_run = false; + }, + ); + let result = check_proposal(&state, params).await.unwrap(); + assert!( + !result.complete, + "the answer must not reveal which accounts carry the hidden instance" + ); + } + + #[tokio::test] + async fn creating_a_proposal_is_not_marked_as_a_check() { + let module = crate::modules::testing::StubModule::allowing(); + let (state, _, params, _) = + module_setup(module.clone(), HookName::BeforeProposalCreated, |_| {}); + let _ = push_delta_proposal(&state, params).await; + assert!( + !module + .last_request() + .expect("the creation rule ran") + .dry_run + ); + } + + #[tokio::test] + async fn a_module_that_opts_out_is_skipped_and_the_check_is_incomplete() { + let module = crate::modules::testing::StubModule::denying("would_deny"); + let (state, _, params, _) = module_setup( + module.clone(), + HookName::BeforeProposalCreated, + |instance| { + instance.config.dry_run = false; + }, + ); + let result = check_proposal(&state, params).await.unwrap(); + assert!(!result.complete, "the skip is reported, not hidden"); + assert_eq!(module.calls(), 0); + + let (state, _, params, _) = + module_setup(module, HookName::BeforeProposalCreated, |instance| { + instance.config.dry_run = false; + }); + assert!( + matches!( + push_delta_proposal(&state, params).await, + Err(GuardianError::ModuleDenied { .. }) + ), + "creation still runs it" + ); + } + + #[tokio::test] + async fn module_denial_at_creation_stores_no_proposal() { + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let (result, storage, _) = + propose_with_module(module, HookName::BeforeProposalCreated).await; + assert!(matches!(result, Err(GuardianError::ModuleDenied { .. }))); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + } + + #[tokio::test] + async fn a_failure_let_through_at_creation_is_audited_and_a_clean_creation_is_not() { + use crate::modules::catalog::OnError; + use crate::modules::testing::{Behaviour, StubModule}; + use crate::testing::helpers::CapturingAuditor; + + let auditor = CapturingAuditor::new(); + let (mut state, storage, params, proposer) = module_setup( + StubModule::new(Behaviour::Fail), + HookName::BeforeProposalCreated, + |instance| instance.config.on_error = OnError::Allow, + ); + state.auditor = Arc::new(auditor.clone()); + let created = push_delta_proposal(&state, params) + .await + .expect("a fail-open module does not stop the proposal"); + assert_eq!(storage.get_submit_delta_proposal_calls().len(), 1); + let events = auditor.snapshot(); + assert_eq!(events.len(), 1, "{events:?}"); + let event = &events[0]; + assert_eq!(event.action_kind, crate::audit::kinds::MODULES_FAILED_OPEN); + assert_eq!(event.operator_identity, "system"); + assert_eq!(event.payload["hook"], "before_proposal_created"); + assert_eq!(event.payload["submitter"], proposer); + assert_eq!(event.payload["proposal_id"], created.commitment); + assert_eq!(event.payload["failed_open"][0]["module_id"], "caps"); + assert_eq!(event.payload["failed_open"][0]["failure"], "error"); + + let clean = CapturingAuditor::new(); + let (mut state, _, params, _) = module_setup( + StubModule::allowing(), + HookName::BeforeProposalCreated, + |_| {}, + ); + state.auditor = Arc::new(clean.clone()); + push_delta_proposal(&state, params).await.unwrap(); + assert!(clean.snapshot().is_empty()); + } + + #[tokio::test] + async fn a_check_audits_nothing() { + use crate::modules::catalog::OnError; + use crate::modules::testing::{Behaviour, StubModule}; + use crate::testing::helpers::CapturingAuditor; + + let auditor = CapturingAuditor::new(); + let (mut state, storage, params, _) = module_setup( + StubModule::new(Behaviour::Fail), + HookName::BeforeProposalCreated, + |instance| instance.config.on_error = OnError::Allow, + ); + state.auditor = Arc::new(auditor.clone()); + check_proposal(&state, params).await.unwrap(); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + assert!(auditor.snapshot().is_empty()); + } + + #[tokio::test] + async fn creation_passes_the_proposer_and_untrusted_metadata() { + let module = crate::modules::testing::StubModule::allowing(); + let (result, storage, proposer) = + propose_with_module(module.clone(), HookName::BeforeProposalCreated).await; + result.expect("proposal is created"); + assert_eq!(storage.get_submit_delta_proposal_calls().len(), 1); + let request = module.last_request().expect("module was called"); + assert_eq!(request.submitter, proposer); + let Some(guardian_module_sdk::proto::hook_request::Subject::Transaction(tx)) = + request.subject + else { + panic!("transaction subject expected"); + }; + assert_eq!(tx.proposer, proposer); + let metadata: serde_json::Value = serde_json::from_slice(&tx.unverified_metadata).unwrap(); + assert_eq!(metadata["description"], "pay rent"); + } + + #[tokio::test] + async fn approval_only_module_is_not_called_at_creation() { + let module = crate::modules::testing::StubModule::denying("no"); + let (result, _, _) = + propose_with_module(module.clone(), HookName::BeforeTransactionApproved).await; + result.expect("creation is not evaluated by an approval-only module"); + assert_eq!(module.calls(), 0); + } } diff --git a/crates/server/src/services/release_on_switch.rs b/crates/server/src/services/release_on_switch.rs index 54c4332f5..02fc4b714 100644 --- a/crates/server/src/services/release_on_switch.rs +++ b/crates/server/src/services/release_on_switch.rs @@ -407,6 +407,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(network), diff --git a/crates/server/src/storage/execution_reservation_tests.rs b/crates/server/src/storage/execution_reservation_tests.rs index 340243b52..0c27a5d7d 100644 --- a/crates/server/src/storage/execution_reservation_tests.rs +++ b/crates/server/src/storage/execution_reservation_tests.rs @@ -516,7 +516,7 @@ async fn a_pre_boundary_failure_releases_with_its_outcome(h: &Harness) { h.storage .resolve_execution( h.metadata.as_ref(), - h.resolution(&proposal, attempt, &owner, code) + h.resolution(&proposal, attempt, &owner, code.clone()) ) .await .unwrap(), @@ -525,7 +525,7 @@ async fn a_pre_boundary_failure_releases_with_its_outcome(h: &Harness) { ); assert_eq!( h.storage - .fail_execution(h.resolution(&proposal, attempt, &owner, code)) + .fail_execution(h.resolution(&proposal, attempt, &owner, code.clone())) .await .unwrap(), ResolveWrite::Resolved diff --git a/crates/server/src/storage/filesystem.rs b/crates/server/src/storage/filesystem.rs index d6ce61f23..4c3afd0b0 100644 --- a/crates/server/src/storage/filesystem.rs +++ b/crates/server/src/storage/filesystem.rs @@ -4464,6 +4464,62 @@ mod tests { tokio::fs::remove_dir_all(temp_dir).await.ok(); } + fn pending_from(proposer: &str, signers: &[&str]) -> DeltaObject { + let mut proposal = create_test_delta("0x7b7b7b7a7b7b7b017b7b7b7b7b7b7b", 1); + proposal.status = DeltaStatus::Pending { + timestamp: "2026-10-13T00:00:00Z".into(), + proposer_id: proposer.into(), + cosigner_sigs: signers + .iter() + .map(|signer| crate::delta_object::CosignerSignature { + signature: guardian_shared::ProposalSignature::from_scheme( + guardian_shared::SignatureScheme::Falcon, + "0xsig".into(), + None, + ), + timestamp: "2026-10-13T00:00:00Z".into(), + signer_id: (*signer).into(), + }) + .collect(), + }; + proposal + } + + fn proposer_of(proposal: &DeltaObject) -> (&str, usize) { + match &proposal.status { + DeltaStatus::Pending { + proposer_id, + cosigner_sigs, + .. + } => (proposer_id, cosigner_sigs.len()), + other => panic!("expected a pending proposal, got {other:?}"), + } + } + + #[tokio::test] + async fn signature_update_after_creation_is_kept_on_reload() { + let temp_dir = env::temp_dir().join(format!("guardian_test_{}", uuid::Uuid::new_v4())); + let account_id = "0x7b7b7b7a7b7b7b017b7b7b7b7b7b7b"; + { + let storage = FilesystemService::new(temp_dir.clone()).await.unwrap(); + storage + .submit_delta_proposal("0xabc", &pending_from("0xfirst", &[])) + .await + .unwrap(); + storage + .update_delta_proposal("0xabc", &pending_from("0xfirst", &["0xcosigner"])) + .await + .unwrap(); + } + let reloaded = FilesystemService::new(temp_dir.clone()).await.unwrap(); + let stored = reloaded + .pull_delta_proposal(account_id, "0xabc") + .await + .unwrap(); + assert_eq!(proposer_of(&stored), ("0xfirst", 1)); + tokio::fs::remove_dir_all(temp_dir).await.ok(); + } + #[tokio::test] async fn test_delete_nonexistent_proposal() { let temp_dir = env::temp_dir().join(format!("guardian_test_{}", uuid::Uuid::new_v4())); diff --git a/crates/server/src/testing/helpers.rs b/crates/server/src/testing/helpers.rs index 2d9283b80..0f0fcb316 100644 --- a/crates/server/src/testing/helpers.rs +++ b/crates/server/src/testing/helpers.rs @@ -384,6 +384,7 @@ pub async fn create_test_app_state() -> AppState { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: storage_backend, metadata: Arc::new(metadata), network_client: Arc::new(mock_client), @@ -1125,6 +1126,7 @@ pub fn create_test_app_state_with_mocks( AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: storage_backend, metadata, network_client, diff --git a/crates/server/src/testing/integration/session_http.rs b/crates/server/src/testing/integration/session_http.rs index b65b1e614..b7d1d92e4 100644 --- a/crates/server/src/testing/integration/session_http.rs +++ b/crates/server/src/testing/integration/session_http.rs @@ -141,6 +141,8 @@ fn http_operation(method: &str, uri: &str) -> Option { ("POST", "/delta/proposal/execution") => SessionOperation::ExecuteDeltaProposal, ("GET", "/delta/proposal/execution") => SessionOperation::GetDeltaProposalExecution, ("GET", "/delta/execution/current") => SessionOperation::GetCurrentExecution, + ("GET", "/policies") => SessionOperation::GetPolicies, + ("POST", "/delta/proposal/check") => SessionOperation::CheckDeltaProposal, _ => return None, }) } @@ -858,6 +860,123 @@ async fn test_removed_signer_loses_access_until_added_back() { assert_eq!(status, StatusCode::OK, "re-added signer: {body}"); } +/// The dry-run check takes proposal creation's body, so a session signature made for one must +/// not pass on the other, and the check is admitted once, as a read. +#[tokio::test] +async fn test_a_proposal_check_is_bound_to_its_own_operation_and_admitted_once() { + let (app, state, signer, account_id_hex) = configured_account().await; + let session_key = falcon_session(&app, &state, &signer).await; + let body = proposal_body(&account_id_hex, &signer); + let timestamp = now_ms(); + let creation = request_word(&account_id_hex, timestamp, &body); + let message = AuthRequestMessage::from_account_id_hex( + &account_id_hex, + timestamp, + AuthRequestPayload::for_operation_json_value(SignedOperation::CheckDeltaProposal, &body) + .unwrap(), + ) + .unwrap() + .to_word(); + let signed_for = |operation, word| { + session_key.sign_bytes_hex( + &SessionRequestEnvelope::from_request_word(SessionTransport::Http, operation, word) + .to_bytes(), + ) + }; + let check = |signature: &str| { + Request::builder() + .uri("/delta/proposal/check") + .method("POST") + .header("content-type", "application/json") + .header("x-pubkey", session_key.public_key_hex()) + .header("x-signature", signature) + .header("x-timestamp", timestamp.to_string()) + .header("x-auth-format", "session-v2") + .body(Body::from(body.to_string())) + .unwrap() + }; + + let response = send( + &app, + check(&signed_for(SessionOperation::PushDeltaProposal, creation)), + ) + .await; + assert_error( + &response, + StatusCode::UNAUTHORIZED, + "authentication_failed", + "a proposal creation signature on the check", + ); + + let signature = signed_for(SessionOperation::CheckDeltaProposal, message); + let (status, checked) = send(&app, check(&signature)).await; + assert_eq!(status, StatusCode::OK, "its own operation: {checked}"); + assert_eq!(checked["allowed"], true, "{checked}"); + + let response = send(&app, check(&signature)).await; + assert_error( + &response, + StatusCode::UNAUTHORIZED, + "authentication_replay", + "the same check sent again", + ); +} + +/// A wallet signature binds the payload but not the route, so the check's payload is tagged: +/// a wallet-signed check is not a valid proposal creation, nor the reverse. +#[tokio::test] +async fn test_a_wallet_signed_check_cannot_create_a_proposal_or_the_reverse() { + let (app, _state, signer, account_id_hex) = configured_account().await; + let body = proposal_body(&account_id_hex, &signer); + let wallet_post = |path: &str, payload: AuthRequestPayload, timestamp: i64| { + let (signature, _) = + signer.sign_with_timestamp_and_request(&account_id_hex, timestamp, &payload); + Request::builder() + .uri(path) + .method("POST") + .header("content-type", "application/json") + .header("x-pubkey", &signer.pubkey_hex) + .header("x-signature", signature) + .header("x-timestamp", timestamp.to_string()) + .body(Body::from(body.to_string())) + .unwrap() + }; + let as_check = + AuthRequestPayload::for_operation_json_value(SignedOperation::CheckDeltaProposal, &body) + .unwrap(); + let as_creation = AuthRequestPayload::from_json_serializable(&body).unwrap(); + let start = now_ms(); + + let response = send( + &app, + wallet_post("/delta/proposal", as_check.clone(), start), + ) + .await; + assert_error( + &response, + StatusCode::UNAUTHORIZED, + "authentication_failed", + "a check signature on proposal creation", + ); + let response = send( + &app, + wallet_post("/delta/proposal/check", as_creation, start + 1), + ) + .await; + assert_error( + &response, + StatusCode::UNAUTHORIZED, + "authentication_failed", + "a creation signature on the check", + ); + let (status, checked) = send( + &app, + wallet_post("/delta/proposal/check", as_check, start + 2), + ) + .await; + assert_eq!(status, StatusCode::OK, "{checked}"); +} + #[tokio::test] async fn test_proposals_are_created_and_signed_through_a_session() { let (app, state, signer, account_id_hex) = configured_account().await; @@ -1256,6 +1375,7 @@ async fn test_every_session_eligible_read_accepts_the_session() { "/delta/execution/current", json!({ "account_id": account_id_hex }), ), + ("/policies", json!({ "account_id": account_id_hex })), ]; let start = now_ms(); for (offset, (path, query)) in (0..).zip(&reads) { diff --git a/crates/server/src/testing/mocks.rs b/crates/server/src/testing/mocks.rs index 9e94291c6..7d48d5941 100644 --- a/crates/server/src/testing/mocks.rs +++ b/crates/server/src/testing/mocks.rs @@ -51,6 +51,10 @@ pub struct MockNetworkClient { /// `(account_id, final_state_commitment, from_block)` per search. pub find_transaction_ending_at_calls: Arc>>, pub account_nonce_responses: Arc>>, + pub module_account_view: Arc>>, + pub module_projection: Arc>>, + /// Account views and projections built for policy modules. + pub module_decodes: Arc, /// Commitments of the decoded accounts passed to /// `verify_and_apply_delta_to_account`, one per call. pub verify_and_apply_delta_to_account_calls: Arc>>, @@ -96,6 +100,17 @@ impl MockNetworkClient { self } + /// Every state decodes to `view` and every delta to `projection`. + pub fn with_module_views( + self, + view: guardian_module_sdk::AccountView, + projection: guardian_module_sdk::MidenTransaction, + ) -> Self { + *self.module_account_view.lock().unwrap() = Some(view); + *self.module_projection.lock().unwrap() = Some(projection); + self + } + pub fn with_validate_first_state(self, response: StdResult<(), String>) -> Self { self.validate_first_state_responses .lock() @@ -232,6 +247,46 @@ impl MockNetworkClient { #[async_trait] impl NetworkClient for MockNetworkClient { + fn module_account_view( + &self, + _state_json: &serde_json::Value, + ) -> StdResult { + self.module_decodes + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); + self.module_account_view + .lock() + .unwrap() + .clone() + .map(|view| crate::network::ModuleAccount { view, nonce: 0 }) + .ok_or_else(|| "no module account view configured".to_string()) + } + + fn module_account_state( + &self, + _state_json: &serde_json::Value, + ) -> StdResult { + Ok(guardian_module_sdk::MidenAccountState::default()) + } + + fn module_transaction( + &self, + tx_summary: &serde_json::Value, + _initial_nonce: u64, + ) -> StdResult { + self.module_decodes + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); + let projection = self + .module_projection + .lock() + .unwrap() + .clone() + .ok_or_else(|| "no module projection configured".to_string())?; + Ok(crate::network::ModuleTransaction { + projection, + raw_tx_summary: serde_json::to_vec(tx_summary).map_err(|e| e.to_string())?, + }) + } + fn get_state_head( &self, account_id: &str, @@ -350,6 +405,29 @@ impl NetworkClient for MockNetworkClient { self.apply_delta(&prev_state_json, delta_payload) } + fn verify_and_apply_delta_to_account_with_module_inputs( + &self, + prev_proof: &str, + prev_account: miden_protocol::account::Account, + delta_payload: &serde_json::Value, + ) -> StdResult<(AppliedState, crate::network::ModuleInputs), String> { + use guardian_shared::ToJson; + let prev_state_json = prev_account.to_json(); + let applied = + self.verify_and_apply_delta_to_account(prev_proof, prev_account, delta_payload)?; + let before = self.module_account_view(&prev_state_json); + let transaction = before + .as_ref() + .map_err(Clone::clone) + .and_then(|before| self.module_transaction(delta_payload, before.nonce)); + let inputs = crate::network::ModuleInputs { + before, + after: self.module_account_view(&applied.state_json), + transaction, + }; + Ok((applied, inputs)) + } + fn merge_deltas( &self, _delta_payloads: Vec, diff --git a/crates/server/tests/from_env.rs b/crates/server/tests/from_env.rs new file mode 100644 index 000000000..297dd3a17 --- /dev/null +++ b/crates/server/tests/from_env.rs @@ -0,0 +1,40 @@ +//! `ServerBuilder::from_env` configures a server from the environment, as the official binary +//! and every custom build start. One test per file: it edits the process environment. A +//! Postgres build needs `DATABASE_URL`, so the test configures the filesystem backend only. + +#![cfg(not(feature = "postgres"))] + +use server::builder::ServerBuilder; + +fn set(name: &str, value: impl AsRef) { + // SAFETY: this test binary runs a single test, so no other thread reads the environment. + unsafe { std::env::set_var(name, value) }; +} + +#[tokio::test] +async fn from_env_configures_a_filesystem_server_and_names_an_invalid_setting() { + let dir = tempfile::tempdir().expect("temporary directory"); + for (name, sub) in [ + ("GUARDIAN_STORAGE_PATH", "storage"), + ("GUARDIAN_METADATA_PATH", "metadata"), + ("GUARDIAN_KEYSTORE_PATH", "keystore"), + ] { + set(name, dir.path().join(sub)); + } + // SAFETY: as in `set`. + unsafe { std::env::remove_var("DATABASE_URL") }; + set("GUARDIAN_ENV", "dev"); + set("GUARDIAN_NETWORK_TYPE", "local"); + + if let Err(error) = ServerBuilder::from_env().await { + panic!("a filesystem server configures from the environment: {error}"); + } + + set("GUARDIAN_NETWORK_TYPE", "nowhere"); + let error = match ServerBuilder::from_env().await { + Ok(_) => panic!("an unknown network type must be refused"), + Err(error) => error.to_string(), + }; + assert!(error.contains("GUARDIAN_NETWORK_TYPE"), "{error}"); + assert!(error.contains("nowhere"), "{error}"); +} diff --git a/crates/shared/src/auth_request_payload.rs b/crates/shared/src/auth_request_payload.rs index d188c779e..4e7a76155 100644 --- a/crates/shared/src/auth_request_payload.rs +++ b/crates/shared/src/auth_request_payload.rs @@ -10,12 +10,15 @@ use serde_json::Value; #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum SignedOperation { ExecuteDeltaProposal, + /// The dry-run proposal check, whose body is proposal creation's. + CheckDeltaProposal, } impl SignedOperation { pub fn tag(&self) -> &'static [u8] { match self { SignedOperation::ExecuteDeltaProposal => b"guardian.ExecuteDeltaProposal\0", + SignedOperation::CheckDeltaProposal => b"guardian.CheckDeltaProposal\0", } } } diff --git a/crates/shared/src/execution.rs b/crates/shared/src/execution.rs index c2e4906b3..72a703285 100644 --- a/crates/shared/src/execution.rs +++ b/crates/shared/src/execution.rs @@ -86,8 +86,24 @@ pub enum ForeignAccountUnavailableReason { Unavailable, } +/// A GUARDIAN policy module's denial of the transaction, with the fields a +/// `GUARDIAN_MODULE_DENIED` refusal carries in its `meta`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ModuleDenial { + /// The denying instance; absent for a generic denial, which reports only `policy_denied`. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub module: Option, + pub reason_code: String, + /// `global` or `account`: the parameter layer that denied; absent for a generic denial. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub layer: Option, + /// The module's text for the requester, when the instance allows it. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub client_message: Option, +} + /// Stable cause of a failed execution, persisted with its structured meta. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[derive(Debug, Clone, PartialEq, Eq)] pub enum ExecutionFailureCode { BindingMismatch, StateMismatch, @@ -119,6 +135,13 @@ pub enum ExecutionFailureCode { Expired, LeaseExpired, Abandoned, + /// A GUARDIAN policy module refused the acknowledgement. The proposal stays stored. + ModuleDenied(ModuleDenial), + /// A fail-closed GUARDIAN policy module could not decide. Requesting again may succeed. + /// `module` is absent for an instance whose denials are generic. + ModuleUnavailable { + module: Option, + }, } #[derive(Serialize, Deserialize)] @@ -131,6 +154,17 @@ struct BoundMeta { bound: ExpirationBound, } +#[derive(Serialize, Deserialize)] +struct ModuleMeta { + module: String, +} + +#[derive(Deserialize)] +struct OptionalModuleMeta { + #[serde(default)] + module: Option, +} + impl ExecutionFailureCode { pub fn as_str(&self) -> &'static str { match self { @@ -167,6 +201,10 @@ impl ExecutionFailureCode { ExecutionFailureCode::Expired => "GUARDIAN_EXECUTION_EXPIRED", ExecutionFailureCode::LeaseExpired => "GUARDIAN_EXECUTION_LEASE_EXPIRED", ExecutionFailureCode::Abandoned => "GUARDIAN_EXECUTION_ABANDONED", + ExecutionFailureCode::ModuleDenied(_) => "GUARDIAN_EXECUTION_MODULE_DENIED", + ExecutionFailureCode::ModuleUnavailable { .. } => { + "GUARDIAN_EXECUTION_MODULE_UNAVAILABLE" + } } } @@ -197,7 +235,9 @@ impl ExecutionFailureCode { | ExecutionFailureCode::AccountInadmissible | ExecutionFailureCode::SubmissionNotProcessed | ExecutionFailureCode::LeaseExpired - | ExecutionFailureCode::Abandoned => false, + | ExecutionFailureCode::Abandoned + | ExecutionFailureCode::ModuleDenied(_) + | ExecutionFailureCode::ModuleUnavailable { .. } => false, } } @@ -213,6 +253,13 @@ impl ExecutionFailureCode { ExecutionFailureCode::ExpirationReached(bound) => { serde_json::to_value(BoundMeta { bound: *bound }) } + ExecutionFailureCode::ModuleDenied(denial) => serde_json::to_value(denial), + ExecutionFailureCode::ModuleUnavailable { + module: Some(module), + } => serde_json::to_value(ModuleMeta { + module: module.clone(), + }), + ExecutionFailureCode::ModuleUnavailable { module: None } => return None, ExecutionFailureCode::BindingMismatch | ExecutionFailureCode::StateMismatch | ExecutionFailureCode::RequestCodec @@ -287,6 +334,19 @@ impl ExecutionFailureCode { "GUARDIAN_EXECUTION_EXPIRED" => ExecutionFailureCode::Expired, "GUARDIAN_EXECUTION_LEASE_EXPIRED" => ExecutionFailureCode::LeaseExpired, "GUARDIAN_EXECUTION_ABANDONED" => ExecutionFailureCode::Abandoned, + "GUARDIAN_EXECUTION_MODULE_DENIED" => { + ExecutionFailureCode::ModuleDenied(required::(code, meta)?) + } + "GUARDIAN_EXECUTION_MODULE_UNAVAILABLE" => ExecutionFailureCode::ModuleUnavailable { + module: match meta { + Some(meta) => { + serde_json::from_value::(meta.clone()) + .map_err(|e| format!("{code} has malformed meta: {e}"))? + .module + } + None => None, + }, + }, other => return Err(format!("unknown execution failure code '{other}'")), }) } @@ -305,6 +365,41 @@ mod tests { assert!(!ExecutionFailureCode::LeaseExpired.ends_proposal()); } + #[test] + fn module_refusals_round_trip_with_their_meta_and_keep_the_proposal() { + let full = ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("account".into()), + client_message: Some("over the daily cap".into()), + }); + let generic = ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: None, + reason_code: "policy_denied".into(), + layer: None, + client_message: None, + }); + let unavailable = ExecutionFailureCode::ModuleUnavailable { + module: Some("caps".into()), + }; + assert_eq!( + generic.meta(), + Some(serde_json::json!({ "reason_code": "policy_denied" })) + ); + let unnamed = ExecutionFailureCode::ModuleUnavailable { module: None }; + assert_eq!(unnamed.meta(), None); + for code in [full, generic, unavailable, unnamed] { + assert!(!code.ends_proposal()); + assert_eq!( + ExecutionFailureCode::from_parts(code.as_str(), code.meta().as_ref()).unwrap(), + code + ); + } + assert!( + ExecutionFailureCode::from_parts("GUARDIAN_EXECUTION_MODULE_DENIED", None).is_err() + ); + } + #[test] fn the_not_processed_code_round_trips_without_meta() { let code = ExecutionFailureCode::SubmissionNotProcessed; diff --git a/crates/shared/src/session_request.rs b/crates/shared/src/session_request.rs index cf1b1d168..b08117dda 100644 --- a/crates/shared/src/session_request.rs +++ b/crates/shared/src/session_request.rs @@ -78,10 +78,12 @@ pub enum SessionOperation { GetDeltaProposalExecution = 12, GetCurrentExecution = 13, GetStateTail = 14, + GetPolicies = 15, + CheckDeltaProposal = 16, } impl SessionOperation { - pub const ALL: [Self; 14] = [ + pub const ALL: [Self; 16] = [ Self::GetState, Self::GetCanonicalNonce, Self::GetDelta, @@ -96,6 +98,8 @@ impl SessionOperation { Self::GetDeltaProposalExecution, Self::GetCurrentExecution, Self::GetStateTail, + Self::GetPolicies, + Self::CheckDeltaProposal, ]; pub fn id(self) -> u16 { @@ -117,7 +121,9 @@ impl SessionOperation { | Self::GetDeltaProposal | Self::GetDeltaProposalExecution | Self::GetCurrentExecution - | Self::GetStateTail => ReplayPolicy::Read, + | Self::GetStateTail + | Self::GetPolicies + | Self::CheckDeltaProposal => ReplayPolicy::Read, Self::PushDelta | Self::PushDeltaProposal | Self::SignDeltaProposal @@ -143,6 +149,8 @@ impl SessionOperation { Self::GetDeltaProposalExecution => "GetDeltaProposalExecution", Self::GetCurrentExecution => "GetCurrentExecution", Self::GetStateTail => "GetStateTail", + Self::GetPolicies => "GetPolicies", + Self::CheckDeltaProposal => "CheckDeltaProposal", } } } @@ -239,7 +247,7 @@ mod tests { assert_eq!(SessionOperation::from_id(operation.id()), Some(operation)); } assert_eq!(SessionOperation::from_id(0), None); - assert_eq!(SessionOperation::from_id(15), None); + assert_eq!(SessionOperation::from_id(17), None); assert_eq!(SessionTransport::from_id(3), None); } diff --git a/crates/shared/tests/fixtures/session_request_vectors.json b/crates/shared/tests/fixtures/session_request_vectors.json index e02339417..dd1dce1c1 100644 --- a/crates/shared/tests/fixtures/session_request_vectors.json +++ b/crates/shared/tests/fixtures/session_request_vectors.json @@ -74,6 +74,16 @@ "id": 14, "name": "GetStateTail", "replay_policy": "read" + }, + { + "id": 15, + "name": "GetPolicies", + "replay_policy": "read" + }, + { + "id": 16, + "name": "CheckDeltaProposal", + "replay_policy": "read" } ], "vectors": [ @@ -441,6 +451,58 @@ "record_key_hex": "0xb84175431206776c651aad305acfc9d7efa7096183ee93777e49c704647fe7f7", "signature_hex": "0xf610d5f62da766c4cd78e38716a55fc08ffa4bd963f01441751668658b95ef61c142e00b3d8cd74bbbe6afde90e1a7903e5b73ad84bba107b22356bd81b50f49" }, + { + "name": "GetPolicies_http", + "account_id_hex": "0x8a8a8a8a8a8a8a010a8a8a8a8a8a8a", + "timestamp_ms": 1767225600000, + "payload_hex": "0x7b226163636f756e745f6964223a223078386138613861386138613861386130313061386138613861386138613861227d", + "transport": 1, + "operation": 15, + "request_word_hex": "0x7f8d45c63289919f1ef9a10c7f5c5b8467e87dbd125ae7e5d01ecccb22b157c8", + "envelope_hex": "0x475541524449414e5f53455353494f4e5f5245515545535400000201000f7f8d45c63289919f1ef9a10c7f5c5b8467e87dbd125ae7e5d01ecccb22b157c8", + "signed_digest_hex": "0xbee8ca4a83d9e1f15ef7717c8d11d180a5254b1e12790caef3c29eedca3f8dda", + "record_key_hex": "0xa5ccc2d713cf513db1dc803ecad635b786b300548f694a0bcee9590942621b8c", + "signature_hex": "0x3ddecb4f8b153f0ec622b72a5f97251333ff6612fbeed6f9f7be551be0fc87a3cf257ea8dee57c3b25a42920dcfffb0aacfb2be2931133195d09b9d692442e30" + }, + { + "name": "GetPolicies_grpc", + "account_id_hex": "0x8a8a8a8a8a8a8a010a8a8a8a8a8a8a", + "timestamp_ms": 1767225600000, + "payload_hex": "0x7b226163636f756e745f6964223a223078386138613861386138613861386130313061386138613861386138613861227d", + "transport": 2, + "operation": 15, + "request_word_hex": "0x7f8d45c63289919f1ef9a10c7f5c5b8467e87dbd125ae7e5d01ecccb22b157c8", + "envelope_hex": "0x475541524449414e5f53455353494f4e5f5245515545535400000202000f7f8d45c63289919f1ef9a10c7f5c5b8467e87dbd125ae7e5d01ecccb22b157c8", + "signed_digest_hex": "0x45c79c3ecdb315a8f4078125ced72b7dc6bf3438aea68d6917be89b500621520", + "record_key_hex": "0x30f09ca0fbf91a0894a1a842024ad1fd4634963b0391f4d9fdf4dd121a1b2096", + "signature_hex": "0x6ac999f43cfd924f68613881ad46f2fcf6f5f28ddc8a29f642f0835bdf3ccabad7b253c955da0a55f76634b98b94564922fa6ef7d3db1be4aff0582345bda131" + }, + { + "name": "CheckDeltaProposal_http", + "account_id_hex": "0x8a8a8a8a8a8a8a010a8a8a8a8a8a8a", + "timestamp_ms": 1767225600000, + "payload_hex": "0x7b226163636f756e745f6964223a223078386138613861386138613861386130313061386138613861386138613861227d", + "transport": 1, + "operation": 16, + "request_word_hex": "0x7f8d45c63289919f1ef9a10c7f5c5b8467e87dbd125ae7e5d01ecccb22b157c8", + "envelope_hex": "0x475541524449414e5f53455353494f4e5f524551554553540000020100107f8d45c63289919f1ef9a10c7f5c5b8467e87dbd125ae7e5d01ecccb22b157c8", + "signed_digest_hex": "0x2f95647e4607e67ad0166068dbfd99509b75ef1f9eec93073cd1f7ea1461b3cd", + "record_key_hex": "0x663af2cebe090d78d7d3cc87d075ac2d6018aafbb6be97ff93ee61d1267c0c77", + "signature_hex": "0x73769000f6d9c646b10368b8995168a0256e43193ba4f19d597133ff492523c047ad2b961b4b74bf392ea8124ca9cdd20bf09b7a4d70dec8afe60093797db9d1" + }, + { + "name": "CheckDeltaProposal_grpc", + "account_id_hex": "0x8a8a8a8a8a8a8a010a8a8a8a8a8a8a", + "timestamp_ms": 1767225600000, + "payload_hex": "0x7b226163636f756e745f6964223a223078386138613861386138613861386130313061386138613861386138613861227d", + "transport": 2, + "operation": 16, + "request_word_hex": "0x7f8d45c63289919f1ef9a10c7f5c5b8467e87dbd125ae7e5d01ecccb22b157c8", + "envelope_hex": "0x475541524449414e5f53455353494f4e5f524551554553540000020200107f8d45c63289919f1ef9a10c7f5c5b8467e87dbd125ae7e5d01ecccb22b157c8", + "signed_digest_hex": "0xcd2c83131907a6497703757d7052e4788bceddc6d16ee2c6828c3d2e732eefa6", + "record_key_hex": "0xb0176455892edeca5b85f0cf779debaf3776e606e12818f6c0e4d839d196b3b2", + "signature_hex": "0x37e9e3b9821e93763e3596ae137e986d0a7a55538043280b2af17297310f2bca39696073b53221b7c2046ce2cfe42022d4a8992283fa6531d2919c7a01f15b61" + }, { "name": "empty_payload", "account_id_hex": "0x8a8a8a8a8a8a8a010a8a8a8a8a8a8a", diff --git a/docs/CONCEPTS.md b/docs/CONCEPTS.md index 34e59d824..15652395e 100644 --- a/docs/CONCEPTS.md +++ b/docs/CONCEPTS.md @@ -178,6 +178,7 @@ flowchart LR | Guardian → Client | The ACK signature on every accepted delta. Clients verify the ACK and the commitment chain before trusting returned state. | | Client → Miden | Miden's own ZK proof verification; Guardian is not in this path. | | Guardian → Miden | Read-only RPC; Miden does not trust Guardian for anything. | +| Guardian → policy modules (optional) | Modules can only refuse: the Guardian signs only when every applicable module allows, and a module never holds a key. Remote modules are reached over TLS with a bearer token per instance. What they receive is a disclosure; see [Policy modules](#policy-modules) below. | | Inside Guardian | Backend access control, IAM scoping, infrastructure hardening — see [`docs/runbooks/secrets.md`](./runbooks/secrets.md) and [`docs/architecture/infra.md`](./architecture/infra.md). | What this means in practice: @@ -191,6 +192,48 @@ What this means in practice: locally; they just cannot sync with their other devices, and other cosigners cannot see their proposals. +### Policy modules + +An operator can start Guardian with a module catalog: policy modules it asks +before it creates a proposal, signs a delta or accepts a new account +([guide](./guides/policy-modules/README.md), +[RFC 0002](./rfcs/0002-guardian-modules.md)). They change the trust model in +two ways. + +- **They add a reason to refuse, never a way to sign.** A module that is + compromised or wrong can stop transactions (or, if its instance is set to + fail open, be skipped), but it cannot make Guardian sign anything the + cosigners did not sign. A rule that must hold even if Guardian itself is + compromised belongs in the account's code on chain, not in a module. +- **They are a disclosure.** Each module, and for a remote module the team or + vendor running it, receives for every account it applies to: + - the full transaction: amounts, assets, recipients, notes, storage and code + changes, and the account's signers and thresholds before and after; + - the verified signer that submitted it, and the proposer; + - the proposer's free-text proposal `description`, which can contain + personal data; + - transactions that never execute: proposals at creation, and every + transaction a cosigner checks with the dry-run endpoint (unless the + instance sets `dry_run = false`); + - at registration, the account's initial vault and storage. + + Secrets never reach a remote module: secret references are refused in its + configuration, and resolved values stay in the Guardian process. + +What this means for operators: + +- Treat a module vendor as a data processor. Ask it to document what it + stores, for how long and where, and put that in your agreement with it. +- Apply a module only where it is needed: a `scope = "assigned"` instance sees + only the accounts it is assigned to, and a module subscribed only to + `before_transaction_approved` does not see proposals at creation. +- Guardian's own logs hold, for every denial, the module's free-text + `message`, the account, the submitter and the reason code; they fall under + the same retention as the rest of the server log. +- What cosigners learn about the modules is chosen per instance + (`disclosure`, `client_reason`); by default they learn only that a policy + refused, with the module's instance id and reason code. + ## Client verification checklist When integrating an SDK against a Guardian, clients **must**: diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index b3600814a..4d96187ea 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -400,6 +400,25 @@ closed** (rejected, never bypassed) and recovers automatically. See the Allowlist payload shapes and enrollment flow: [`docs/DASHBOARD.md`](./DASHBOARD.md). +## Runtime: policy modules + +Prototype (RFC 0002, issue #251); not in a release yet. See the [policy +modules guide](./guides/policy-modules/README.md). + +| Variable | Default | Notes | +|---|---|---| +| `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). A value that is set but empty, or a catalog that declares no module, refuses startup: unset the variable to run without modules. Without it the server logs that no policy module runs, as a warning when its database still holds module state from an earlier catalog; in the prod stage that case refuses startup instead, unless `GUARDIAN_MODULES_DISABLED=true`, so a deploy that lost the variable cannot run every account without its policies. Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; a relative `tls.ca_file` in the catalog resolves against the catalog's directory, and `auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret` and `$secret` params name secrets read through `GUARDIAN_MODULE_SECRET_PROVIDER`. An enabled instance that fails its startup checks stops startup, with one exception: an instance that has started on this Guardian before and whose module does not answer starts unavailable (its breaker open, so its accounts follow `on_error`) and runs its startup checks on each health probe until they pass, so a module's outage does not keep the Guardian from restarting. A module that answers but rejects the token, the params or the protocol still stops startup, and so does an unreachable module of an instance new to this Guardian. An instance stored as disabled that the catalog declares enabled and not `operator_can_disable` is enabled at startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | +| `GUARDIAN_MODULES_DISABLED` | `false` | `true` lets a prod-stage server start without `GUARDIAN_MODULES_CONFIG` although its database holds policy module state, running no module on purpose (for example when retiring modules). Without it that start is refused. `true` or `false`; any other value refuses startup. Ignored when a catalog is set. | +| `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` | `30` | Dry-run proposal checks (`POST /delta/proposal/check`) one signer may make for one account per minute; excess returns `rate_limit_exceeded`. Per replica. A value that is not a positive integer refuses startup. | +| `GUARDIAN_MODULES_STATE` | `/modules` when that variable is set, otherwise the catalog path with its extension replaced by `.tables` (`built-in.toml` keeps its state in `built-in.tables/`) | Filesystem builds only: directory of the module state file (`module_state.json`). Set it, or `GUARDIAN_METADATA_PATH`, when the catalog sits on a read-only mount. Postgres builds keep module state in the database. | +| `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | Time spent in module calls for one hook invocation (request assembly is not charged). Each call gets the smaller of its `timeout_ms` and what is left; once spent, later modules count as timed out and their `on_error` applies. In the prod stage startup refuses a catalog whose `all` and `default` instances, enabled or not, exceed it at any hook, and a budget not below the execution reservation lease; account assignments and layers that would raise an account's cost over it are refused at write time, while writes that keep or lower the cost pass. Client and SDK request timeouts must exceed it, or a slow approval arrives after the client retried. | +| `GUARDIAN_MODULE_REQUEST_MAX_BYTES` | `2097152` (2 MiB) | Largest encoded request sent to a module. A larger one is not sent and the request is refused with `GUARDIAN_MODULE_DENIED` (`reason_code = request_too_large`), whatever the instance's `on_error`. | +| `GUARDIAN_MODULE_BREAKER_FAILURES` | `5` | Consecutive failures (timeouts, transport errors, malformed decisions) that open an instance's circuit breaker on a replica. While open the module is not called and its `on_error` applies at once. A deny is an answer and resets the count, and so is a request the module rejects as one it cannot judge (its `on_error` still applies to that request). A timeout that earlier modules caused by using up the budget does not count, and dry-run checks neither count nor reset. | +| `GUARDIAN_MODULE_PROBE_INTERVAL_MS` | `5000` | Interval of the `Describe` health probe of every enabled instance. A successful probe moves an open breaker to half-open, where one call at a time is sent as the trial and decides, while other requests are treated as while open; the result is `guardian_module_up`. A probe that gets no answer counts as a failed call toward the breaker. A probe that finds the module answering with a protocol version, a required capability or a hook set this Guardian cannot work with opens the breaker at once and keeps it open until a probe passes. | +| `GUARDIAN_MODULE_PARAMS_MAX_BYTES` | `65536` (64 KiB) | Largest params value one write may store (global params, an account layer or an assignment entry), measured as compact JSON with sorted keys. A larger write is refused with `invalid_input` before the module is called, and a larger catalog seed refuses startup, so no params value can push every request for an account over `GUARDIAN_MODULE_REQUEST_MAX_BYTES`. | +| `GUARDIAN_MODULE_SECRET_PROVIDER` | `aws` in the prod stage, `file` otherwise | Where the secrets a module catalog names (`auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret`, `$secret` params) are read from, once at startup. `file`: one file per secret below `GUARDIAN_MODULE_SECRET_DIR`, readable by its owner only (`0600`). `aws`: AWS Secrets Manager secret ids, with `AWS_REGION` set. Not consulted when the catalog names no secret. | +| `GUARDIAN_MODULE_SECRET_DIR` | the catalog's directory | Directory of the `file` secrets provider; a secret name is a relative path below it. | + ## Runtime — EVM (feature-gated) These take effect only when the server is built with `--features evm`. diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md index bcc4c7cc7..c60b42f4c 100644 --- a/docs/DASHBOARD.md +++ b/docs/DASHBOARD.md @@ -344,7 +344,9 @@ load time so a typo surfaces explicitly |---|---| | `dashboard:read` | Read access to all `/dashboard/*` read endpoints. | | `accounts:pause` | Pause/unpause accounts. | -| `policies:write` | Reserved for future policy writes — no endpoint currently requires it. | +| `policies:write` | Policy module writes for one account (account layers, assignments) and enabling or disabling module instances ([Policy modules](#policy-modules)). | +| `policies:write_global` | Policy module global params, which apply to every account. | +| `modules:disable` | Disabling a module instance that the catalog marks `operator_can_disable`, without any other policy write. | | `stats:refresh` | Request an out-of-cycle refresh of the `/dashboard/stats` aggregate (`POST /dashboard/stats/refresh`, issue #371). | Wire strings are **case-sensitive** and **must not contain whitespace** — @@ -352,9 +354,99 @@ the parser rejects both. > **Current scope:** `dashboard:read` gates all read endpoints. > `accounts:pause` gates the pause/unpause endpoints (see [Account -> pausing](#account-pausing) below). `policies:write` is reserved -> vocabulary — accepted by the allowlist parser but no endpoint requires -> it yet. +> pausing](#account-pausing) below). `policies:write`, +> `policies:write_global` and `modules:disable` gate the policy module +> writes (see [Policy modules](#policy-modules) below). + +## Policy modules + +M2a (RFC 0002, issue #251); not in a release yet. The endpoints +manage the module instances the catalog file declares +([`GUARDIAN_MODULES_CONFIG`](./CONFIGURATION.md#runtime-policy-modules)); +they cannot add, remove or reconfigure an instance. Every write takes a +`reason`, is validated by the module before it is stored, and is recorded +in the params history and the audit log. A walkthrough is in the +[policy modules guide](./guides/policy-modules/README.md). + +Which configuration approved a signed delta is on its detail, +`GET /dashboard/accounts/{account_id}/deltas/{nonce}`, in the `modules` field: +`catalog_hash`, `params_version`, `account_params_version`, `signed_at`, +`submitter`, `proposer`, and under `failed_open` each module failure an `on_error = "allow"` instance let +through (`module_id`, `layer`, `failure`). It is absent when no module ran for +the delta, and client routes never return it. The same skips at proposal +creation and account registration, where nothing is signed, are written to the +audit log as `modules.failed_open` events (`operator_identity` `system`, with +the hook, submitter, catalog hash, both params versions and, for a proposal, +its `proposal_id`). Operator writes are audited with the version they +committed as (`params_version` for an instance write, `account_params_version` +for a write to one account), or `null` for an enable or disable that changed +nothing. + +There are two params versions. `params_version` moves with every write to an +instance (its global params or its enabled flag) and is what each replica keys +its instance cache on; `GET /dashboard/modules` reports it. Each account has its +own `account_params_version`, which moves with every write to that account's +layers or assignment, including the default copy at registration; +`GET /dashboard/accounts/{account_id}/modules` reports it. A write to one +account therefore neither waits for writes to other accounts nor makes any +replica reload its instances. The params history gives each entry an `id`, in +write order, and the `version` it committed as; page it with `before=`. +`GET /dashboard/info` reports the +catalog hash this replica loaded as `backend.module_catalog_hash`. + +| Endpoint | Permission | Body | +|---|---|---| +| `GET /dashboard/modules` | `dashboard:read` | | +| `GET /dashboard/modules/{module_id}/params/history?before=&limit=` | `dashboard:read` | | +| `GET /dashboard/accounts/{account_id}/modules` | `dashboard:read` | | +| `PUT /dashboard/modules/{module_id}/params` | `policies:write_global` | `{"params": {...}, "reason": "...", "expected_version": n}` (`expected_version` optional) | +| `PUT /dashboard/accounts/{account_id}/modules/{module_id}/params` | `policies:write` | `{"params": {...}, "reason": "...", "expected_version": n}` (`expected_version` optional) | +| `DELETE /dashboard/accounts/{account_id}/modules/{module_id}/params` | `policies:write` | `{"reason": "...", "expected_version": n}` (`expected_version` optional) | +| `PUT /dashboard/accounts/{account_id}/modules` | `policies:write` | `{"modules": [{"module_id": "...", "params": {...}}], "reason": "...", "expected_version": n}` (`expected_version` optional) | +| `POST /dashboard/modules/{module_id}/enable` | `policies:write` | `{"reason": "..."}` | +| `POST /dashboard/modules/{module_id}/disable` | `policies:write` or `modules:disable` | `{"reason": "..."}` | + +On a `scope = all` instance the per-account params are a layer evaluated +after the global params, and both must allow, so a layer only adds +restrictions. A `scope = default` instance is copied into an account's +assignment when it first registers and is then replaced or removed with the +account's other assignments; a `scope = assigned` one applies only where it +is assigned. Disabling an instance the catalog does not mark +`operator_can_disable` returns `409 GUARDIAN_MODULE_NOT_DISABLEABLE`. + +The four params writes (global params, account layer set or removed, assignment) +accept an optional `expected_version`: the catalog-wide `params_version` from +`GET /dashboard/modules` for a global write (any instance's global write or +enable/disable moves it, so re-read the catalog after a 409), the account's `account_params_version` for the others. Set, a +write made after another change to the same rows is refused with +`409 GUARDIAN_MODULE_PARAMS_STALE` and nothing is written; read the params +again and reapply your change. Unset, the write replaces whatever is there, so +two operators editing from the same read can drop each other's change. + +A refused write returns `400 invalid_input` with the reason in `meta.detail` +(the module and the rule it broke; the `message` stays generic, as for every +error), and a body that names a JSON key twice in one object is refused the +same way rather than keeping the last value. Writes are refused when the +`reason` is longer than +512 characters, when the params exceed +`GUARDIAN_MODULE_PARAMS_MAX_BYTES`, when a layer is written for a module the +account still has in its assignment (left from before a catalog change made it +`scope = all`; remove it from the assignment first), or when they would take the account's modules +over the evaluation budget at a hook where they are not already that far over +(each `all` instance, again for its layer, plus each assigned one). A write that +keeps or lowers the cost always passes, so an account a deploy pushed over the +budget can be brought back under it. Params a module cannot validate because it +does not answer are refused with `503 GUARDIAN_MODULE_UNAVAILABLE`; an assignment +entry sent exactly as stored is not validated again, so an account keeping a down +module can still have its other entries changed. `GET /dashboard/modules` reports each instance's +`circuit` on the answering replica, `params_drift` against the params seeded +from the catalog file, and under `undeclared` the stored instances the catalog +no longer declares. An account's entries naming such an instance are marked +`orphaned` and skipped, and so are entries a `scope` change left behind: a +layer on an instance that is no longer `all`, or an assignment entry on one +that now is. Delete such a layer, or write the account's assignment again +(which drops entries on `all` instances). The history is newest first, at most 100 entries per +page by default (1,000 at most), and `before` pages backwards by entry `id` (not `version`, which is counted per instance or per account). ## Account pausing diff --git a/docs/MIDEN_COMPATIBILITY.md b/docs/MIDEN_COMPATIBILITY.md index 81fdfb5f8..df3069175 100644 --- a/docs/MIDEN_COMPATIBILITY.md +++ b/docs/MIDEN_COMPATIBILITY.md @@ -923,6 +923,43 @@ newest candidate held (issue #517). `GET /delta` for each `queue[].nonce`: it serves the candidate's payload, whose transaction summary lists its input notes. +### Policy modules (0.19.0) + +Policy modules are off unless the operator configures a catalog, so a +deployment without one behaves as before. With one: + +- **New error codes.** `GUARDIAN_MODULE_DENIED` (403, final) and + `GUARDIAN_MODULE_UNAVAILABLE` (503, retryable) on proposal creation, delta + push and registration; `GUARDIAN_EXECUTION_MODULE_DENIED` and + `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` as Guardian execution failure codes. + SDKs from 0.18.x surface the request codes as an untyped server error and + reject the two execution codes as unknown. +- **Breaking for Rust callers.** + - `ExecutionFailureCode` is no longer `Copy`, and has the two new variants + `ModuleDenied(ModuleDenial)` and `ModuleUnavailable { module }`. + - `MultisigError` has the new variants `ModuleDenied` and + `ModuleUnavailable`. A refusal that used to arrive as `GuardianServer` or + `GuardianProposalRefused` now arrives as one of them, so a `match` that + handled those two variants needs the new arms. + - Neither enum is `#[non_exhaustive]`, so an exhaustive `match` over either + stops compiling until the new variants are handled. +- **New calls.** `get_policies` / `getPolicies`, `check_transaction` / + `checkTransaction`, Rust `check_custom_transaction`, session operations 15 (`GetPolicies`) and 16 + (`CheckDeltaProposal`), and the operator client's module routes and the + `policies:write_global` and `modules:disable` permissions. An operator client + from 0.18.x fails to parse a session that holds either permission. +- **Module authors.** `guardian.module.v1` is not frozen until the first + published `guardian-module-sdk` release; see + [RFC 0002](./rfcs/0002-guardian-modules.md), section 7. +- **Custom server builds.** `ServerBuilder::from_env()` configures the server + from the environment as the `server` binary does, and a release attaches a + `custom-guardian-.tar.gz` template that registers extra module kinds + with `with_module_kind`. For crates embedding `guardian-server`, + `ServerBuilder::build` now returns `BuildError` instead of `String`; + `BuildError` is a `std::error::Error`, so map it with `.to_string()` where a + `String` error is still wanted. The + `custom_module_server` example is replaced by `examples/custom-guardian`. + ### Open upstream items The facts below change independently of this repository. This list is the one diff --git a/docs/MULTISIG_SDK.md b/docs/MULTISIG_SDK.md index 167da21bf..73a5b9868 100644 --- a/docs/MULTISIG_SDK.md +++ b/docs/MULTISIG_SDK.md @@ -798,6 +798,51 @@ report a refusal as their usual error: `ClientError` in Rust and a `GuardianHttp `rawCode` is the wire string in TypeScript. See [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md#guardian-execution) for every code. +### Policy Modules + +A Guardian can run policy modules (spending caps, recipient and signer rules, +screening) that refuse a proposal at creation, a transaction at approval, or +an account at registration. Both SDKs expose the same three things. + +**The rules the operator discloses.** `get_policies()` in Rust and +`getPolicies()` in TypeScript list the modules that apply to the account, as +far as the operator chose to disclose them: the module id, its hooks and a +description, and its params only where the catalog allows it. + +**A check before proposing.** `check_transaction(transaction_type)` in Rust and +`checkTransaction({ type, ... })` in TypeScript build the transaction as the +matching create call would and ask the Guardian whether it would be accepted. +Nothing is stored, no proposal slot is taken and no signature is sent. The +result's `complete` is false when a module that opts out of checks was +skipped. The answer is advisory, since approval still decides, and checks are +rate limited per account and signer. Both SDKs check every typed creator and +custom proposals (`check_custom_transaction` in Rust, `{ type: 'custom' }` in +TypeScript). A Guardian switch is checkable only in Rust, but a switch is never +gated by modules anyway. + +A check and a creation build the proposal the same way: each create call first +drafts the proposal locally (summary, metadata and payload, no signature) and +then either sends that draft to the check route or pushes it. Rust adds the +proposer's signature to a push; TypeScript pushes it unsigned and the proposer +signs afterwards, as for any other approval. A check never carries a signature. + +**Typed refusals.** A refusal from a check, at creation, at push or at +registration carries the same information in both SDKs: + +| | Rust | TypeScript | +|---|---|---| +| Denied (final) | `MultisigError::ModuleDenied { module, reason_code, layer, client_message }` | `GuardianHttpError`, `error.moduleRefusal()` with `kind: 'denied'` | +| Could not decide (retryable) | `MultisigError::ModuleUnavailable { module }` | `error.moduleRefusal()` with `kind: 'unavailable'` | + +A denial from an instance the operator keeps generic names no module and +carries only the reason code `policy_denied`. Neither SDK retries a refusal +on its own. A Guardian execution refused by a module ends failed with +`GUARDIAN_EXECUTION_MODULE_DENIED` or `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE`, +and the proposal is kept. In Rust, `propose_with_fallback` falls back to an +offline proposal on a module refusal for transaction types that can execute +without the Guardian, which is how an account leaves a Guardian whose modules +refuse it. + ### Side-channel (offline) workflow For moving a proposal between cosigners as a document instead of through diff --git a/docs/QUALIFICATION.md b/docs/QUALIFICATION.md index ea9af574f..21cf7eab2 100644 --- a/docs/QUALIFICATION.md +++ b/docs/QUALIFICATION.md @@ -85,10 +85,11 @@ gitignored directories, and tears it down afterwards: | A fourth Guardian that offers execution, `server-executing` | a configured prover and a database of its own (`guardian_executing`), so execution requests get past the capability gate in the deterministic profile | | A fifth Guardian that queues chained candidates, `server-queue` | `GUARDIAN_MAX_PENDING_CANDIDATES_PER_ACCOUNT` set to `2` in the deterministic profile and `4` in the live one (`QUAL_QUEUE_DEPTH` overrides it), the main server's acknowledgement identity, and a database of its own, so the candidate queue (issue #17) is qualified as an operator opts into it while the main server keeps the default of one in-flight candidate | | Operator allowlist | generated from the server fixtures via `qualification-driver operator-keys`, so the identities the scenarios sign with cannot drift from the ones the server accepts | +| Policy module catalog | `lib/modules.sh` writes the main server's catalog per run: four in-process instances (`qual-gate` and `qual-switch` of kind `signer-policy`, `qual-cap` of kind `spending-limit`, `qual-recipient` of kind `recipient-policy`) and one remote `grpc` instance, all scoped `assigned` so no other scenario meets them. The remote one points at a module the Rust driver serves on the host (`host.docker.internal`, on `QUAL_MODULE_PORT`) over TLS, with a certificate a per-run CA signs and a bearer token the server reads through the file secrets backend | | Guardian execution | the live profile points the server at the network's public prover (`https://tx-prover..miden.io`, overridable with `QUAL_TX_PROVER_URL`), so it offers execution; the deterministic stack configures none, so execution must be refused | | Postgres password | random per run | | Ports | picked per run, so concurrent runs do not collide | -| Everything written per run | one directory per run under `qualification/stack/runs/`, removed with the stack: the generated environment file, both acknowledgement key directories and the operator allowlist, so a second run cannot overwrite what the first one's server is still mounting | +| Everything written per run | one directory per run under `qualification/stack/runs/`, removed with the stack: the generated environment file, both acknowledgement key directories, the operator allowlist and the module catalog with its certificates and token, so a second run cannot overwrite what the first one's server is still mounting | The deterministic profile is the exception worth knowing about: it registers a **committed fixture account** whose stored state binds one specific guardian @@ -298,6 +299,50 @@ must fit its step budget inside devnet's 150 s historical window, and the wait a it; they still run there. Testnet runs Miden 0.16 until its 0.17 upgrade, so until then a testnet run of this line fails them along with everything else on 0.17. +### Policy modules + +Five scenarios cover policy modules ([RFC 0002](./rfcs/0002-guardian-modules.md)). Every +instance in the stack's catalog is scoped `assigned`, so it applies only to an account a +scenario assigns it to through the operator API, and the operator in the allowlist holds +`policies:write` for that. + +- `det-module-refusal` (deterministic, both SDKs): `qual-gate` is assigned to the fixture + account with a signer allowlist that names none of its signers. The proposal is refused at + the dry-run check and at creation with `GUARDIAN_MODULE_DENIED`, module `qual-gate` and + `signer_not_allowed`, over gRPC (Rust) and HTTP (TypeScript); once the assignment is + cleared the same proposal passes the check. +- `det-module-unavailable` (deterministic, Rust): the driver serves `signer-policy` for + `qual-remote` and enables it. The remote module refuses over TLS with the token from the + secrets backend; with the module stopped the check is refused as + `GUARDIAN_MODULE_UNAVAILABLE` naming `qual-remote` (`on_error = "deny"`), and disabling the + instance lets the account through. The instance starts disabled in the catalog, because an + enabled module that has never started on this Guardian and cannot be reached stops the server + from starting, and the action leaves it disabled on every path for the restart that follows. +- `det-module-break-glass` (deterministic, Rust): disabling `qual-switch` lets a refused + account through at once. The pass after the restart finds it still disabled against a + catalog that says enabled, with the disable in its params history, and enables it again. +- `live-module-cap-1of1-ecdsa` (live, both SDKs, required on testnet): `qual-cap` caps the + account at exactly what `asset-send` sends, and the account's own policy listing shows it. + One unit more is refused at the check and at creation with `amount_cap_exceeded`; the capped + payment passes, is signed by GUARDIAN at execution after the approval hook runs on the real + transaction, and lands. The funding asset is the network's fee asset, so a fee note counted + as a payment would push the capped send over the cap and fail it. Devnet's pairs exclude it + for the window reason above. +- `live-module-recipient-1of1-ecdsa` (live, both SDKs, required on testnet): `qual-recipient` + gives the account a denylist naming the funding faucet, which the scenario never pays, and + the account's own policy listing shows it. A payment to the faucet is refused at the check + and at creation with `recipient_blocked`; a payment to the treasury passes, is signed by + GUARDIAN at execution after the approval hook runs on the real transaction, and lands. The + denylist names someone, so `deny_unknown` is on, and the fee note has no recipient a + denylist can check: a fee note read as a payment would refuse the send. Devnet's pairs + exclude it for the same window reason. + +The deterministic scenarios propose the first threshold-only fixture delta (`queue_1`), not +`delta_1`: the fixture generator adds `delta_1`'s signer without the approver scheme entry a +real add-signer writes, and GUARDIAN refuses (as unavailable) to build a module's account view +from that state. What stays uncovered: a fail-open instance (`on_error = "allow"`) recording +`metadata.modules.failed_open` on a signed delta, the circuit breaker, and mutual TLS. + ## Reading the outcome | Exit code | Meaning | @@ -438,9 +483,9 @@ is still cheaper to make all six at once: | `crates/qualification-driver/src/manifest/mod.rs` | the `Action` variant | | the same file | its `From` arm, the wire name | | `crates/qualification-driver/src/scenario/mod.rs` | the Rust dispatch arm | -| `crates/qualification-driver/src/scenario/{live,account,identity,error_envelope}.rs` | the Rust body, in the file for its family | +| `crates/qualification-driver/src/scenario/{live,account,identity,error_envelope,modules}.rs` | the Rust body, in the file for its family | | `packages/miden-multisig-client/tests/qualification/runner.ts` | the TypeScript dispatch case | -| `packages/miden-multisig-client/tests/qualification/actions/{live,account,identity,errorEnvelope,operator}.ts` | the TypeScript body | +| `packages/miden-multisig-client/tests/qualification/actions/{live,account,identity,errorEnvelope,operator,modules}.ts` | the TypeScript body | An action implemented on one SDK only is legitimate when it records a real capability gap, but it must report a skip naming the gap rather than a pass. Two diff --git a/docs/SERVER_AWS_DEPLOY.md b/docs/SERVER_AWS_DEPLOY.md index 217297a23..3092833cb 100644 --- a/docs/SERVER_AWS_DEPLOY.md +++ b/docs/SERVER_AWS_DEPLOY.md @@ -301,6 +301,51 @@ aws_region = "us-east-1" # cloudflare_api_token = "..." ``` +## Policy modules + +Policy modules ([guide](./guides/policy-modules/README.md)) are off unless the +server is given a catalog. The catalog is a file the server reads once at +startup, and the published image carries none, so on this stack it travels in +the image: + +1. Build an image from the published one that copies your catalog in, push it + to the stack's ECR repository and deploy it as the server image. Use a + release that includes policy modules: no published image does yet, so until + one does, build the base image from the source + (`docker build --build-arg GUARDIAN_SERVER_FEATURES=postgres .`). Copy any + file the catalog names relative to itself, such as a `tls.ca_file`, next to + it: + + ```dockerfile + FROM ghcr.io/openzeppelin/guardian: + COPY modules.toml /etc/guardian/modules.toml + COPY module-ca.pem /etc/guardian/module-ca.pem + ``` + +2. Point the server at it and name the secrets the catalog references: + + ```hcl + guardian_modules_config = "/etc/guardian/modules.toml" + guardian_module_secret_names = ["guardian/modules/screening-token"] + ``` + +`guardian_modules_config` sets `GUARDIAN_MODULES_CONFIG`. +`guardian_module_secret_names` grants the task runtime role +`secretsmanager:GetSecretValue` on exactly those secrets and sets +`GUARDIAN_MODULE_SECRET_PROVIDER=aws`. Create each secret before the deploy +that enables its instance ([`runbooks/secrets.md`](./runbooks/secrets.md#policy-module-secrets)): +an enabled instance whose secret cannot be read stops startup. + +The catalog is deploy configuration. A change to it is a new image and a new +task definition, which is the review bar wanted for adding, removing or +reconfiguring an instance; params, enabled flags and account assignments +change at run time through the [operator API](./DASHBOARD.md#policy-modules) +and live in the database. A remote module must be reachable from the task's +subnets; the stack does not deploy modules. + +A catalog that is set but empty, or declares no module, stops startup. To run +without modules again, clear `guardian_modules_config`. + ## Database TLS verification By default the server `DATABASE_URL` uses `sslmode=require` — the connection is @@ -629,6 +674,8 @@ exposes no knobs for a routable bind address. | `-execution-failures` | More than `alarm_execution_failures_threshold` (default 1) executions in a 5-minute period fail with an operator-side code (`GUARDIAN_EXECUTION_PROVING_FAILED`, `NODE_UNAVAILABLE`, `CHAIN_INCONSISTENT`, `SEALING_FAILED`, `ACKNOWLEDGEMENT_FAILED`): check the prover, the Miden node and the acknowledgement signer. Failures caused by the proposal or its signers are not counted | | `-execution-observation-outage` | Guardian could not observe the chain for a submitted execution for more than `alarm_execution_observation_outage_threshold_seconds` (default 300 s); the account stays reserved meanwhile | | `-execution-reservation-age` | The oldest active execution reservation is older than `alarm_execution_reservation_age_threshold_seconds` (default 1800 s, above 256 blocks plus the lease); the account cannot start another execution until it is released. Raise it with the lease or the expiration horizon | +| `-module-circuit-open` | Only with `guardian_modules_config` set. A policy module's circuit has been open for 10 minutes: its accounts follow `on_error` (fail-closed instances refuse, fail-open ones skip the module). See the [policy modules runbook](./runbooks/policy-modules.md) | +| `-module-fail-open` | Only with `guardian_modules_config` set. More than `alarm_module_fail_open_threshold` (default 0) requests in 5 minutes were approved without a module's judgement because a fail-open instance failed | | `-metrics-missing` | Application metrics stop arriving — the constant `guardian_build_info` heartbeat disappears (metrics endpoint down, sidecar dead, or scrape failing) | | `-metrics-refresh-failures` | Slow-aggregate refresher attempts are failing; delta/proposal/account gauges are stale | | `-metrics-refresh-stale` | The refresh timestamp stopped advancing for ≥ 10 min (hung or dead refresher — catches what the failures counter cannot) | diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 43db981ba..368d45de8 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -132,7 +132,7 @@ Most startup failures are environment misconfiguration. Check in order: 1. **`GUARDIAN_NETWORK_TYPE` unset, non-Unicode, or unrecognized.** The server exits before binding any port with - `Failed to resolve network type: GUARDIAN_NETWORK_TYPE is not set; accepted values: ...` + `Failed to configure server: Failed to resolve network type: GUARDIAN_NETWORK_TYPE is not set; accepted values: ...` (or `contains non-Unicode data` / `has unrecognized value "..."` for malformed values and typos like `tesnet`). There is no fallback network. Replace the variable with `MidenLocal`, `MidenDevnet`, `MidenTestnet`, @@ -862,6 +862,63 @@ once come back synchronously and create nothing. 256-block window built-in proposals script, so it fires only when a reservation outlives the transaction's expiration, which is worth investigating. +### A policy module refuses or blocks requests + +Only on servers started with a module catalog (`GUARDIAN_MODULES_CONFIG`). +Clients see `403 GUARDIAN_MODULE_DENIED` (a module decided to refuse) or +`503 GUARDIAN_MODULE_UNAVAILABLE` (a fail-closed module could not decide) on +proposal creation, delta push, account registration and the dry-run check; a +Guardian execution ends `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED` or +`GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` and keeps its proposal. + +1. **Find the decision.** Every denial is logged at `info` as + `Policy module denied the request` with `request_id`, `module`, + `account_id`, `hook`, `submitter`, `reason_code`, `layer` (`global` or + `account`), the module's `message` (never sent to clients), + `catalog_hash`, `params_version`, `account_params_version` and + `client_reason`. A denial with + `meta.reason_code = "policy_denied"` and no `module` comes from an instance + with `client_reason = "generic"`; only this log line names it. The + `request_id` is also in the module's request, so the module's own logs can + be joined on it. +2. **A failure, not a decision.** `Policy module failed; refusing` (or + `continuing (fail-open)` for `on_error = "allow"`) is logged at `warn` with + `module`, `account_id` and the failure: the module's error, `timed out`, + an unknown or unset effect, or an open circuit. A deny whose reason code + breaks the rule is still a deny: it reaches clients as `policy_denied` and + logs `Policy module denied with a reason code that breaks the reason code + rule`. A request the + Guardian could not build, or one over `GUARDIAN_MODULE_REQUEST_MAX_BYTES`, + is logged as `Policy module request could not be judged; refusing whatever + on_error says`, counted in `guardian_module_request_refused_total{module, + reason}` (`unavailable` or `too_large`), and refused even by a fail-open + instance. A fail-open + failure is also recorded on the signed delta (`modules.failed_open` on + `GET /dashboard/accounts/{account_id}/deltas/{nonce}`) + and counted in `guardian_module_fail_open_total`. +3. **Module health.** `guardian_module_up` is 0 after a failed `Describe` + health probe (`Policy module health probe failed` at `warn`), and + `guardian_module_circuit_open` is 1 while this replica skips the module + after `GUARDIAN_MODULE_BREAKER_FAILURES` consecutive failures (failed + calls and unanswered probes both count); the next successful probe lets a + call through again. `Policy module cannot be used by this Guardian; its + circuit is open until a probe passes` at `warn` means the module answered `Describe` with a protocol version, + capability or hook set the Guardian cannot use, usually after the module + was redeployed: its circuit opens at once and stays open until the module + is fixed or the instance is reconfigured. A module that is up but slow + shows in `guardian_module_evaluate_duration_seconds` and as `timed out` + failures: compare with the instance's `timeout_ms` and + `GUARDIAN_MODULE_EVALUATION_BUDGET_MS`. +4. **Params.** `GET /dashboard/modules` shows each instance's params in force + and `params_drift`, and `GET /dashboard/accounts/{account_id}/modules` the + account's layer or assignment; the history route shows + who changed them and why. A change through the operator API applies on the + next request. + +To let requests through while a module is broken, disable the instance (if its +catalog entry has `operator_can_disable = true`) or switch it to fail open; +see the [policy modules runbook](./runbooks/policy-modules.md). + ### Rate limits triggered Over HTTP: `429` with `code: rate_limit_exceeded` and a `Retry-After` @@ -1014,6 +1071,8 @@ Causes of a `failed` execution, in `error.code`: | `GUARDIAN_EXECUTION_BINDING_MISMATCH`, `GUARDIAN_EXECUTION_STATE_MISMATCH`, `GUARDIAN_EXECUTION_REQUEST_CODEC`, `GUARDIAN_EXECUTION_PROTOCOL_MISMATCH`, `GUARDIAN_EXECUTION_INSUFFICIENT_FEE`, `GUARDIAN_EXECUTION_EXPIRATION_BEYOND_HORIZON`, `GUARDIAN_EXECUTION_ACCOUNT_INADMISSIBLE` | none | Not until the cause is fixed. | | `GUARDIAN_EXECUTION_INSUFFICIENT_SIGNATURES` | none | Yes, once more cosigners have signed; the proposal is untouched. | | `GUARDIAN_EXECUTION_SUBMISSION_NOT_PROCESSED` | none | Yes; the node refused the send before processing it (a rate limit that outlasted the client's retries, an authentication or permission refusal, an unimplemented call, or inputs sealed against an encryption key the validator no longer holds), so the transaction cannot land and the proposal is kept. Check the node endpoint and its limits if it repeats. | +| `GUARDIAN_EXECUTION_MODULE_DENIED` | `reason_code`, plus `module`, `layer` and `client_message` unless the instance reports generic denials (`reason_code: policy_denied` only) | Not while the policy holds; the proposal is untouched. Only on servers built with policy modules. | +| `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` | `module`, unless the instance reports generic denials | Yes, once the fail-closed module answers again; the proposal is untouched. | | `GUARDIAN_EXECUTION_SUBMISSION_REJECTED`, `GUARDIAN_EXECUTION_CANDIDATE_DISCARDED`, `GUARDIAN_EXECUTION_EXPIRED` | none | No; the transaction was sent, and the proposal is gone (`proposal_exists: false`). | `error.message` is a fixed, user-safe sentence for its cause, plus chain facts such as block @@ -1022,6 +1081,20 @@ stored or served; find it in the server log (`WARN`, same `code`) for the accoun A transaction whose execution stopped because the node could not serve a note script it needed fails as `GUARDIAN_EXECUTION_NODE_UNAVAILABLE`, not as a binding mismatch. +### Policy modules + +Only on servers started with a module catalog. See +[the symptom section](#a-policy-module-refuses-or-blocks-requests) and the +[policy modules runbook](./runbooks/policy-modules.md). + +| Code | HTTP | `meta` | First check | +|---|---|---|---| +| `GUARDIAN_MODULE_DENIED` | 403 (gRPC `PermissionDenied`) | `module`, `reason_code`, `layer` (`global` or `account`), and `client_message` when the module set one; only `reason_code: "policy_denied"` for an instance with `client_reason = "generic"` | A policy refused the request: proposal creation, delta push, account registration or the dry-run check. Not retryable while the policy holds. The server log line `Policy module denied the request` has the module's own `message`. | +| `GUARDIAN_MODULE_UNAVAILABLE` | 503 (gRPC `Unavailable`) | `module`, unless the instance has `client_reason = "generic"` (then the `Policy module failed; refusing` log line names it) | A fail-closed module timed out, errored, sent an invalid decision or was skipped by an open circuit, or the Guardian could not build the module's request (an account view or the projection could not be extracted, a proposal or state read failed), whatever the instance's `on_error`. Retryable. A request over the size cap is a `GUARDIAN_MODULE_DENIED` with `reason_code = request_too_large` instead. On the operator API, enabling an instance that fails its startup checks returns it too. | +| `GUARDIAN_MODULE_NOT_FOUND` | 404 | `module` | Operator API: no catalog instance with this id. Instances come only from the catalog file. | +| `GUARDIAN_MODULE_PARAMS_STALE` | 409 (gRPC `Aborted`) | none | Operator API: a params write sent `expected_version`, and the params changed since that version was read (another operator, or a module migrating its params). Nothing was written. Read the params again and reapply the change. | +| `GUARDIAN_MODULE_NOT_DISABLEABLE` | 409 (gRPC `FailedPrecondition`) | `module` | Operator API: the instance's catalog entry has `operator_can_disable = false`. Changing that is a deploy (edit the catalog and restart). | + ### Validation | Code | HTTP | First check | diff --git a/docs/architecture/services.md b/docs/architecture/services.md index 8a303fe30..eabd8d41d 100644 --- a/docs/architecture/services.md +++ b/docs/architecture/services.md @@ -289,6 +289,45 @@ It piggybacks on the same Postgres backend as the rest of the server but authenticates operators through Falcon-signed challenges rather than the per-account credentials used by Guardian's primary API. +### Policy modules — `modules/` + +A hook pipeline the server consults before it approves anything +([RFC 0002](../rfcs/0002-guardian-modules.md), +[guide](../guides/policy-modules/README.md)). It is off unless +`GUARDIAN_MODULES_CONFIG` names a catalog file, and `AppState.modules` is then +the one [`ModulePipeline`](../../crates/server/src/modules/pipeline/mod.rs) every +request path uses. + +| File | Purpose | +|---|---| +| [`catalog.rs`](../../crates/server/src/modules/catalog.rs) | Parses the catalog: instances, kinds, scopes (`all`, `default`, `assigned`), hooks, `on_error`, disclosure. Read once at startup. | +| [`registry.rs`](../../crates/server/src/modules/registry.rs), [`grpc_kind.rs`](../../crates/server/src/modules/grpc_kind.rs) | Turns catalog entries into module instances: in-process kinds registered on the builder, or the remote `grpc` kind. Runs the startup and health checks (`Describe`, params validation). | +| [`secrets.rs`](../../crates/server/src/modules/secrets.rs) | Resolves the tokens, client certificates and `$secret` params a catalog names, from AWS Secrets Manager or owner-only files. | +| [`store.rs`](../../crates/server/src/modules/store.rs), [`postgres_store.rs`](../../crates/server/src/modules/postgres_store.rs) | The mutable state: enabled flags, global params, account layers and assignments, params history, an instance params version moved by instance writes and a version per account moved by that account's writes. Files on a filesystem build, tables on Postgres. | +| [`pipeline/mod.rs`](../../crates/server/src/modules/pipeline/mod.rs) | Plans which instances run for an account at a hook (one store read) and runs them in order under the evaluation budget; applies `on_error`; returns what the evaluation ran with. | +| [`pipeline/startup.rs`](../../crates/server/src/modules/pipeline/startup.rs) | Builds the pipeline once at startup: applies the stored flags and params to the catalog, builds and checks the instances, then seeds new instances, enables those the catalog requires and stores params a module migrated. Nothing is written if an instance fails its checks. | +| [`pipeline/budget.rs`](../../crates/server/src/modules/pipeline/budget.rs), [`pipeline/probe.rs`](../../crates/server/src/modules/pipeline/probe.rs) | The per-account budget check on operator writes and the over-budget recount; the health probe loop and the state gauges. | +| [`breaker.rs`](../../crates/server/src/modules/breaker.rs), [`limits.rs`](../../crates/server/src/modules/limits.rs) | Per-instance circuit breakers fed by calls and by the `Describe` probe; the budget, size caps and probe interval. | +| [`request.rs`](../../crates/server/src/modules/request.rs), [`network/miden/module_views.rs`](../../crates/server/src/network/miden/module_views.rs) | Builds what a module receives: account views before and after, the transaction projection, the registration state. All are decoded inside the reconstruction task, by the decode that verifies and applies the delta (or, at registration, one decode per state); request assembly only copies them. | +| [`admin.rs`](../../crates/server/src/modules/admin.rs), [`api/dashboard_modules.rs`](../../crates/server/src/api/dashboard_modules.rs) | Operator writes and views behind `/dashboard/modules*` and `/dashboard/accounts/{id}/modules*`. | +| [`disclosure.rs`](../../crates/server/src/modules/disclosure.rs), [`check_limit.rs`](../../crates/server/src/modules/check_limit.rs) | What cosigners may see (`GET /policies`) and the rate limit of dry-run checks. | + +Three service handlers call it, each before its write: + +- `ack_delta_internal.rs` runs `before_transaction_approved` inside + `acknowledge_applied`, the only place an acknowledgement is signed, so both + `push_delta` and the Guardian execution worker pass through it. The record + of the evaluation is stored with the delta (`metadata.modules`). +- `push_delta_proposal.rs` runs `before_proposal_created` before a proposal is + stored, and the dry-run check (`POST /delta/proposal/check`) through the + same path without storing. +- `configure_account.rs` runs `before_account_registered` on every + `/configure`, and copies the `default` instances into a new account. + +Module code never holds the acknowledgement key and can only answer allow or +deny; a module that fails follows its instance's `on_error` (deny unless the +catalog says otherwise). + ## Consumers ```mermaid diff --git a/docs/guides/README.md b/docs/guides/README.md index 0b966fdd3..f729d8ccd 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -26,6 +26,7 @@ storage, or network), not after Compose. | [Miden Dashboard UI](./miden-dashboard/README.md) | Self-hosted Compose: Postgres + Guardian server + the Miden Dashboard operator UI | | [Observability](./observability/README.md) | Local Compose: server + Prometheus + pre-provisioned Grafana dashboard | | [Horizontal scaling](./horizontal-scaling/README.md) | Local Compose: two replicas + round-robin proxy + shared Postgres (sessions, lease failover, fail-closed auth) | +| [Policy modules](./policy-modules/README.md) | From source (`251-modules-m2a` branch): the built-in policies, a remote module over gRPC, and a custom module written with `guardian-module-sdk` | ## Adding a guide diff --git a/docs/guides/observability/README.md b/docs/guides/observability/README.md index c01ff693a..2aea56125 100644 --- a/docs/guides/observability/README.md +++ b/docs/guides/observability/README.md @@ -27,7 +27,8 @@ The server instruments, end to end: HTTP and gRPC request paths (rate, latency, in-flight, status/code), Miden RPC (the upstream chain node), storage operations and per-pool (`storage`/`metadata`) DB-pool saturation, canonicalization, the delta & proposal lifecycle, account growth, operator auth, -rate limiting, refresher health, and process metrics. +rate limiting, refresher health, Guardian execution, policy modules, and process +metrics. Two properties worth knowing as an operator: @@ -98,11 +99,15 @@ Panels are grouped by subsystem and map 1:1 onto the metric taxonomy in | Accounts | total + creation rate by network kind | | Auth & rate limiting | operator auth outcomes, sessions, rate-limit rejections, refresh failures | | Process / runtime | CPU, RSS, file descriptors | +| Guardian execution | executions ended by outcome and code, proving p95, reconciliation, oldest reservation | +| Policy modules | evaluations by module and outcome, p99 per module, health (`up`, circuit open, enabled), fail-open skips, catalog drift, accounts over budget, orphaned assignments | An `Instance` variable (top-left) filters to a single replica or aggregates across all of them. Some panels stay empty in this local filesystem stack — -**DB pool** needs a Postgres build, and **Miden RPC / deltas / proposals / -account creation** need a real signed multisig flow. Copy +**DB pool** needs a Postgres build, **Miden RPC / deltas / proposals / +account creation** need a real signed multisig flow, and **Policy modules** +needs a module catalog (`GUARDIAN_MODULES_CONFIG`, see the +[policy modules guide](../policy-modules/README.md)). Copy [`grafana/dashboards/guardian.json`](./grafana/dashboards/guardian.json) into your own Grafana and adapt it. diff --git a/docs/guides/observability/grafana/dashboards/guardian.json b/docs/guides/observability/grafana/dashboards/guardian.json index b663dcbed..c1419ba0d 100644 --- a/docs/guides/observability/grafana/dashboards/guardian.json +++ b/docs/guides/observability/grafana/dashboards/guardian.json @@ -3190,6 +3190,264 @@ } ], "description": "Admitted session reads per second. kind=recorded: admitted once through the read record (served once, duplicates and stale copies refused); kind=window_only: the canonical nonce poll, served every time inside its window and never recorded. A recorded rate approaching about 1,000/s is the signal to revisit the nonce decision (speckit/features/317-secure-scalability/decision-nonce-read-window.md)." + }, + { + "type": "row", + "title": "Policy modules", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 219 + }, + "id": 69, + "panels": [] + }, + { + "type": "timeseries", + "title": "Module evaluations by outcome", + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 220 + }, + "id": 70, + "fieldConfig": { + "defaults": { + "unit": "ops", + "custom": { + "drawStyle": "line", + "fillOpacity": 12, + "showPoints": "never", + "lineWidth": 1, + "lineInterpolation": "smooth" + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "desc" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "sum by (module, outcome) (rate(guardian_module_evaluate_duration_seconds_count{instance=~\"$instance\"}[$__rate_interval]))", + "refId": "A", + "legendFormat": "{{module}} {{outcome}}" + } + ] + }, + { + "type": "timeseries", + "title": "Module evaluation p99", + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 220 + }, + "id": 71, + "fieldConfig": { + "defaults": { + "unit": "s", + "custom": { + "drawStyle": "line", + "fillOpacity": 12, + "showPoints": "never", + "lineWidth": 1, + "lineInterpolation": "smooth" + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "desc" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "histogram_quantile(0.99, sum by (module, le) (rate(guardian_module_evaluate_duration_seconds_bucket{instance=~\"$instance\"}[$__rate_interval])))", + "refId": "A", + "legendFormat": "{{module}}" + } + ] + }, + { + "type": "timeseries", + "title": "Module health: up, circuit open, enabled", + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 228 + }, + "id": 72, + "fieldConfig": { + "defaults": { + "unit": "short", + "custom": { + "drawStyle": "line", + "fillOpacity": 12, + "showPoints": "never", + "lineWidth": 1, + "lineInterpolation": "smooth" + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "desc" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "min by (module) (guardian_module_up{instance=~\"$instance\"})", + "refId": "A", + "legendFormat": "{{module}} up" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "max by (module) (guardian_module_circuit_open{instance=~\"$instance\"})", + "refId": "B", + "legendFormat": "{{module}} circuit open" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "min by (module) (guardian_module_enabled{instance=~\"$instance\"})", + "refId": "C", + "legendFormat": "{{module}} enabled" + } + ] + }, + { + "type": "timeseries", + "title": "Fail-open skips & configuration", + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 228 + }, + "id": 73, + "fieldConfig": { + "defaults": { + "unit": "short", + "custom": { + "drawStyle": "line", + "fillOpacity": 12, + "showPoints": "never", + "lineWidth": 1, + "lineInterpolation": "smooth" + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "desc" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "sum by (module) (rate(guardian_module_fail_open_total{instance=~\"$instance\"}[$__rate_interval]))", + "refId": "A", + "legendFormat": "{{module}} fail-open/s" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "max by (module) (guardian_module_config_drift{instance=~\"$instance\"})", + "refId": "B", + "legendFormat": "{{module}} catalog drift" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "max(guardian_module_over_budget_accounts{instance=~\"$instance\"})", + "refId": "C", + "legendFormat": "accounts over budget" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "max(guardian_module_orphaned_assignments{instance=~\"$instance\"})", + "refId": "D", + "legendFormat": "orphaned assignments" + } + ] } ] } diff --git a/docs/guides/policy-modules/.env.example b/docs/guides/policy-modules/.env.example new file mode 100644 index 000000000..e33801bde --- /dev/null +++ b/docs/guides/policy-modules/.env.example @@ -0,0 +1,12 @@ +# Policy modules guide: a local server on the filesystem backend. +# Copy to .env next to this file, then load it before starting the server: +# set -a && . docs/guides/policy-modules/.env && set +a +# Paths are relative to the repository root, where you start the server. +GUARDIAN_ENV=dev +GUARDIAN_NETWORK_TYPE=MidenDevnet +GUARDIAN_STORAGE_PATH=.guardian/modules-guide/storage +GUARDIAN_METADATA_PATH=.guardian/modules-guide/metadata +GUARDIAN_KEYSTORE_PATH=.guardian/modules-guide/keystore +GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE=.guardian/operators.json +# One of built-in.toml, remote.toml or custom.toml, copied into .guardian/. +GUARDIAN_MODULES_CONFIG=.guardian/built-in.toml diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md new file mode 100644 index 000000000..72ae5daf1 --- /dev/null +++ b/docs/guides/policy-modules/README.md @@ -0,0 +1,250 @@ +# Policy modules + +Run a local Guardian with policy modules: spending caps, recipient and signer +rules, and your own checks, consulted before the Guardian signs. A module only +answers allow or deny. A deny refuses the Guardian's acknowledgement, so the +transaction cannot execute; a module can never produce a signature. + +> **Not released yet.** Modules are implemented on the +> [`251-modules-m2a`](https://github.com/OpenZeppelin/guardian/tree/251-modules-m2a) +> branch and are not in a release. The design is +> [RFC 0002](../../rfcs/0002-guardian-modules.md). No published image includes +> modules yet, so this guide runs the server from source instead of Docker +> Compose. + +This guide assembles the pieces; the reference lives elsewhere: +[`CONFIGURATION.md`](../../CONFIGURATION.md#runtime-policy-modules) for the +variables and [`DASHBOARD.md`](../../DASHBOARD.md#policy-modules) for the +operator endpoints and permissions. + +## Three ways to run a module + +| Page | Module runs | Use it for | +|---|---|---| +| [Built-in](./built-in.md) | Inside the Guardian process (`spending-limit`, `recipient-policy`, `signer-policy`, `code-policy`) | Spending caps and allowed assets, recipient lists, signer lists, code pinning, with no extra service | +| [Remote](./remote.md) | As its own service over gRPC | A module operated, scaled or upgraded apart from the Guardian, or by another team | +| [Custom](./custom.md) | Your code, written with `guardian-module-sdk`, served over gRPC or compiled into your own server build | Rules the built-in policies cannot express | + +For a complete worked example of a custom remote module, see +[KYC and sanctions screening](./compliance.md): signers must be KYC-verified +and payments are screened against a blocklist or an allowlist read from your +own data. + +## How evaluation works + +- **Catalog.** A TOML file (`GUARDIAN_MODULES_CONFIG`) declares every module + instance: its kind, the hooks it runs at, its scope, its timeout and what + happens when it fails. It is read once at startup. Instances cannot be added + or reconfigured at runtime. +- **Hooks.** `before_proposal_created` filters a proposal before it is stored; + `before_transaction_approved` runs before the Guardian signs, for a pushed + delta and for a Guardian execution alike, and is the one that enforces, + because transactions signed offline skip proposals; + `before_account_registered` runs when an account is configured. +- **Scope.** A `scope = "all"` instance applies to every account. A + `scope = "assigned"` instance applies only to accounts an operator assigns it + to. +- **Params.** The catalog's `params` seed an instance's global params on first + start. After that, operators change them through the API, and can add a + per-account layer on an `all` instance. The layer is evaluated as a second + pass and both must allow, so it can only add restrictions. +- **Failure.** If a module times out or errors, `on_error = "deny"` (the + default) refuses with `503 GUARDIAN_MODULE_UNAVAILABLE`; `"allow"` continues + and records the failure on the signed delta. +- **Refusal.** A deny returns `403 GUARDIAN_MODULE_DENIED` with `module`, + `reason_code` and `layer` (`global` or `account`) in `meta`, plus the + module's `client_message` when it sets one. The Rust and TypeScript clients + surface it as a typed refusal (`ClientError::module_refusal`, + `GuardianHttpError.moduleRefusal()`). A Guardian execution refused this way ends `failed` with + `GUARDIAN_EXECUTION_MODULE_DENIED` (same `meta`) or + `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module`, omitted like the + denial's for a generic instance), and its proposal is + kept. + +## What users see + +Each instance decides how much the account's cosigners learn +([RFC 0002 section 2.7](../../rfcs/0002-guardian-modules.md#27-policy-discovery-and-disclosure)): + +| Catalog field | Values | Effect | +|---|---|---| +| `client_reason` | `full` (default), `generic` | `generic` turns a denial into `meta = { reason_code: "policy_denied" }`: no module, layer or message. Use it for screening, where telling a user why could itself be prohibited. The server log still has the full decision. | +| `disclosure` | `none` (default), `summary`, `params` | What a policy summary for cosigners will show. `summary` and `params` need a `description`. | +| `description` | Text, at most 500 characters | Shown to cosigners, for example "At most 5 per transaction". | +| `dry_run` | `true` (default), `false` | Whether a dry-run check may call the instance. | + +Cosigners use two client endpoints: + +- `GET /policies?account_id=…` lists the disclosed policies (Rust + `get_policies`, TypeScript `getPolicies`). +- `POST /delta/proposal/check` runs proposal creation without storing + anything: it answers `{ "allowed": true, "complete": … }` or the error + creation would return. At most `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` (30) + checks per account and signer per minute. + +The multisig SDKs wrap both: Rust `get_policies`, `check_transaction` and +`check_custom_transaction`, TypeScript `getPolicies` and `checkTransaction`, +which build the transaction exactly as proposing it would. + +An instance whose catalog params contain secret references cannot use +`disclosure = "params"`: the server refuses to start, since the reference +would show cosigners the secret's name. + +Such an instance's global params stay in the catalog file: the operator API +refuses to change them, and the database keeps only an empty placeholder. If a +later catalog drops the secret references, the instance becomes +operator-managed: on that start the new catalog params apply and are stored, a +warning is logged, and from then on operators change them through the API like +any other instance's. The other way round, adding secret references to an +instance operators managed, makes the catalog params apply and logs that the +stored operator params no longer do. (An instance first stored before this +release keeps the old behaviour on that first switch: it starts from the empty +placeholder, so set its params through the API right after that deploy.) + +In +[`built-in.toml`](./built-in.toml), `caps` discloses its params and +`blocklist` denies generically. + +## Setup + +Run everything from the repository root, on the `251-modules-m2a` branch. + +### 1. Operator key + +The module endpoints need an operator session. Generate a Falcon key with the +CLI that ships with the server: + +```sh +mkdir -p .guardian +cargo run -p guardian-server --example modules_admin -- keygen .guardian/operator.key +``` + +It prints the key's commitment and an allowlist entry. Copy +[`operators.example.json`](./operators.example.json) to +`.guardian/operators.json` and paste the printed `public_key` into it. The +example grants all four permissions the module endpoints use. `.guardian/` is +gitignored, so keys and tokens stay out of commits. + +### 2. Catalog and environment + +```sh +cp docs/guides/policy-modules/built-in.toml .guardian/ +cp docs/guides/policy-modules/.env.example docs/guides/policy-modules/.env +``` + +Edit `.guardian/built-in.toml` for your network: replace `0xREPLACE_WITH_FAUCET_ID` +with the faucet id of an asset you hold, in `0x` hex form or as its bech32 +address (stored as hex). The server does not start until you do: the built-in +policies refuse a placeholder, since it would never match a transaction. The other pages swap in +`remote.toml` or `custom.toml` by changing `GUARDIAN_MODULES_CONFIG` in the +guide's `.env`. + +### 3. Start the server + +```sh +set -a && . docs/guides/policy-modules/.env && set +a +cargo run -p guardian-server --bin server +``` + +Exported variables take precedence over the repository's own `.env`. The +server uses the filesystem backend unless built with `--features postgres`; +module state then goes to `GUARDIAN_METADATA_PATH/modules/module_state.json`. +Look for this line in the log: + +``` +Policy modules loaded catalog_hash=0x… params_version=… builds=caps=spending-limit , … +``` + +The ports are fixed at 3000 (HTTP) and 50051 (gRPC); stop any other Guardian +first. + +### 4. The operator CLI + +Define a shell function for the CLI, then list the modules: + +```sh +admin() { ./target/debug/examples/modules_admin --key .guardian/operator.key "$@"; } +admin GET /modules +``` + +`admin METHOD PATH [JSON]` logs in with the key and calls `/dashboard/PATH` on +`http://localhost:3000` (`--url` changes it). Each instance in the listing +shows its `enabled` flag, current params, `build`, and whether the stored +values have drifted from the catalog. + +### 5. A client + +Send transactions with the Rust demo, which surfaces module refusals with the +module and reason code: + +```sh +cargo run -p guardian-demo +``` + +At its prompts, pick the network the guide's `.env` names +(`GUARDIAN_NETWORK_TYPE`, devnet by default; the demo's own default is local), +and use an account funded with the asset whose faucet id you put in the +catalog, or the cap has nothing to apply to. + +Any client works; refusals are plain Guardian errors. + +## Catalog fields + +One `[[module]]` table per instance. A field the table does not list, or a +value outside these rules, stops startup with `invalid module catalog`. + +| Field | Required | Values and default | +|---|---|---| +| `id` | yes | 1 to 64 characters of `a-z`, `0-9`, `_` and `-`, unique in the catalog. It names the instance in the operator API, logs, metrics and full denials | +| `kind` | yes | A built-in policy (`spending-limit`, `recipient-policy`, `signer-policy`, `code-policy`), `grpc` for a remote module, or a kind a custom build registers | +| `endpoint` | `grpc` only | `grpc://host:port` (TLS) or `grpc+insecure://127.0.0.1:port` (loopback only) | +| `scope` | yes | `all` (every account; an account layer can only add restrictions), `default` (copied to each account when it registers, then replaceable per account) or `assigned` (only where an operator assigns it) | +| `hooks` | yes | Non-empty list of `before_account_registered`, `before_proposal_created`, `before_transaction_approved`; each must be one the module supports | +| `timeout_ms` | yes | 1 to 1000 | +| `on_error` | no | `deny` (default) or `allow`: what happens when the module fails or does not answer | +| `params` | no | The instance's global params, seeded on first start and changed through the operator API afterwards. Params with `$secret` references stay in this file; they are refused for `grpc` instances and for `scope = "default"` (whose params are copied per account) | +| `enabled` | no | `true` (default). Read only the first time the instance is seen; the runtime flag applies afterwards | +| `operator_can_disable` | no | `false` (default). Whether the operator API may switch the instance off | +| `disclosure` | no | `none` (default), `summary` or `params`: what `get_policies` shows cosigners. `params` is refused when the params reference secrets | +| `description` | unless `disclosure = "none"` | Up to 500 characters, shown with `disclosure = summary` or `params` | +| `client_reason` | no | `full` (default: module, reason code and message) or `generic` (`policy_denied` only) | +| `dry_run` | no | `true` (default). Whether cosigners can check a transaction against the instance without submitting it | +| `auth` | `grpc` only | `{ token_secret = "" }`; required in the prod stage | +| `tls` | `grpc` only | `ca_file` (relative to the catalog), and `client_cert_secret` with `client_key_secret` for mTLS | + +`after_transaction_committed` and `require_fresh_state_ms` belong to stateful +modules, which are not in this release; a catalog naming them does not start. + +## Operator API at a glance + +| Task | Call | +|---|---| +| Change a global rule | `admin PUT /modules/{id}/params '{"params":{...},"reason":"..."}'` | +| Add a stricter rule for one account | `admin PUT /accounts/{account_id}/modules/{id}/params '{"params":{...},"reason":"..."}'` | +| Remove that account rule | `admin DELETE /accounts/{account_id}/modules/{id}/params '{"reason":"..."}'` | +| Assign opt-in modules to an account | `admin PUT /accounts/{account_id}/modules '{"modules":[{"module_id":"...","params":{...}}],"reason":"..."}'` | +| See what applies to an account | `admin GET /accounts/{account_id}/modules` | +| Switch an instance off or on | `admin POST /modules/{id}/disable '{"reason":"..."}'`, then `/enable` | +| See every change | `admin GET /modules/{id}/params/history` | +| See which configuration approved a delta | `admin GET /accounts/{account_id}/deltas/{nonce}`, field `modules` | + +Every write is validated by the module before it is stored; invalid params +return `400` and change nothing. A module that is down cannot validate, so a +change to its params returns `503 GUARDIAN_MODULE_UNAVAILABLE` (not `400`), +while an assignment that keeps its entry unchanged is still accepted: entries +stored as they are sent are not validated again. + +## Troubleshooting + +For outages, a module that refuses too much, and break-glass steps, see the +[policy modules runbook](../../runbooks/policy-modules.md). + +| Symptom | Cause | +|---|---| +| `cannot read module catalog` | `GUARDIAN_MODULES_CONFIG` is relative to the directory you started the server in; start from the repository root. | +| `module caps: invalid params: …` at startup | The catalog's seed params fail the module's validation on a first start: fix the catalog; nothing is stored until every instance passes. On a later start it is the stored params that fail (the catalog's are no longer read): see the [runbook](../../runbooks/policy-modules.md). | +| `GUARDIAN_MODULES_CONFIG is set but empty` or `declares no module` at startup | An empty value or an empty catalog would silently run without any policy. Point the variable at a catalog, or unset it to run without modules. | +| `module caps-remote: …` at startup | An enabled remote module rejected the token or answered incompatibly, or it is new to this Guardian and unreachable. Start the module first, or set `enabled = false` until it runs. A module that has started here before and is merely down does not stop startup: the instance starts unavailable and recovers on a health probe. | +| `relation "module_state_version" does not exist` | A Postgres database that ran an earlier prototype migration. Drop the `module_*` tables and the functions `guardian_module_snapshot` and `guardian_module_seed_assignment`, delete the module rows in `__diesel_schema_migrations` (versions `20261015000001`, `20261109000001`, `20261110000001` and `20261110000002`, whichever exist), then restart so every module migration runs again. | +| `login failed: no session cookie` | The server did not load the key: check `GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE` and the `public_key` in it. | +| The client shows a generic error | The server log names the module, reason code and layer for every refusal. | diff --git a/docs/guides/policy-modules/built-in.md b/docs/guides/policy-modules/built-in.md new file mode 100644 index 000000000..03b8242bb --- /dev/null +++ b/docs/guides/policy-modules/built-in.md @@ -0,0 +1,171 @@ +# Built-in policies + +Four policy kinds run inside the Guardian process: no extra service, no network +hop. Each enforces one concern, so an instance is configured with only the +params of that rule. One kind backs any number of instances, each with its own +params, hooks and scope. Do the [setup](./README.md#setup) first; the catalog +is [`built-in.toml`](./built-in.toml). + +| Kind | Judges | Hooks it supports | +|---|---|---| +| `spending-limit` | Which assets a transaction moves and how much of each it sends | `before_proposal_created`, `before_transaction_approved` | +| `recipient-policy` | Who a transaction pays | `before_proposal_created`, `before_transaction_approved` | +| `signer-policy` | Who may sign for the account | all three, including `before_account_registered` | +| `code-policy` | Which account code the account may run | all three, including `before_account_registered` | + +A catalog that subscribes a kind to a hook it does not support does not start: +a spending or recipient rule has nothing to judge at registration. A kind +refuses params that belong to another, so a signer list put into a spending +instance is caught when the params are written. + +## Ids + +Write a signer or code commitment in `0x` hex form. Write a faucet or a +recipient either in `0x` hex form or as its bech32 account address (as a wallet +shows it, such as `mtst1...`, with or without the routing part after `_`, which +must be valid but is otherwise ignored). Params written through the operator +API, and catalog params on their first start, are stored with the hex id the +Guardian reports, so the stored params, their history and `get_policies` show +hex; an instance whose params stay in the catalog file shows them as written +there, and matches the same accounts. The address's network prefix is not +checked, since an account id is the same on every network. Params with any +other form are refused, since such an id would never match and its rule would +not apply: a placeholder left in an example catalog, a bech32 string that is +not an account address, and an id of the wrong length (a faucet or a recipient +is an account id of 30 hex digits, a signer or code commitment is 64), so an id +cut short when it was pasted, or an account id where a commitment belongs, is +caught when the params are validated. Case does not matter. + +All params are optional; an instance with none allows everything, which is +what an account layer or assignment of `{}` means. A param that only modifies +another is refused without it (`deny_unknown` needs `denylist`, `check` needs +a list), since an account layer is evaluated with its own params and such a +layer alone would do nothing. + +## `spending-limit` + +| Param | Value | Refuses with | Notes | +|---|---|---|---| +| `max_per_transaction` | `{ "": "" }` | `amount_cap_exceeded` | Gross amount per asset across the transaction's payment notes, in base units. The fee note is not a payment, and an asset that is not listed is not capped. A faucet named twice in different case is refused. | +| `allowed_assets` | `["", ...]` | `asset_not_allowed` | Assets sent in payment notes and received from consumed notes. Unset, any asset; empty, none. | + +Limits over a period (per day, per week) need state the Guardian does not keep +yet; they belong to this kind when they arrive. + +## `recipient-policy` + +| Param | Value | Refuses with | Notes | +|---|---|---|---| +| `allowlist` | `["", ...]` | `recipient_not_allowed` | The only accounts a payment note may go to: P2ID and P2IDE targets, and the reclaimer of a P2IDE note whose reclaim is enabled (unless the reclaimer is the paying account itself), since that account can take the note too. A note whose recipient cannot be identified is refused. Excludes `denylist`. | +| `denylist` | `["", ...]` | `recipient_blocked` | Accounts no payment note may go to, as its target or as the reclaimer of a reclaimable P2IDE note. Excludes `allowlist`. | +| `deny_unknown` | `true` / `false`; unset, `true` once `denylist` names anyone | `recipient_blocked` | With `denylist`: also refuses payment notes whose recipient the Guardian cannot identify (a partial note, or one that is not P2ID or P2IDE), since a blocked recipient could otherwise be paid through a note the Guardian cannot read. It is read from the same params as the list, so it cannot be relaxed per account: an account layer only adds restrictions. For accounts that must create custom-script notes, such as swaps, give them their own `assigned` instance with `deny_unknown = false` instead of the shared denylist. | + +The `blocklist` instance in the guide's catalog starts with an empty +`denylist`, which refuses nothing. Once a recipient is listed, globally or in +an account's layer, notes without a checkable recipient are refused for the +accounts that list applies to, unless the same params set `deny_unknown` to +`false`. + +## `signer-policy` + +| Param | Value | Refuses with | Notes | +|---|---|---|---| +| `allowlist` | `["", ...]` | `signer_not_allowed` | The only signers the account may have. Excludes `denylist`. | +| `denylist` | `["", ...]` | `signer_not_allowed` | Signers the account may not have. Excludes `allowlist`. | +| `check` | `"added"` (default) or `"all"` | | `added` checks only signers a registration or transaction adds; `all` checks every signer the account has after it. | + +## `code-policy` + +| Param | Value | Refuses with | Notes | +|---|---|---|---| +| `allowed` | `["", ...]` | `code_not_allowed` | Pins accounts to account code you reviewed. The Guardian does not check an account's code itself, so a module verdict is only as good as the code that requires the Guardian's signature. | +| `check` | `"changed"` (default) or `"all"` | | `changed` checks the code an account registers with and code a transaction replaces it with, so accounts already on other code keep working until they change it; `all` checks the code the account runs at every hook, so an account on unlisted code can only upgrade to listed code. | + +## Refusals + +Each refusal carries a fixed `client_message` naming the rule (for example +"The transaction sends more than this Guardian allows per transaction."), +never a list entry or a limit, so a `client_reason = "full"` instance tells +users what to change without disclosing params. The exact amounts and +entries go to the server log. A request a kind cannot judge (a transaction +without a Miden projection, say) is an error, not an allow, so the instance's +`on_error` applies. + +## The example catalog + +| Instance | Scope | Rule | +|---|---|---| +| `caps` (`spending-limit`) | all | At most 5 of one asset per transaction; can be switched off; discloses its params to cosigners | +| `blocklist` (`recipient-policy`) | all | Recipient denylist, empty until you fill it; denies generically | +| `signers` (`signer-policy`) | all | One signer may never be added; the catalog protects it from being switched off | +| `treasury-allowlist` (`recipient-policy`) | assigned | Opt-in: applies only to accounts you assign it to | + +## Try it + +Use your account id from the demo's "Show account" as `ACCOUNT`, and a second +account as `RECIPIENT`. + +**Cap.** Propose a payment of 10 of the capped asset. It is refused when the +proposal is created: `GUARDIAN_MODULE_DENIED`, module `caps`, reason +`amount_cap_exceeded`, layer `global`. A payment of 3 goes through. + +**Global blocklist.** Block the recipient for every account: + +```sh +admin PUT /modules/blocklist/params '{"params":{"denylist":["RECIPIENT"]},"reason":"test"}' +``` + +A payment to it is refused, but the client only sees +`reason_code: "policy_denied"`: `blocklist` sets `client_reason = "generic"`, +so neither the module nor `recipient_blocked` reaches the user. The server log +has both. + +**A stricter rule for one account.** Add a lower cap for one account only: + +```sh +admin PUT /accounts/ACCOUNT/modules/caps/params \ + '{"params":{"max_per_transaction":{"":"2"}},"reason":"test"}' +admin GET /accounts/ACCOUNT/modules +``` + +The second call shows the global params and the account's layer side by side. +From this account a payment of 3 is now refused with layer `account`; other +accounts still have the cap of 5. Set the account's cap to 100 and a payment of +10 is still refused, by the global layer: an account layer only adds +restrictions. Remove it with: + +```sh +admin DELETE /accounts/ACCOUNT/modules/caps/params '{"reason":"done"}' +``` + +**Opt-in module.** Give one account an allowlist of recipients: + +```sh +admin PUT /accounts/ACCOUNT/modules \ + '{"modules":[{"module_id":"treasury-allowlist","params":{"allowlist":["RECIPIENT"]}}],"reason":"test"}' +``` + +A payment from that account to any other recipient is refused with +`recipient_not_allowed`. The call replaces the account's whole assignment +list; send `"modules":[]` to clear it. + +**Signer rule.** Propose adding the cosigner +`0xdededededededededededededededededededededededededededededededede`. It is +refused with `signer_not_allowed`, at proposal creation and again at approval +if the transaction was signed offline. + +**Switch.** `admin POST /modules/caps/disable '{"reason":"test"}'` stops the +cap for every account until `/enable`. `signers` returns `409 +GUARDIAN_MODULE_NOT_DISABLEABLE`: its catalog entry does not set +`operator_can_disable`. + +**History.** `admin GET /modules/caps/params/history` lists every change with +its version, operator and reason, including the seed and each enable or +disable. + +## What persists + +The catalog's `params` are only a seed. After the first start the stored +params apply, and editing the catalog shows up as drift (`params_drift: true` +in `GET /modules`) without changing behaviour. Params that hold secret +references stay managed in the file and cannot be changed through the API. diff --git a/docs/guides/policy-modules/built-in.toml b/docs/guides/policy-modules/built-in.toml new file mode 100644 index 000000000..30cc233ba --- /dev/null +++ b/docs/guides/policy-modules/built-in.toml @@ -0,0 +1,62 @@ +# Built-in policies run inside the Guardian process: spending-limit, recipient-policy, +# signer-policy and code-policy, one concern each. +# Copy to .guardian/built-in.toml and replace the placeholders. +# `params` seed the global params on first start; change them later through the operator API. + +# Spending cap for every account: at most 5 base units of one asset per transaction. +[[module]] +id = "caps" +kind = "spending-limit" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +operator_can_disable = true +disclosure = "params" +description = "At most 5 base units of one asset per transaction" +params = { max_per_transaction = { "0xREPLACE_WITH_FAUCET_ID" = "5" } } + +# Recipient blocklist for every account; extend it globally or per account at runtime. +# Generic denials: clients learn that a policy refused, not which list or why. +[[module]] +id = "blocklist" +kind = "recipient-policy" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +operator_can_disable = true +client_reason = "generic" +params = { denylist = [] } + +# Signer rule: no account may add this signer. Protected: operators cannot disable it. +[[module]] +id = "signers" +kind = "signer-policy" +scope = "all" +hooks = ["before_account_registered", "before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +params = { check = "added", denylist = ["0xdededededededededededededededededededededededededededededededede"] } + +# Code pinning (uncomment after reviewing the account code you accept): an account must +# register with a listed code commitment, and a transaction that replaces its code must +# replace it with listed code. With check = "all", every gate hook checks the code the +# account runs, so an account on unlisted code can only upgrade. +# [[module]] +# id = "reviewed-code" +# kind = "code-policy" +# scope = "all" +# hooks = ["before_account_registered", "before_proposal_created", "before_transaction_approved"] +# timeout_ms = 50 +# on_error = "deny" +# params = { check = "changed", allowed = ["0xREPLACE_WITH_REVIEWED_CODE_COMMITMENT"] } + +# Opt-in module: applies only to accounts an operator assigns it to, with their own params. +[[module]] +id = "treasury-allowlist" +kind = "recipient-policy" +scope = "assigned" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" diff --git a/docs/guides/policy-modules/compliance.md b/docs/guides/policy-modules/compliance.md new file mode 100644 index 000000000..799db36b7 --- /dev/null +++ b/docs/guides/policy-modules/compliance.md @@ -0,0 +1,302 @@ +# KYC and sanctions screening + +This page builds a compliance policy as your own remote module and runs it with +a Guardian. The module is +[`examples/compliance-module`](../../../examples/compliance-module/README.md), +about 500 lines of Rust on the +[module SDK](../../../crates/guardian-module-sdk/README.md). Copy it as the +starting point for your own. It enforces two rules: + +- **KYC on signers.** Every signer of an account must be KYC-verified. The + module checks this when the account registers (`/configure`, hook + `before_account_registered`), where it sees every signer the account will + have. It checks again on every transaction, against the signers the + account has after the transaction. Without the second check, an account + could add an unverified signer, or keep one whose verification was + withdrawn. +- **Screening recipients.** A payment may not go to a sanctioned account + (blocklist), or may go only to a verified account (allowlist). The module + checks every account a payment note can reach: its P2ID target and, for a + P2IDE note that can be reclaimed, the reclaimer. It refuses a note whose + recipient it cannot read (a partial note, a custom script), since a + sanctioned recipient could hide there. + +The lists come from a JSON file the module reads when it starts. That keeps the +example self-contained, and it is not a recommendation: where the data lives +depends on your compliance program. A production module would typically read +the same lists from its own database, a screening vendor's API, or on-chain +rules such as a sanctions or attestation registry. The rest of the module stays +the same; see [Using your own data](#using-your-own-data). + +Do the [setup](./README.md#setup) first (operator key, `.env`, server). This +page replaces its catalog with [`compliance.toml`](./compliance.toml). + +## Two kinds of configuration + +The module separates *who* from *which rule*: + +| | Where it lives | Who changes it | Example | +|---|---|---|---| +| **Data**: who is verified, who is sanctioned | The module's data file (or your database) | Your compliance process | `kyc_signers`, `sanctioned_accounts`, `verified_accounts` | +| **Params**: which checks an instance applies | The Guardian's catalog, then the [operator API](./README.md#operator-api-at-a-glance) | Guardian operators, recorded in the params history | `{ "signers": "all", "recipients": "blocklist" }` | + +One module process can serve several catalog instances with different +params. [`compliance.toml`](./compliance.toml) uses two: + +- **`compliance`** has `scope = "all"`. It applies to every account: every + signer must be KYC-verified, and no payment may go to a sanctioned account. +- **`treasury-screening`** has `scope = "assigned"`. It applies only to the + accounts an operator assigns it to, and allows payments only to verified + counterparties. It runs in addition to `compliance`, so it can only add + restrictions. An assigned instance runs the params given when the account is + assigned, not its catalog params, which are only checked at startup. So + assign it with `{"signers":"off","recipients":"allowlist"}`: assigned with + `{}`, it runs the module's defaults (a blocklist), which repeats `compliance`. + +### Params + +| Param | Values | Default | +|---|---|---| +| `signers` | `all`: every signer, on every request. `added`: every signer at registration, afterwards only the signers a transaction adds (an account keeps working if a signer later loses verification). An account registered before the module was deployed was never checked at registration, so under `added` its unverified signers are never refused; use `all` at least until every existing account has transacted once. `off`. | `all` | +| `recipients` | `blocklist`: no payment to `sanctioned_accounts`. `allowlist`: payments only to `verified_accounts`. `off`. | `blocklist` | + +Any other field or value is refused when the params are written, so a typo +cannot quietly switch a check off. + +### The data file + +```json +{ + "kyc_signers": ["0x<64 hex digits: a signer's public key commitment>"], + "sanctioned_accounts": ["0x<30 hex digits: a Miden account id>"], + "verified_accounts": ["0x<30 hex digits>"] +} +``` + +[`lists.example.json`](../../../examples/compliance-module/lists.example.json) +is a template. Every id must be `0x` hex at its full length, in any case. The +module refuses to start on anything else, including a bech32 address or an id +cut short, because such an entry would never match and its rule would not +apply. Where to find the values: + +- **Signer commitments.** These are the commitments the Guardian reports for + an account's signers. `admin GET /accounts/{account_id}` lists them as + `authorized_signer_ids`, and the multisig SDKs and the demo show them as + cosigner commitments. Your KYC process records the commitment of each key a + verified person or entity controls. +- **Account ids.** Use the `0x` hex form. `admin GET /accounts/{account_id}` + shows both forms (`account_id` and `account_id_bech32`). Convert an address + a wallet shows as `mtst1...` before you add it. + +## Run it + +1. Create a token for each instance: + + ```sh + mkdir -p .guardian + (umask 077; openssl rand -hex 32 > .guardian/compliance.token) + (umask 077; openssl rand -hex 32 > .guardian/treasury-screening.token) + cp examples/compliance-module/lists.example.json .guardian/compliance-lists.json + ``` + + The Guardian reads the same tokens through its secrets backend. With the + guide's default `file` provider and the catalog in `.guardian/`, the names + in the catalog (`compliance.token`, `treasury-screening.token`) are these + files. + +2. Edit `.guardian/compliance-lists.json`. The example ids are placeholders. + Your demo signers' commitments only exist once the demo has created its + keys (it prints them as cosigner commitments), and the module refuses to + register an account whose signers are not listed. So start the demo first, + copy the commitments into `kyc_signers`, then start or restart the module. + Put a recipient account id you will refuse in `sanctioned_accounts`. + +3. Start the module: + + ```sh + cargo run -p guardian-compliance-module -- \ + --data .guardian/compliance-lists.json --listen 127.0.0.1:7445 \ + --instance compliance .guardian/compliance.token \ + --instance treasury-screening .guardian/treasury-screening.token + ``` + + It prints how many entries each list holds, and refuses to start if the + file has an id that could never match. + +4. Point the Guardian at the catalog and start it. In the guide's `.env`, set: + + ```sh + GUARDIAN_MODULES_CONFIG=.guardian/compliance.toml + ``` + + ```sh + cp docs/guides/policy-modules/compliance.toml .guardian/ + set -a && . docs/guides/policy-modules/.env && set +a + cargo run -p guardian-server --bin server + ``` + + The log line `Policy modules loaded` lists + `compliance=compliance 0.1.0` and `treasury-screening=compliance 0.1.0`. + If the module is not running, startup stops with an error containing + `module compliance: describe`, followed by the transport error. The + instance is new to this Guardian, so a wrong endpoint is reported at once. + Once an instance has started, a later restart with the module down starts + it unavailable instead (its accounts follow `on_error`). + +## Try it + +| Step | Expected | +|---|---| +| Register a 2-of-2 account whose signers are both in `kyc_signers` | Registered | +| Register one with a signer that is not in `kyc_signers` | Refused at `/configure`, nothing stored; the client sees `GUARDIAN_MODULE_DENIED` with `reason_code: policy_denied` (generic) | +| Propose adding a signer that is not in `kyc_signers` | Refused at proposal creation | +| Pay a recipient in `sanctioned_accounts` | Refused at proposal creation, and again at the push if the proposal was made elsewhere and signed offline | +| `admin PUT /accounts/{account_id}/modules '{"modules":[{"module_id":"treasury-screening","params":{"signers":"off","recipients":"allowlist"}}],"reason":"treasury"}'`, then pay an account that is not in `verified_accounts` | Refused; paying a verified account is allowed | +| Read why in the Guardian's log | `Policy module denied the request` with `module`, `reason_code` (`signer_not_verified`, `recipient_sanctioned`, `recipient_not_verified` or `recipient_unknown`) and the module's `message`, which names the signer or recipient | + +Clients see only `policy_denied`, because the catalog sets +`client_reason = "generic"`: they learn that a policy refused, not which rule. +With `client_reason = "full"`, they would see the reason code and the module's +client message, which names the rule but no list entry. + +Neither setting hides *who is on a list*. A cosigner who proposes a payment to +an address of their choosing learns from the answer whether that address is +blocked (or, under the allowlist, verified), and an add-signer proposal tests a +signer against `kyc_signers` the same way. The catalog sets `dry_run = false` +on `compliance`, so cosigners cannot run that test for free with +`checkTransaction` / `check_transaction` ([dry runs](./custom.md#dry-runs)): +each probe is then a signed proposal request, subject to the request rate +limits, and every refusal is logged by the Guardian with the submitter +(`Policy module denied the request`). A refused proposal is not stored, so +watch those log lines rather than the account's history. Treat list membership as +something an account's own cosigners can find out, and do not put on the lists +anything that must stay secret from them. + +## Changing the lists + +This example reads the file once, at startup. To change a list, edit the file +and restart the module process. The Guardian keeps running. While the module +is down, its calls fail, and with `on_error = "deny"` every gated request is +refused until it answers again. That is the right failure mode for +compliance, but it means a restart is a short outage of transactions. To avoid +it, run two module processes behind a load balancer and restart them one at a +time, or have the module reload its lists in place (see below). + +Changing *params* never needs a restart. A params write through the operator +API applies to the next request. + +## What the module refuses, and why + +| Reason code | When | Notes | +|---|---|---| +| `signer_not_verified` | A signer of the account is not in `kyc_signers` | At registration, and on transactions per `signers` | +| `recipient_sanctioned` | A payment's target or reclaimer is in `sanctioned_accounts` | `recipients = "blocklist"` | +| `recipient_not_verified` | A payment's target or reclaimer is not in `verified_accounts` | `recipients = "allowlist"` | +| `recipient_unknown` | A payment note's recipient cannot be read (partial note, unknown script) | Unless `recipients = "off"` | + +A note the account sends back to itself (a P2IDE reclaim by the paying +account) is not a payment to anyone else. The fee note is not a payment. + +A request the module cannot judge is an error, never an allow. Examples are a +registration without the account's signers, or a transaction without its +projection. The instance's `on_error` then decides, and `on_error = "deny"` +refuses the request. + +## Going to production + +- **Transport.** In the prod stage, a remote instance must use TLS + (`endpoint = "grpc://host:7445"`) and a token. Start the module with + `--tls-cert` and `--tls-key` (and `--client-ca` for mutual TLS), as the + [remote module guide](./remote.md#credentials) shows. Store the tokens in + your secrets backend (`GUARDIAN_MODULE_SECRET_PROVIDER=aws` on AWS). +- **Availability.** `on_error = "deny"` means the module's availability is your + transaction availability. Run at least two replicas behind a load balancer, + and alert on `-module-circuit-open` (see + [the runbook](../../runbooks/policy-modules.md)). +- **Break-glass, and who can switch screening off.** `compliance` is not + `operator_can_disable`, so the disable route refuses it. Its params can + still turn it off: an operator with `policies:write_global` can set + `{"signers":"off","recipients":"off"}` and screening stops for every account + on the next request, recorded in the params history with the operator and + reason. Grant `policies:write_global` only to the people who may make that + decision, and alert on changes to this instance's params history. If no + operator should be able to do it, remove `off` from the values your module + accepts. `treasury-screening` can also be disabled outright by an operator + with `modules:disable`. +- **Timeouts.** `timeout_ms` (200 here) bounds each call, including the + connection setup after a reconnect. Both instances together must stay within + `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` (1,000 by default) at each hook. +- **Know what the Guardian cannot screen.** + - *Leaving.* An account's signers can move it to another Guardian with + `SwitchGuardian`, which executes on chain without this Guardian's + approval. The policy binds only while the account stays here. An account + whose signer lost verification can leave rather than fix it. + - *Incoming funds.* The module sees the notes a transaction consumes, but the + projection does not carry who sent them, so it cannot screen inbound + payments. Screen deposits elsewhere if your program requires it. + - *Custom-script notes.* `recipient_unknown` refuses every payment note whose + recipient the Guardian cannot read, swaps included, for every account under + `compliance`. An account layer can only add restrictions, so no account + can be exempted there. If some accounts must make swaps, run them under an + assigned instance with recipient checks that fit them, and set + `recipients = "off"` on the shared one. +- **Records.** The Guardian records which configuration approved each delta + (`admin GET /accounts/{account_id}/deltas/{nonce}`, field `modules`). It + also keeps every params change in the params history, with operator and + reason. Keep your list changes under the same kind of control in your own + system. + +## Using your own data + +All data access goes through `Lists` in +[`src/lib.rs`](../../../examples/compliance-module/src/lib.rs): three sets, +filled once by `Lists::from_file`. Replace that function with whatever fits +your requirements: + +- **Your own database.** The KYC records your onboarding process already keeps, + and the sanctions list you maintain or import. +- **A screening vendor.** A sanctions or risk-scoring service, queried for the + accounts and signers you care about, or a list it publishes for download. +- **On-chain rules.** A registry contract or account whose storage holds the + list (for example an allowlist an issuer maintains, or attestations from a + KYC provider), read through a node's RPC. Pin the network and the registry + address in your module's configuration, not in the request: the request's + account is the one being judged, never a source of rules about itself. +- **A combination.** For example, KYC from your database and sanctions from a + vendor. Each list can come from a different place. + +Whatever the source: + +- **Load into memory, refresh in the background.** `evaluate` must answer + within `timeout_ms` (tens of milliseconds in practice). Do not query a vendor + API or a node for each request. Keep the lists in memory (for example behind + an `ArcSwap` or `RwLock`), and refresh them on a timer, on a change + notification from your database, or on new blocks for an on-chain registry. +- **Fail closed.** If the lists cannot be loaded at startup, exit, as this + example does. If a refresh fails, keep serving the last good lists and alert; + if they become too old for your policy, return + `ModuleError::Unavailable` from `evaluate`. The instance's + `on_error = "deny"` then refuses requests rather than letting them through + unscreened. +- **Personal data stays with you.** The Guardian sends account ids, signer + commitments and transaction contents, never names or documents. Map + commitments to people in your own systems, and keep the module's logs to ids + and reason codes. + +Everything else stays the same: the params, the hooks, the reason codes and +the conformance tests. + +## Testing your changes + +[`tests/conformance.rs`](../../../examples/compliance-module/tests/conformance.rs) +runs every rule through the SDK's conformance suite over a real gRPC +connection. The suite checks that the module refuses what it should, allows +what it should, returns an error for what it cannot judge, and validates its +params: + +```sh +cargo test -p guardian-compliance-module +``` + +Add a case for every rule you add. For the protocol and the full request +fields, see [custom modules](./custom.md). diff --git a/docs/guides/policy-modules/compliance.toml b/docs/guides/policy-modules/compliance.toml new file mode 100644 index 000000000..e2eeb37f3 --- /dev/null +++ b/docs/guides/policy-modules/compliance.toml @@ -0,0 +1,40 @@ +# KYC and sanctions screening with the example compliance module +# (examples/compliance-module), run as a remote module next to the Guardian. +# Walkthrough: docs/guides/policy-modules/compliance.md. +# Copy to .guardian/compliance.toml. Both instances are served by one module process started +# with `--instance compliance ... --instance treasury-screening ...`. + +# Every account: every signer KYC-verified, no payment to a sanctioned account. +# Clients learn only that a policy refused (client_reason = "generic"), not which rule, and +# cannot run it as a free dry-run check (dry_run = false), which would let a cosigner test +# addresses against the lists at no cost. It is not operator-disableable, but an operator with +# policies:write_global can still set its params to "off"; see the guide. +[[module]] +id = "compliance" +kind = "grpc" +endpoint = "grpc+insecure://127.0.0.1:7445" +scope = "all" +hooks = ["before_account_registered", "before_proposal_created", "before_transaction_approved"] +timeout_ms = 200 +on_error = "deny" +client_reason = "generic" +dry_run = false +auth = { token_secret = "compliance.token" } +params = { signers = "all", recipients = "blocklist" } + +# Opt-in, for accounts an operator assigns it to (treasuries): payments only to verified +# counterparties. It runs in addition to `compliance`, so it can only tighten. For an assigned +# instance the params below are only checked at startup: each account runs the params given +# when it is assigned, so assign it with { "signers": "off", "recipients": "allowlist" }. +[[module]] +id = "treasury-screening" +kind = "grpc" +endpoint = "grpc+insecure://127.0.0.1:7445" +scope = "assigned" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 200 +on_error = "deny" +client_reason = "generic" +operator_can_disable = true +auth = { token_secret = "treasury-screening.token" } +params = { signers = "off", recipients = "allowlist" } diff --git a/docs/guides/policy-modules/custom-in-process.toml b/docs/guides/policy-modules/custom-in-process.toml new file mode 100644 index 000000000..4ece3ecee --- /dev/null +++ b/docs/guides/policy-modules/custom-in-process.toml @@ -0,0 +1,14 @@ +# Custom module compiled into the server: `note-policy` runs in the Guardian process. +# Start the server with the custom-guardian example (see custom.md), not the +# stock binary, which does not know the `note-policy` kind and would refuse to start. +# Copy to .guardian/custom-in-process.toml. + +[[module]] +id = "note-policy" +kind = "note-policy" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +operator_can_disable = true +params = { max_payment_notes = 1, deny_private_notes = true } diff --git a/docs/guides/policy-modules/custom.md b/docs/guides/policy-modules/custom.md new file mode 100644 index 000000000..7687f8bcd --- /dev/null +++ b/docs/guides/policy-modules/custom.md @@ -0,0 +1,366 @@ +# Custom modules + +Write your own module against `guardian-module-sdk`, then either serve it over +gRPC or compile it into your own server build. The worked example, +[`note_policy/mod.rs`](../../../crates/guardian-module-sdk/examples/note_policy/mod.rs), +is a module the built-in policies cannot express: it limits how many payment notes a +transaction creates and can refuse private notes, whose recipients the +Guardian cannot see. The same code runs both ways. Do the +[setup](./README.md#setup) first. + +| | Over gRPC | In process | +|---|---|---| +| Runs | As its own service ([`note-policy-serve.rs`](../../../crates/guardian-module-sdk/examples/note-policy-serve.rs)) | Inside your server build ([`examples/custom-guardian`](../../../examples/custom-guardian/README.md)) | +| Catalog | [`custom.toml`](./custom.toml): `kind = "grpc"` and an `endpoint` | [`custom-in-process.toml`](./custom-in-process.toml): `kind = "note-policy"` | +| Cost per call | A network round trip | A function call on its own task | +| Isolation | Separate process; can only refuse | Shares the process that holds the signing keys | +| Upgrades | Deploy the module alone | Rebuild the server for every Guardian release | +| Use it for | Third-party code, modules other teams run | Code you review and ship as part of your Guardian build | + +## The `Module` trait + +A stateless module implements three methods: + +| Method | Returns | Notes | +|---|---|---| +| `describe(guardian)` | `ModuleInfo`: name, version, `PROTOCOL_VERSION`, supported hooks, required capabilities | `guardian` carries the Guardian's protocol range and capabilities. The Guardian refuses an instance subscribed to a hook the module does not list, a protocol version outside its range, or a capability it lacks. | +| `validate_params` | `ParamsVerdict::ok()`, `ParamsVerdict::invalid(message)` or `ParamsVerdict::normalized(params)` | Called at startup and on every params write. Reject unknown fields (`#[serde(deny_unknown_fields)]`) so a typo fails here, not silently at evaluation. Return `normalized` to have the Guardian store the params in your current shape. | +| `evaluate` | `Decision::allow()` or `Decision::deny(reason_code, message)` | Must be free of side effects: the same transaction is evaluated at proposal creation and again at approval, and clients retry. | + +Add `guardian-module-sdk` with the `conformance` feature as a dev-dependency to +test it (see [Test it](#test-it)). The crate re-exports `async_trait`, so +`#[guardian_module_sdk::async_trait]` goes on the `impl`. + +## The protocol + +Modules speak `guardian.module.v1`, defined in +[`guardian_module_v1.proto`](../../../crates/guardian-module-sdk/proto/guardian_module_v1.proto). +Protocol version 1 freezes with the first published `guardian-module-sdk` +release; from then on Guardian releases add fields, hooks and named +capabilities, never a change that breaks a version 1 module. A module in +another language implements the `GuardianModule` service from that file with +any gRPC stack; the Rust trait above is a thin layer over it. + +| RPC | When the Guardian calls it | +|---|---| +| `Describe` | At startup, before enabling an instance, and every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` (5 s) as a health probe | +| `ValidateParams` | At startup for the stored global params, and on every params write through the operator API | +| `Evaluate` | Once per gate hook invocation the instance applies to, and again for an account's layer | + +Every call carries `authorization: Bearer ` in its gRPC metadata, with +the token of the instance it is for, and `instance_id` in the message +(`Describe` names no instance). Any gRPC error status is a module failure, as +is a call that outlives the instance's `timeout_ms`, and the instance's +`on_error` decides; repeated failures open a circuit breaker that skips the +module until a health probe succeeds. Requests can be up to 2 MiB encoded +(`GUARDIAN_MODULE_REQUEST_MAX_BYTES`), so keep your server's receive limit at +least that high (tonic's default is 4 MiB). + +## Decisions + +| Field | Rule | +|---|---| +| `effect` | `ALLOW` or `DENY`, set by `Decision::allow()` and `Decision::deny(..)`. A value the Guardian does not know is a module failure, never an allow. A module that leaves it unspecified has failed: its instance's `on_error` applies | +| `reason_code` | Required on a deny: 1 to 64 characters of `a-z`, `0-9` and `_`. A deny with any other code is still a deny, but clients get the generic `policy_denied` and the Guardian logs a warning. Stable codes let operators and clients act on them | +| `message` | For the operator: logged with the decision, never sent to clients | +| `client_message` | Optional, for the person who sent the request, via `.with_client_message(..)`. Plain text: the Guardian drops control characters, collapses whitespace and keeps at most 256 characters. Shown only for instances with `client_reason = "full"` (the default); with `"generic"` the client sees `reason_code = "policy_denied"` and nothing else | + +Return `ModuleError` for a request you cannot judge (a missing projection, +params you cannot read). It is a module failure and `on_error` decides, so a +module never allows by accident. + +## Changing your module across releases + +- **Params.** When you rename or restructure a param, keep accepting the + previous shape for at least one release (serde aliases and defaults) and + return `ParamsVerdict::normalized` with the new shape. At startup the + Guardian stores the migrated global params, with a history entry by + `module: `; account layers move to the new shape when they + are next written. Never reuse a param name with a different meaning. +- **Protocol.** Within a protocol version the Guardian only adds fields, + hooks and capabilities, so a module keeps working across Guardian releases. + When a new protocol version ships, the Guardian keeps accepting the previous + one for one release. +- **Rust API.** Build protocol types with `..Default::default()` or the SDK + helpers, and SDK-owned types with their constructors + (`ModuleInstanceConfig::new(..)`), so new fields do not break your build. + +The rules are in [RFC 0002 section 3.5](../../rfcs/0002-guardian-modules.md#35-protocol-evolution-and-compatibility). + +## Hooks and requests + +| Hook | Called | `subject` | +|---|---|---| +| `before_proposal_created` | Before a multisig proposal is stored, and in dry runs | `transaction` | +| `before_transaction_approved` | Before the Guardian signs a pushed delta or a Guardian execution: the one that enforces, since transactions signed offline skip proposals | `transaction` | +| `before_account_registered` | On every `/configure` of an account: its first configuration on this Guardian and each later re-configuration | `registration` | + +A module lists the hooks it supports in `describe`; the catalog subscribes each +instance to some of them, and the Guardian refuses an instance subscribed to a +hook its module does not list. + +| `HookRequest` field | Contents | +|---|---| +| `request_id` | Unique per hook invocation and shared by every module called in it; log it to join your logs with the Guardian's | +| `hook` | Which hook is calling | +| `dry_run` | `true` for a policy check: nothing is stored or signed whatever you decide (see [Dry runs](#dry-runs)) | +| `network`, `network_id` | `"miden"`, and the network this Guardian serves: `"mainnet"`, `"testnet"`, `"devnet"`, `"cedar"` or `"local"`. It comes from the Guardian's own configuration, never from the account's registration | +| `account_id`, `instance_id` | The account, and the catalog id of the instance being called | +| `params` | UTF-8 JSON: the instance's global params, the account's layer on its second pass, or the account's own params for a `default` or `assigned` instance. Read them on every call; they change without restarting the module | +| `accounting_time` | The time recorded with the transaction if it is signed; at `before_proposal_created` and in a dry run, the evaluation time | +| `submitter`, `submitter_session` | The verified signer commitment that authenticated the request, and whether it did so through a session key it delegated | +| `before` | The account as the Guardian holds it. At `before_account_registered` it is absent for a first configuration and set to the stored state for a re-configuration, so "no `before`" means "new to this Guardian", not "registration" | +| `after` | The account as it will be if every module allows | +| `subject.transaction.projection` | The decoded transaction; read the Miden variant with `subject.miden()` | +| `subject.transaction.proposer` | The verified signer commitment that created the matching proposal; empty when there is none | +| `subject.transaction.unverified_metadata` | UTF-8 JSON the proposer asserted; never base a decision on it alone | +| `subject.transaction.raw` | The transaction in its network's own encoding (`encoding = "miden.transaction_summary"`), for modules that decode it themselves; tied to the Guardian's Miden version | +| `subject.transaction.pending` | Empty until commit notifications ship (M2b) | +| `subject.registration.initial_state` | The account about to be accepted: its whole vault and every storage slot, map entries included. Read the Miden variant with `subject.miden()` | + +An account view (`before`, `after`) carries the account `commitment`, its +`signer_commitments` with each signer's scheme in `signer_schemes` (`auth_scheme` +is `"falcon"`, `"ecdsa"` or `"mixed"`), `default_threshold` (absent for +single-key accounts), `procedure_thresholds`, `code_commitment` and the +`procedure_roots` the code exports. + +The Miden projection has the `nonce_delta`, the `bound_block` (the block the +summary binds; the transaction executes against it or a later one), the +optional `expiration_delta` (blocks after the block it executes against, set by +its script, so not an absolute height), the optional +`approval_expiration_block` (the block at which the cosigners' approval +lapses; use this one for "valid until"), `vault_changes` (asset and +direction), `output_notes` +(`note_type`, assets, `p2id_target` for known P2ID and P2IDE scripts, +`reclaimer` for a P2IDE note whose reclaim is enabled, `tx_fee`), `input_notes`, `storage_changes` by slot name, and +`new_code_commitment` when the transaction replaces the account's code. +Amounts are decimal strings. Skip the fee note (`tx_fee = true`) when counting +payments: every transaction pays its fee through an output note. The Guardian +sets `tx_fee` only on the one note the fee payment creates, and only while it +carries no more of the fee asset than a transaction can owe (64 times the +chain's base fee), never on another note that merely uses the fee script, so +treat every other note as a payment. + +A rule about who gets paid must judge `reclaimer` as well as `p2id_target`: the +creator of a P2IDE note picks the reclaimer freely, and once the note's reclaim +height is reached that account can consume it. A note to an allowed target with a +blocked reclaimer otherwise pays the blocked account. A reclaimer equal to the +paying account is the sender taking its own note back. + +Projections are tagged by network (`TransactionProjection`, `oneof network`). +Miden is the only network today; read it with `subject.miden()` and return a +`ModuleError` when it is absent, so a module never judges a transaction it +does not understand. + +## Personal data + +Requests can carry personal data: the proposer's free-text `description` in +`unverified_metadata`, and recipients and amounts that identify people. For a +remote module the operator treats you as a data processor, so document what +your module stores, for how long and where it runs. A module that does not +need a field should not log it, and `message` (logged by the Guardian for +every denial) should not repeat it. + +## Dry runs + +Cosigners can check a transaction before proposing it +(`POST /delta/proposal/check`). The Guardian then calls the account's gate +instances with `dry_run = true`: the creation instances, then those subscribed +only to `before_transaction_approved`. Decide exactly as you would otherwise; +`evaluate` has no side effects either way. An operator who does not want an +instance to see transactions that may never be proposed sets `dry_run = false` +in its catalog entry, and the check then reports `complete: false`. + +## Run it over gRPC + +For a complete example with data of its own (KYC on signers, sanctions or +allowlists on recipients), see [KYC and sanctions screening](./compliance.md). + +The [remote](./remote.md) page explains the transport. + +```sh +(umask 077; openssl rand -hex 32 > .guardian/note-policy.token) +cargo run -p guardian-module-sdk --example note-policy-serve -- \ + --listen 127.0.0.1:7444 --instance note-policy .guardian/note-policy.token +cp docs/guides/policy-modules/custom.toml .guardian/ +``` + +Set `GUARDIAN_MODULES_CONFIG=.guardian/custom.toml` in the guide's `.env` and +start the server as in the setup. The log line lists +`note-policy=note-policy `. + +The catalog names the token with `auth = { token_secret = "note-policy.token" }`; +the Guardian reads it through its secrets backend, and the module is started +with the same value. For TLS, mutual TLS and the AWS secrets provider, see +[remote modules](./remote.md#credentials) and +[`examples/policy-module`](../../../examples/policy-module/README.md), a +standalone service you can copy as a starting point. + +### Without the Rust SDK + +A module in another language implements the `GuardianModule` service from +[`guardian_module_v1.proto`](../../../crates/guardian-module-sdk/proto/guardian_module_v1.proto). +What the Guardian expects on the wire: + +- **Authentication.** Each call carries `authorization: Bearer `, the + instance's token. Check it against the instance the request names + (`HookRequest.instance_id`), and refuse an unknown instance. +- **Status codes.** `INVALID_ARGUMENT` means "I cannot judge this request": the + instance's `on_error` applies to that request only, and it does not count + toward the circuit breaker. `UNAVAILABLE`, `DEADLINE_EXCEEDED` and `UNKNOWN` + mean the module is down: they count toward the breaker, and on `Describe` at + startup an already-known instance starts unavailable instead of stopping the + server. Any other status (`UNAUTHENTICATED`, `PERMISSION_DENIED`, `INTERNAL`, + ...) means the Guardian cannot use the module: on `Describe` it stops startup + for a new instance and holds the breaker open until a health probe passes. +- **Decisions.** Set `effect` to `ALLOW` or `DENY`; an unset or unknown effect + is a module failure. A deny needs a `reason_code` of 1 to 64 characters of + `a-z`, `0-9` and `_` (another code is still a deny, but clients only see + `policy_denied`). +- **Time.** `timeout_ms` bounds the whole call, including the TCP connect and + the TLS handshake after the Guardian reconnects, so leave room for them. +- **Keepalive.** The Guardian sends HTTP/2 PINGs every 10 seconds on an idle + connection and drops it after 5 seconds without an answer. gRPC servers that + reject frequent pings by default (for example `grpc-go` and `grpc-java` + enforcement policies) must permit pings every 10 seconds without active + streams, or they close the connection with `too_many_pings`. +- **Size.** Requests can be up to `GUARDIAN_MODULE_REQUEST_MAX_BYTES` (2 MiB by + default): raise your server's receive limit if it is lower. +- **Stateful modules** (commit notifications, counting across transactions) + are not part of this protocol version yet; they arrive as a named + capability, so a module written now keeps working. + +The Rust conformance suite runs in process only, so port its cases (listed in +[Test it](#test-it)) to your language's test framework. + +## Run it in process + +A custom build is the official server plus one `with_module_kind` call per +kind. [`ServerBuilder::from_env`](../../../crates/server/src/builder/env.rs) +configures everything else from the environment exactly as the stock `server` +binary does, so there is no setup to copy or keep in step: + +```rust +ServerBuilder::from_env() + .await + .expect("Failed to configure server") + .with_module_kind("note-policy", Arc::new(NotePolicyFactory)) + .build() + .await + .expect("Failed to build server") + .run() + .await; +``` + +The factory gets each catalog instance's configuration and returns the module. +`build` fails if the kind name is already taken, including by a built-in +policy (`spending-limit`, `recipient-policy`, `signer-policy`, `code-policy`) or +`grpc`, and the server refuses to start with a catalog that enables an instance +of a kind it does not register. Builder methods called after `from_env` +override what the environment set. `from_env` and `build` return `BuildError`, a +`std::error::Error`, so a `main` returning `anyhow::Result` can use `?`. + +Run the example build, [`examples/custom-guardian`](../../../examples/custom-guardian/README.md): + +```sh +cp docs/guides/policy-modules/custom-in-process.toml .guardian/ +# set GUARDIAN_MODULES_CONFIG=.guardian/custom-in-process.toml in the guide's .env +set -a && . docs/guides/policy-modules/.env && set +a +cargo run -p custom-guardian +``` + +No module process, token or endpoint is involved. An in-process module that +needs a credential of its own, such as a vendor API key, names it in its +catalog params as `{ "$secret" = "" }`. The Guardian reads it at startup +and the factory gets the value from `ModuleInstanceConfig::secret("")`; +`HookRequest.params` keeps the reference, never the value. To run it next to another +Guardian, set `GUARDIAN_EXAMPLE_HTTP_PORT` and `GUARDIAN_EXAMPLE_GRPC_PORT` +(default 3000 and 50051). The stock binary refuses +this catalog at startup, since it does not know the `note-policy` kind. + +Each call still runs on its own task with the instance's `timeout_ms`, so a +panic in the module, or a timeout, is a module failure and `on_error` applies, +as for a remote module. Keep `evaluate` async and non-blocking all the same: a +module that blocks holds a runtime worker thread until it returns, even after +the Guardian has answered the request. + +### Your own build + +Start from the `custom-guardian-.tar.gz` attached to each Guardian +release, not from this repository: it is the example as a standalone project +that depends on `guardian-server` and `guardian-module-sdk` at the release tag +and carries the release's `Cargo.lock`. The Guardian needs the exact Miden and +Plonky3 versions it was released with, and a freshly resolved lockfile can +pick versions that build but break transaction execution, so always build with +`--locked`. Add your crate, register its kind, and build the image with the +template's `Dockerfile`, which uses the official image's toolchain and base. +Its [README](../../../examples/custom-guardian/README.md) has the steps. A +different copy of `guardian-module-sdk` is a different trait, so the server +and your module must share the release's: the template's `[patch.crates-io]` +points a crate that depends on the crates.io SDK at the release tag, and that +crate must accept the release's SDK version. + +On every Guardian release, start again from that release's template and +rebuild, sign and redeploy your image; the official image's provenance +attestation does not cover your build. + +## Try it + +| Test | Expected | +|---|---| +| A transaction with one payment note | Allowed | +| A transaction with two payment notes, if your client can build one | Refused with `too_many_payment_notes` | +| A payment sent as a private note, if your client supports it | Refused with `private_note_not_allowed` | +| `admin PUT /modules/note-policy/params '{"params":{"max_payment_notes":3},"reason":"test"}'` | Two notes allowed; private notes allowed too, since `deny_private_notes` now defaults to `false` | +| `admin PUT /modules/note-policy/params '{"params":{"max_notes":3},"reason":"typo"}'` | `400`, nothing stored: `validate_params` rejected the unknown field | + +The tests work the same in either mode. The module's own tests run with +`cargo test -p guardian-module-sdk --example note-policy-serve`. + +## Test it + +The SDK's conformance suite runs your module in process and over loopback gRPC, +with two instances on one service: + +```rust +use guardian_module_sdk::conformance::Suite; + +#[tokio::test] +async fn note_policy_conforms() { + Suite::new(NotePolicy) + .allows("one payment", one_payment()) + .denies_with("two payments", two_payments(), "too_many_payment_notes") + .valid_params(serde_json::json!({ "max_payment_notes": 1 })) + .invalid_params(serde_json::json!({ "max_notes": 1 })) + .run() + .await + .assert_conformant(); +} +``` + +It checks that `describe` reports protocol version 1 and known hooks, that +params validate the same over both transports and that normalized params +validate to themselves, that every request gets the same answer in process and +over gRPC, repeated, in reverse order and concurrently (so `evaluate` keeps no +state), that every deny has a valid `reason_code` and a plain `client_message` +of at most 256 characters, that each request is answered as the suite states +(`allows`, `denies`, `denies_with` a reason code, or `fails` for a request the +module cannot judge), that one instance's token is refused for another, +and that a request at the 2 MiB size cap goes through. A suite needs at least +one request the module must deny: a module that allows everything answers +consistently too, so consistency alone does not conform. A module written in +another language can port these cases to its own tests. `note-policy` and the four built-in policies run it in +[`tests/conformance.rs`](../../../crates/guardian-module-sdk/tests/conformance.rs). + +## Shipping your module + +- Use `serve(YourModule).instance(id, token)` from the SDK, or implement the + `GuardianModule` service from the proto in any language with gRPC support. +- Keep the module stateless for now. Limits that count across transactions + (daily caps) need the commit notifications of the RFC's M2b slice. +- Run the conformance suite in your CI, with requests that cover every rule. +- Prefer the remote path for code you do not own. In process, the rule that a + module can only refuse, never sign, holds by code review rather than by + isolation. +- A custom server build leaves the published image, so your release process has + to rebuild it from each release's `custom-guardian` template. diff --git a/docs/guides/policy-modules/custom.toml b/docs/guides/policy-modules/custom.toml new file mode 100644 index 000000000..889ac227e --- /dev/null +++ b/docs/guides/policy-modules/custom.toml @@ -0,0 +1,15 @@ +# Custom module: note-policy, written against guardian-module-sdk and served over gRPC. +# Copy to .guardian/custom.toml, put the bearer token in .guardian/note-policy.token (mode 0600), +# and start the module before the Guardian (see custom.md). + +[[module]] +id = "note-policy" +kind = "grpc" +endpoint = "grpc+insecure://127.0.0.1:7444" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 200 +on_error = "deny" +operator_can_disable = true +auth = { token_secret = "note-policy.token" } +params = { max_payment_notes = 1, deny_private_notes = true } diff --git a/docs/guides/policy-modules/operators.example.json b/docs/guides/policy-modules/operators.example.json new file mode 100644 index 000000000..abcce54b1 --- /dev/null +++ b/docs/guides/policy-modules/operators.example.json @@ -0,0 +1,6 @@ +[ + { + "public_key": "0xPASTE_THE_PUBLIC_KEY_FROM_modules_admin_keygen", + "permissions": ["dashboard:read", "policies:write", "policies:write_global", "modules:disable"] + } +] diff --git a/docs/guides/policy-modules/remote.md b/docs/guides/policy-modules/remote.md new file mode 100644 index 000000000..287931da8 --- /dev/null +++ b/docs/guides/policy-modules/remote.md @@ -0,0 +1,123 @@ +# Remote modules + +A remote module is its own service that implements the `GuardianModule` gRPC +API from +[`guardian_module_v1.proto`](../../../crates/guardian-module-sdk/proto/guardian_module_v1.proto). +The Guardian finds it through the catalog's `endpoint`, and the module +describes itself when the Guardian asks. This page runs the built-in +`spending-limit` policy as a remote service, so the only difference from the +[built-in](./built-in.md) page is the transport. Do the [setup](./README.md#setup) first; the catalog is +[`remote.toml`](./remote.toml). + +## How the Guardian talks to it + +| Call | When | Purpose | +|---|---|---| +| `Describe` | Startup, before enabling, and every 5 s as a health probe | Name, version, protocol version and supported hooks. A mismatch with the catalog stops startup. | +| `ValidateParams` | Startup, and on every params write | The module rejects params it cannot use; nothing is stored. | +| `Evaluate` | Every gated request | One request in, one decision out, within `timeout_ms`. | + +Each request carries the instance id, the params to apply (global or the +account's layer), the before and after account views, the decoded transaction +projection, the raw transaction summary, the verified submitter and proposer, +and the proposal's unverified metadata. The module keeps no params of its own, +so params changed through the API apply on the next request without +restarting it. + +To write your own remote module, in Rust or any language with gRPC, read +[custom modules](./custom.md): the protocol, every request field, the rules for +decisions, dry runs and the conformance suite. This page is about running one. + +## 1. Token and module + +Each instance authenticates the Guardian with a bearer token, sent on every +call: + +```sh +(umask 077; openssl rand -hex 32 > .guardian/caps.token) +cargo run -p guardian-policy-module -- --kind spending-limit \ + --listen 127.0.0.1:7443 --instance caps-remote .guardian/caps.token +``` + +The module is [`examples/policy-module`](../../../examples/policy-module/README.md), +built on the SDK's serve harness; `--kind` picks which of the four built-in +policies it serves. It accepts a call only for an instance id it +knows, with that instance's token. One process can host several instances, each +with its own token: repeat `--instance`. + +## 2. Catalog and server + +```sh +cp docs/guides/policy-modules/remote.toml .guardian/ +``` + +Replace the faucet placeholder, set `GUARDIAN_MODULES_CONFIG=.guardian/remote.toml` +in the guide's `.env`, and start the server as in the setup. The module must +already be running: an enabled instance that is new to this Guardian and +cannot be reached stops startup. Once the instance has started here, a later +start during a module outage succeeds with the instance unavailable (its +accounts get `GUARDIAN_MODULE_UNAVAILABLE`, or skip it with +`on_error = "allow"`) until a health probe passes its startup checks. +The log line lists `caps-remote=spending-limit `. + +`auth.token_secret` names a secret in the Guardian's secrets backend (see +[Credentials](#credentials)); here the `file` provider reads it from +`.guardian/caps.token`. + +## 3. Try it + +| Test | How | Expected | +|---|---|---| +| Remote refusal | Pay 4 | Refused by `caps-remote` (cap 3); the in-process `caps` (cap 5) allows it | +| Remote params | `admin PUT /modules/caps-remote/params '{"params":{"max_per_transaction":{"":"1"}},"reason":"test"}'`, then pay 2 | Refused; the module was not restarted | +| Module down, fail closed | Stop the module, pay 1 | `503 GUARDIAN_MODULE_UNAVAILABLE`, module `caps-remote` | +| Switch it off while down | `admin POST /modules/caps-remote/disable '{"reason":"module down"}'`, pay 1 | Allowed; start the module again and `/enable` (which re-runs `Describe` and `ValidateParams`) | +| Fail open | Set `on_error = "allow"`, restart the Guardian, stop the module, pay 1 | Allowed; the delta's `modules.failed_open` on the dashboard delta detail names `caps-remote` | +| Wrong token | Start the module with a different token file, restart the Guardian | Startup fails: the module rejects `Describe` | + +## Transport security + +- `grpc://host:port` is always TLS, verified against the system roots or a + private CA. Mutual TLS is optional: + + ```toml + endpoint = "grpc://risk.internal:7443" + tls = { ca_file = "risk-ca.pem", client_cert_secret = "guardian/modules/risk-cert", client_key_secret = "guardian/modules/risk-key" } + ``` + + `ca_file` is a path (relative to the catalog's directory); the client + certificate and key are secret names, like the token. + +- Plain text needs the explicit `grpc+insecure://` scheme and a loopback host + (`127.0.0.1`, `localhost`, `::1`), so a missing letter cannot turn TLS off. +- In the prod stage (`GUARDIAN_ENV=prod`) plain text is refused and `auth` is + mandatory for every remote instance. +- The example module serves TLS and mutual TLS itself (`--tls-cert`, + `--tls-key`, `--client-ca`); see its + [README](../../../examples/policy-module/README.md#tls). A module built on + the SDK harness does the same by adding the harness service to a tonic + server configured for TLS. + +## Credentials + +The token and the mTLS client certificate and key are secrets, named in the +catalog and read once at startup through the secrets backend that +`GUARDIAN_MODULE_SECRET_PROVIDER` selects: + +| Provider | Default for | A secret name is | +|---|---|---| +| `file` | every stage but prod | A path below `GUARDIAN_MODULE_SECRET_DIR` (the catalog's directory when unset). The file must be readable by its owner only (`0600`), or startup refuses it | +| `aws` | the prod stage | An AWS Secrets Manager secret id, read with the task's credentials (`AWS_REGION` required) | + +An enabled instance whose secret cannot be read stops startup; a disabled one +stays disabled. Changing a secret takes effect at the next restart. + +## What a remote module cannot do + +It cannot sign, change its hooks, or see secrets: catalog params with secret +references are refused for remote kinds. It can rewrite the params it is given +into its own normalized form when they are validated (at startup, on enable +and on every operator write), within the params size cap; the Guardian stores +that form, and with `disclosure = "params"` cosigners see it. The worst a compromised +or failing remote module can do is refuse (or, with `on_error = "allow"`, be +skipped), and the operator can switch it off if the catalog allows it. diff --git a/docs/guides/policy-modules/remote.toml b/docs/guides/policy-modules/remote.toml new file mode 100644 index 000000000..85e6fb28f --- /dev/null +++ b/docs/guides/policy-modules/remote.toml @@ -0,0 +1,40 @@ +# Remote module: the built-in spending-limit policy, served by a separate process over gRPC. +# Copy to .guardian/remote.toml, put the bearer token in .guardian/caps.token (mode 0600), +# and start the module before the Guardian (see remote.md). + +[[module]] +id = "caps" +kind = "spending-limit" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +operator_can_disable = true +params = { max_per_transaction = { "0xREPLACE_WITH_FAUCET_ID" = "5" } } + +# A tighter cap (3) than the in-process one (5), so refusals show which module decided. +[[module]] +id = "caps-remote" +kind = "grpc" +endpoint = "grpc+insecure://127.0.0.1:7443" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 200 +on_error = "deny" +operator_can_disable = true +auth = { token_secret = "caps.token" } +params = { max_per_transaction = { "0xREPLACE_WITH_FAUCET_ID" = "3" } } + +# The same module on another host, over TLS (examples/policy-module/README.md). Its token is +# read from AWS Secrets Manager in the prod stage; the CA file is relative to this catalog. +# [[module]] +# id = "caps-remote" +# kind = "grpc" +# endpoint = "grpc://policy-module.internal:7443" +# scope = "all" +# hooks = ["before_proposal_created", "before_transaction_approved"] +# timeout_ms = 200 +# on_error = "deny" +# operator_can_disable = true +# auth = { token_secret = "guardian/modules/caps-remote-token" } +# tls = { ca_file = "module-ca.pem" } diff --git a/docs/openapi-client.json b/docs/openapi-client.json index 385ec94a9..61db50919 100644 --- a/docs/openapi-client.json +++ b/docs/openapi-client.json @@ -984,6 +984,128 @@ ] } }, + "/delta/proposal/check": { + "post": { + "tags": [ + "client" + ], + "summary": "Dry run of `POST /delta/proposal`: the same checks and proposal-creation\npolicy modules, without storing a proposal or taking a slot. A refusal is\nthe same error proposal creation returns; `complete` is false when a module\nthat opts out of dry runs was skipped. Advisory: approval still decides.\nRate limited per account and signer (`GUARDIAN_MODULE_CHECK_RATE_PER_MIN`).", + "operationId": "check_delta_proposal", + "parameters": [ + { + "name": "x-auth-format", + "in": "header", + "description": "Optional ECDSA request format: eip712; omitted for raw signatures", + "required": false, + "schema": { + "type": [ + "string", + "null" + ] + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeltaProposalRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Proposal creation would pass", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CheckProposalResponse" + } + } + } + }, + "400": { + "description": "Invalid proposal payload", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed or replay rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "A policy module refused (GUARDIAN_MODULE_DENIED)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflicting / too many pending proposals", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Too many checks for this account and signer", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "A policy module is unavailable (GUARDIAN_MODULE_UNAVAILABLE)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "x-pubkey": [], + "x-signature": [], + "x-timestamp": [] + } + ] + } + }, "/delta/proposal/execution": { "get": { "tags": [ @@ -1391,6 +1513,106 @@ ] } }, + "/policies": { + "get": { + "tags": [ + "client" + ], + "summary": "The policy modules that apply to the account, as far as each module's\ncatalog entry discloses them (RFC 0002 section 2.7), in evaluation order.\nEmpty when the Guardian has no modules or discloses none.", + "operationId": "get_policies", + "parameters": [ + { + "name": "account_id", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "x-auth-format", + "in": "header", + "description": "Optional ECDSA request format: eip712; omitted for raw signatures", + "required": false, + "schema": { + "type": [ + "string", + "null" + ] + } + } + ], + "responses": { + "200": { + "description": "Disclosed policies", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PoliciesResponse" + } + } + } + }, + "400": { + "description": "The account is not a Miden account (unsupported_for_network)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed or replay rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "x-pubkey": [], + "x-signature": [], + "x-timestamp": [] + } + ] + } + }, "/pubkey": { "get": { "tags": [ @@ -2483,6 +2705,23 @@ } } }, + "CheckProposalResponse": { + "type": "object", + "required": [ + "allowed", + "complete" + ], + "properties": { + "allowed": { + "type": "boolean", + "description": "Always true: a refusal is returned as an error." + }, + "complete": { + "type": "boolean", + "description": "False when a module that opts out of dry runs was skipped." + } + } + }, "ConfigureRequest": { "type": "object", "required": [ @@ -2791,6 +3030,17 @@ } ] }, + "modules": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/ModuleApproval", + "description": "The policy module configuration that approved this delta, for operators: absent when no\nmodule ran, never included in client API responses, and served to operators on the\ndashboard delta detail." + } + ] + }, "note_counts": { "$ref": "#/components/schemas/NoteCounts" }, @@ -3207,6 +3457,26 @@ "canonicalization_disabled" ] }, + "FailedOpen": { + "type": "object", + "required": [ + "module_id", + "layer", + "failure" + ], + "properties": { + "failure": { + "type": "string", + "description": "`timeout`, `error`, `invalid_decision` or `circuit_open`; the\ndetail is logged." + }, + "layer": { + "type": "string" + }, + "module_id": { + "type": "string" + } + } + }, "HistoryEntry": { "type": "object", "description": "One canonical transaction in the history feed wire shape.\n`account_id` is omitted — the authenticated query scopes it.", @@ -3319,6 +3589,53 @@ "mainnet" ] }, + "ModuleApproval": { + "type": "object", + "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, the two params versions and the account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", + "required": [ + "catalog_hash", + "params_version", + "account_params_version", + "signed_at", + "submitter" + ], + "properties": { + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: its layers and assignment.", + "minimum": 0 + }, + "catalog_hash": { + "type": "string", + "description": "SHA-256 of the catalog file the approving replica loaded." + }, + "failed_open": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FailedOpen" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "description": "The instance params version: every instance's global params and enabled flag.", + "minimum": 0 + }, + "proposer": { + "type": "string", + "description": "The matching proposal's creator; empty when no stored proposal matched." + }, + "signed_at": { + "type": "string", + "description": "RFC 3339 time the Guardian signed, the accounting time the modules evaluated with." + }, + "submitter": { + "type": "string", + "description": "The cosigner the acknowledgment was evaluated for." + } + } + }, "NetworkConfig": { "oneOf": [ { @@ -3473,6 +3790,61 @@ } } }, + "PoliciesResponse": { + "type": "object", + "required": [ + "account_id", + "policies" + ], + "properties": { + "account_id": { + "type": "string" + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PolicyEntry" + } + } + } + }, + "PolicyEntry": { + "type": "object", + "description": "One policy as the account's cosigners see it.", + "required": [ + "module_id", + "hooks", + "description" + ], + "properties": { + "account_layer": { + "type": [ + "object", + "null" + ], + "description": "`disclosure = \"params\"` on a `scope = all` instance: this account's layer, when set." + }, + "description": { + "type": "string" + }, + "hooks": { + "type": "array", + "items": { + "type": "string" + } + }, + "module_id": { + "type": "string" + }, + "params": { + "type": [ + "object", + "null" + ], + "description": "`disclosure = \"params\"`: the instance's global params, or the account's own params for\nan assigned instance." + } + } + }, "ProposalMetadata": { "type": "object", "description": "Operator-stated intent lifted from a matching proposal.\nThe fields that bind a proposal to a block (`bound_block_num`, and the\nlegacy `chain_anchor`) remain only in the proposal payload, to avoid\nduplicating them in delta metadata and dashboard listings.", diff --git a/docs/openapi-dashboard.json b/docs/openapi-dashboard.json index 5a49ca367..72fe1016c 100644 --- a/docs/openapi-dashboard.json +++ b/docs/openapi-dashboard.json @@ -626,13 +626,106 @@ ] } }, - "/dashboard/accounts/{account_id}/pause": { - "post": { + "/dashboard/accounts/{account_id}/modules": { + "get": { "tags": [ "dashboard" ], - "summary": "Pause an account (blocks mutating actions). Requires the\n`accounts:pause` permission.", - "operationId": "pause_account_handler", + "operationId": "account_modules", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The account's effective module set, in evaluation order", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountModulesView" + } + } + } + }, + "400": { + "description": "No policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + }, + "put": { + "tags": [ + "dashboard" + ], + "operationId": "set_assignment", "parameters": [ { "name": "account_id", @@ -648,7 +741,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PauseAccountRequest" + "$ref": "#/components/schemas/AssignmentBody" } } }, @@ -656,17 +749,953 @@ }, "responses": { "200": { - "description": "Account paused", + "description": "Assignment stored", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PauseResponse" + "$ref": "#/components/schemas/AccountModulesView" } } } }, "400": { - "description": "Invalid or missing reason", + "description": "Invalid params, reason or assignment, or no policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/modules/{module_id}/params": { + "put": { + "tags": [ + "dashboard" + ], + "operationId": "set_account_layer", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParamsBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Account layer stored", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountModulesView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment, or no policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + }, + "delete": { + "tags": [ + "dashboard" + ], + "operationId": "remove_account_layer", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LayerRemovalBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Account layer removed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountModulesView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment, or no policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/pause": { + "post": { + "tags": [ + "dashboard" + ], + "summary": "Pause an account (blocks mutating actions). Requires the\n`accounts:pause` permission.", + "operationId": "pause_account_handler", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PauseAccountRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Account paused", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PauseResponse" + } + } + } + }, + "400": { + "description": "Invalid or missing reason", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing accounts:pause permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/proposals": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/accounts/{account_id}/proposals`. Returns the\nin-flight multisig proposal queue for one account, paginated\nnewest-first by `(nonce DESC, commitment DESC)`. Single-key Miden\nand EVM accounts always return an empty page per FR-017.", + "operationId": "list_account_proposals_handler", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Per-account in-flight proposal queue page", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PagedResult_DashboardProposalEntry" + } + } + } + }, + "400": { + "description": "Invalid limit or cursor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/snapshot": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "Decode and return the current vault snapshot for a Miden account.", + "operationId": "get_operator_account_snapshot", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Account snapshot", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardAccountSnapshot" + } + } + } + }, + "400": { + "description": "Unsupported for this network (e.g. EVM)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "Account state unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/unpause": { + "post": { + "tags": [ + "dashboard" + ], + "summary": "Unpause an account (idempotent). Requires the `accounts:pause`\npermission. Accepts an optional reason in the body.", + "operationId": "unpause_account_handler", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpauseAccountRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Account unpaused", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpauseResponse" + } + } + } + }, + "400": { + "description": "Invalid reason", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing accounts:pause permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/deltas": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/deltas`. Cross-account delta feed paginated\nnewest-first by `status_timestamp DESC`. Optional comma-separated\n`status` filter restricts to a subset of `{candidate, canonical,\nretained, discarded}`. Pending entries live on the proposal feed.", + "description": "Spec reference: `005-operator-dashboard-metrics` US6, FR-031..FR-035.", + "operationId": "list_global_deltas_handler", + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Cross-account delta feed page", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PagedResult_DashboardGlobalDeltaEntry" + } + } + } + }, + "400": { + "description": "Invalid limit, cursor, or status filter", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "Aggregate degraded (filesystem threshold exceeded)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/info": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/info` — point-in-time inventory and lifecycle\nsummary per feature `005-operator-dashboard-metrics` US2.", + "operationId": "get_dashboard_info_handler", + "responses": { + "200": { + "description": "Inventory and lifecycle summary", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardInfoResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules": { + "get": { + "tags": [ + "dashboard" + ], + "operationId": "list_modules", + "responses": { + "200": { + "description": "Module instances with their runtime state", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleCatalogView" + } + } + } + }, + "400": { + "description": "No policy modules are configured", "content": { "application/json": { "schema": { @@ -686,7 +1715,7 @@ } }, "403": { - "description": "Missing accounts:pause permission", + "description": "Missing dashboard:read permission", "content": { "application/json": { "schema": { @@ -696,7 +1725,7 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -733,53 +1762,46 @@ ] } }, - "/dashboard/accounts/{account_id}/proposals": { - "get": { + "/dashboard/modules/{module_id}/disable": { + "post": { "tags": [ "dashboard" ], - "summary": "`GET /dashboard/accounts/{account_id}/proposals`. Returns the\nin-flight multisig proposal queue for one account, paginated\nnewest-first by `(nonce DESC, commitment DESC)`. Single-key Miden\nand EVM accounts always return an empty page per FR-017.", - "operationId": "list_account_proposals_handler", + "operationId": "disable_module", "parameters": [ { - "name": "account_id", + "name": "module_id", "in": "path", - "description": "Account identifier", + "description": "Module instance id", "required": true, "schema": { "type": "string" } - }, - { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "cursor", - "in": "query", - "required": false, - "schema": { - "type": "string" - } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, "responses": { "200": { - "description": "Per-account in-flight proposal queue page", + "description": "Instance disabled", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PagedResult_DashboardProposalEntry" + "$ref": "#/components/schemas/ModuleInstanceView" } } } }, "400": { - "description": "Invalid limit or cursor", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -798,8 +1820,28 @@ } } }, + "403": { + "description": "Missing policies:write or modules:disable permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { - "description": "Account not found", + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "The catalog does not mark the instance operator_can_disable", "content": { "application/json": { "schema": { @@ -836,37 +1878,46 @@ ] } }, - "/dashboard/accounts/{account_id}/snapshot": { - "get": { + "/dashboard/modules/{module_id}/enable": { + "post": { "tags": [ "dashboard" ], - "summary": "Decode and return the current vault snapshot for a Miden account.", - "operationId": "get_operator_account_snapshot", + "operationId": "enable_module", "parameters": [ { - "name": "account_id", + "name": "module_id", "in": "path", - "description": "Account identifier", + "description": "Module instance id", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, "responses": { "200": { - "description": "Account snapshot", + "description": "Instance enabled", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardAccountSnapshot" + "$ref": "#/components/schemas/ModuleInstanceView" } } } }, "400": { - "description": "Unsupported for this network (e.g. EVM)", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -886,7 +1937,7 @@ } }, "403": { - "description": "Missing dashboard:read permission", + "description": "Missing policies:write permission", "content": { "application/json": { "schema": { @@ -896,7 +1947,7 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -926,7 +1977,7 @@ } }, "503": { - "description": "Account state unavailable", + "description": "The module failed its startup checks; nothing changed", "content": { "application/json": { "schema": { @@ -943,18 +1994,17 @@ ] } }, - "/dashboard/accounts/{account_id}/unpause": { - "post": { + "/dashboard/modules/{module_id}/params": { + "put": { "tags": [ "dashboard" ], - "summary": "Unpause an account (idempotent). Requires the `accounts:pause`\npermission. Accepts an optional reason in the body.", - "operationId": "unpause_account_handler", + "operationId": "set_global_params", "parameters": [ { - "name": "account_id", + "name": "module_id", "in": "path", - "description": "Account identifier", + "description": "Module instance id", "required": true, "schema": { "type": "string" @@ -965,7 +2015,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnpauseAccountRequest" + "$ref": "#/components/schemas/ParamsBody" } } }, @@ -973,17 +2023,17 @@ }, "responses": { "200": { - "description": "Account unpaused", + "description": "Global params stored", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnpauseResponse" + "$ref": "#/components/schemas/ModuleInstanceView" } } } }, "400": { - "description": "Invalid reason", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1003,7 +2053,7 @@ } }, "403": { - "description": "Missing accounts:pause permission", + "description": "Missing policies:write_global permission", "content": { "application/json": { "schema": { @@ -1013,7 +2063,17 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", "content": { "application/json": { "schema": { @@ -1050,53 +2110,57 @@ ] } }, - "/dashboard/deltas": { + "/dashboard/modules/{module_id}/params/history": { "get": { "tags": [ "dashboard" ], - "summary": "`GET /dashboard/deltas`. Cross-account delta feed paginated\nnewest-first by `status_timestamp DESC`. Optional comma-separated\n`status` filter restricts to a subset of `{candidate, canonical,\nretained, discarded}`. Pending entries live on the proposal feed.", - "description": "Spec reference: `005-operator-dashboard-metrics` US6, FR-031..FR-035.", - "operationId": "list_global_deltas_handler", + "operationId": "params_history", "parameters": [ { - "name": "limit", - "in": "query", - "required": false, + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, "schema": { "type": "string" } }, { - "name": "cursor", + "name": "before", "in": "query", + "description": "Only entries whose `id` is below this one, to page backwards.", "required": false, "schema": { - "type": "string" + "type": "integer", + "format": "int64", + "minimum": 0 } }, { - "name": "status", + "name": "limit", "in": "query", + "description": "At most this many entries (1 to 1,000; default 100).", "required": false, "schema": { - "type": "string" + "type": "integer", + "minimum": 0 } } ], "responses": { "200": { - "description": "Cross-account delta feed page", + "description": "Params changes, newest first", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PagedResult_DashboardGlobalDeltaEntry" + "$ref": "#/components/schemas/ParamsHistoryView" } } } }, "400": { - "description": "Invalid limit, cursor, or status filter", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1115,64 +2179,8 @@ } } }, - "413": { - "description": "Request body exceeds the configured size limit", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "429": { - "description": "Rate limit exceeded", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "503": { - "description": "Aggregate degraded (filesystem threshold exceeded)", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - } - }, - "security": [ - { - "operator_session": [] - } - ] - } - }, - "/dashboard/info": { - "get": { - "tags": [ - "dashboard" - ], - "summary": "`GET /dashboard/info` — point-in-time inventory and lifecycle\nsummary per feature `005-operator-dashboard-metrics` US2.", - "operationId": "get_dashboard_info_handler", - "responses": { - "200": { - "description": "Inventory and lifecycle summary", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DashboardInfoResponse" - } - } - } - }, - "401": { - "description": "No operator session", + "403": { + "description": "Missing dashboard:read permission", "content": { "application/json": { "schema": { @@ -1181,8 +2189,8 @@ } } }, - "403": { - "description": "Missing dashboard:read permission", + "404": { + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -1537,6 +2545,73 @@ }, "components": { "schemas": { + "AccountModuleEntry": { + "type": "object", + "required": [ + "module_id", + "scope", + "enabled", + "orphaned" + ], + "properties": { + "account_layer": { + "type": [ + "object", + "null" + ] + }, + "enabled": { + "type": "boolean" + }, + "global_params": { + "type": [ + "object", + "null" + ] + }, + "module_id": { + "type": "string" + }, + "orphaned": { + "type": "boolean", + "description": "A stored entry naming an instance the catalog no longer declares; skipped at evaluation." + }, + "params": { + "type": [ + "object", + "null" + ] + }, + "scope": { + "type": "string" + } + } + }, + "AccountModulesView": { + "type": "object", + "required": [ + "account_id", + "account_params_version", + "modules" + ], + "properties": { + "account_id": { + "type": "string" + }, + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: moves with every write to its layers or assignment, and\nis recorded with each delta the account's modules approve.", + "minimum": 0 + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AccountModuleEntry" + } + } + } + }, "AccountStatus": { "type": "string", "enum": [ @@ -1665,28 +2740,78 @@ "non_fungible" ] }, - "AssetSummary": { + "AssetSummary": { + "type": "object", + "required": [ + "asset_id", + "kind" + ], + "properties": { + "amount": { + "type": [ + "string", + "null" + ], + "description": "Signed decimal magnitude (e.g., `\"+100\"`, `\"-50\"`) for fungible\nholdings. Absent for non-fungible holdings where the detail\nview uses `added` / `removed` lists instead." + }, + "asset_id": { + "type": "string" + }, + "kind": { + "$ref": "#/components/schemas/AssetKind" + } + } + }, + "Assigned": { + "type": "object", + "required": [ + "module_id", + "params" + ], + "properties": { + "module_id": { + "type": "string" + }, + "params": { + "type": "object" + } + } + }, + "AssignmentBody": { "type": "object", "required": [ - "asset_id", - "kind" + "modules", + "reason" ], "properties": { - "amount": { + "expected_version": { "type": [ - "string", + "integer", "null" ], - "description": "Signed decimal magnitude (e.g., `\"+100\"`, `\"-50\"`) for fungible\nholdings. Absent for non-fungible holdings where the detail\nview uses `added` / `removed` lists instead." + "format": "int64", + "description": "The `account_params_version` the assignment was made against; see [`ParamsBody`].", + "minimum": 0 }, - "asset_id": { - "type": "string" + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Assigned" + } }, - "kind": { - "$ref": "#/components/schemas/AssetKind" + "reason": { + "type": "string" } } }, + "ClientReason": { + "type": "string", + "description": "How a denial from an instance reaches the client (RFC 0002 section 4.1).", + "enum": [ + "full", + "generic" + ] + }, "CounterpartyDirection": { "type": "string", "enum": [ @@ -2069,6 +3194,13 @@ } ] }, + "module_catalog_hash": { + "type": [ + "string", + "null" + ], + "description": "Hash of the policy module catalog this replica loaded; `None` when\nno catalog is configured. Replicas of one deploy report the same hash." + }, "release_sweep": { "oneOf": [ { @@ -2313,6 +3445,17 @@ "$ref": "#/components/schemas/DecodedNote" } }, + "modules": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/ModuleApproval", + "description": "The policy module configuration that approved this delta: the catalog and params version\nit was judged under and the module failures an `on_error = allow` instance let through.\nAbsent when no module ran." + } + ] + }, "new_commitment": { "type": [ "string", @@ -3143,6 +4286,109 @@ } } }, + "Disclosure": { + "type": "string", + "description": "What an account's cosigners may learn about an instance (RFC 0002 section 2.7).", + "enum": [ + "none", + "summary", + "params" + ] + }, + "FailedOpen": { + "type": "object", + "required": [ + "module_id", + "layer", + "failure" + ], + "properties": { + "failure": { + "type": "string", + "description": "`timeout`, `error`, `invalid_decision` or `circuit_open`; the\ndetail is logged." + }, + "layer": { + "type": "string" + }, + "module_id": { + "type": "string" + } + } + }, + "HistoryEntry": { + "type": "object", + "required": [ + "version", + "module_id", + "operator", + "reason", + "at" + ], + "properties": { + "account_id": { + "type": [ + "string", + "null" + ] + }, + "at": { + "type": "string" + }, + "id": { + "type": "integer", + "format": "int64", + "description": "The entry's place in the history, increasing in write order: the cursor a page of\nhistory is read below.", + "minimum": 0 + }, + "module_id": { + "type": "string" + }, + "new": { + "type": [ + "object", + "null" + ] + }, + "operator": { + "type": "string" + }, + "previous": { + "type": [ + "object", + "null" + ] + }, + "reason": { + "type": "string" + }, + "version": { + "type": "integer", + "format": "int64", + "description": "The params version the write committed as: the instance params version for an entry\nwithout `account_id`, that account's params version for one with it.", + "minimum": 0 + } + } + }, + "LayerRemovalBody": { + "type": "object", + "required": [ + "reason" + ], + "properties": { + "expected_version": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "description": "The `account_params_version` the removal was made against; see [`ParamsBody`].", + "minimum": 0 + }, + "reason": { + "type": "string" + } + } + }, "LogoutOperatorResponse": { "type": "object", "required": [ @@ -3154,6 +4400,169 @@ } } }, + "ModuleApproval": { + "type": "object", + "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, the two params versions and the account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", + "required": [ + "catalog_hash", + "params_version", + "account_params_version", + "signed_at", + "submitter" + ], + "properties": { + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: its layers and assignment.", + "minimum": 0 + }, + "catalog_hash": { + "type": "string", + "description": "SHA-256 of the catalog file the approving replica loaded." + }, + "failed_open": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FailedOpen" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "description": "The instance params version: every instance's global params and enabled flag.", + "minimum": 0 + }, + "proposer": { + "type": "string", + "description": "The matching proposal's creator; empty when no stored proposal matched." + }, + "signed_at": { + "type": "string", + "description": "RFC 3339 time the Guardian signed, the accounting time the modules evaluated with." + }, + "submitter": { + "type": "string", + "description": "The cosigner the acknowledgment was evaluated for." + } + } + }, + "ModuleCatalogView": { + "type": "object", + "required": [ + "catalog_hash", + "params_version", + "modules", + "undeclared" + ], + "properties": { + "catalog_hash": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "minimum": 0 + }, + "undeclared": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UndeclaredInstanceView" + }, + "description": "Stored instances the catalog no longer declares: kept, never evaluated, active again if\nthe catalog brings the id back." + } + } + }, + "ModuleInstanceView": { + "type": "object", + "required": [ + "module_id", + "kind", + "scope", + "hooks", + "enabled", + "catalog_enabled", + "enabled_drift", + "operator_can_disable", + "params", + "params_drift", + "file_managed_params", + "disclosure", + "client_reason", + "dry_run", + "circuit" + ], + "properties": { + "build": { + "type": [ + "string", + "null" + ], + "description": "`name version` from `describe` at startup; absent when the startup checks failed." + }, + "catalog_enabled": { + "type": "boolean" + }, + "circuit": { + "type": "string", + "description": "The instance's circuit breaker on the replica that answered: `closed`, `open` or\n`half_open`." + }, + "client_reason": { + "$ref": "#/components/schemas/ClientReason" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "disclosure": { + "$ref": "#/components/schemas/Disclosure" + }, + "dry_run": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "enabled_drift": { + "type": "boolean" + }, + "file_managed_params": { + "type": "boolean" + }, + "hooks": { + "type": "array", + "items": { + "type": "string" + } + }, + "kind": { + "type": "string" + }, + "module_id": { + "type": "string" + }, + "operator_can_disable": { + "type": "boolean" + }, + "params": { + "type": "object" + }, + "params_drift": { + "type": "boolean" + }, + "scope": { + "type": "string" + } + } + }, "NoteCounts": { "type": "object", "properties": { @@ -3690,6 +5099,48 @@ } } }, + "ParamsBody": { + "type": "object", + "required": [ + "params", + "reason" + ], + "properties": { + "expected_version": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "description": "The params version the change was made against: `params_version` for a global write,\n`account_params_version` for an account layer. Set, a write after another change is\nrefused with 409 `GUARDIAN_MODULE_PARAMS_STALE`.", + "minimum": 0 + }, + "params": { + "type": "object" + }, + "reason": { + "type": "string" + } + } + }, + "ParamsHistoryView": { + "type": "object", + "required": [ + "module_id", + "entries" + ], + "properties": { + "entries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HistoryEntry" + } + }, + "module_id": { + "type": "string" + } + } + }, "PauseAccountRequest": { "type": "object", "required": [ @@ -3865,6 +5316,17 @@ } } }, + "ReasonBody": { + "type": "object", + "required": [ + "reason" + ], + "properties": { + "reason": { + "type": "string" + } + } + }, "SessionInfoResponse": { "type": "object", "required": [ @@ -3916,6 +5378,25 @@ } } }, + "UndeclaredInstanceView": { + "type": "object", + "required": [ + "module_id", + "enabled", + "params" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "module_id": { + "type": "string" + }, + "params": { + "type": "object" + } + } + }, "UnpauseAccountRequest": { "type": "object", "properties": { diff --git a/docs/openapi.json b/docs/openapi.json index acc9826c5..844c09264 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -789,13 +789,106 @@ ] } }, - "/dashboard/accounts/{account_id}/pause": { - "post": { + "/dashboard/accounts/{account_id}/modules": { + "get": { "tags": [ "dashboard" ], - "summary": "Pause an account (blocks mutating actions). Requires the\n`accounts:pause` permission.", - "operationId": "pause_account_handler", + "operationId": "account_modules", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The account's effective module set, in evaluation order", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountModulesView" + } + } + } + }, + "400": { + "description": "No policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + }, + "put": { + "tags": [ + "dashboard" + ], + "operationId": "set_assignment", "parameters": [ { "name": "account_id", @@ -811,7 +904,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PauseAccountRequest" + "$ref": "#/components/schemas/AssignmentBody" } } }, @@ -819,17 +912,17 @@ }, "responses": { "200": { - "description": "Account paused", + "description": "Assignment stored", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PauseResponse" + "$ref": "#/components/schemas/AccountModulesView" } } } }, "400": { - "description": "Invalid or missing reason", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -849,7 +942,7 @@ } }, "403": { - "description": "Missing accounts:pause permission", + "description": "Missing policies:write permission", "content": { "application/json": { "schema": { @@ -859,7 +952,17 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", "content": { "application/json": { "schema": { @@ -896,13 +999,12 @@ ] } }, - "/dashboard/accounts/{account_id}/proposals": { - "get": { + "/dashboard/accounts/{account_id}/modules/{module_id}/params": { + "put": { "tags": [ "dashboard" ], - "summary": "`GET /dashboard/accounts/{account_id}/proposals`. Returns the\nin-flight multisig proposal queue for one account, paginated\nnewest-first by `(nonce DESC, commitment DESC)`. Single-key Miden\nand EVM accounts always return an empty page per FR-017.", - "operationId": "list_account_proposals_handler", + "operationId": "set_account_layer", "parameters": [ { "name": "account_id", @@ -914,35 +1016,975 @@ } }, { - "name": "limit", - "in": "query", - "required": false, + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParamsBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Account layer stored", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountModulesView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment, or no policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + }, + "delete": { + "tags": [ + "dashboard" + ], + "operationId": "remove_account_layer", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, "schema": { "type": "string" } }, { - "name": "cursor", - "in": "query", - "required": false, + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LayerRemovalBody" + } + } + }, + "required": true + }, "responses": { "200": { - "description": "Per-account in-flight proposal queue page", + "description": "Account layer removed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountModulesView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment, or no policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/pause": { + "post": { + "tags": [ + "dashboard" + ], + "summary": "Pause an account (blocks mutating actions). Requires the\n`accounts:pause` permission.", + "operationId": "pause_account_handler", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PauseAccountRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Account paused", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PauseResponse" + } + } + } + }, + "400": { + "description": "Invalid or missing reason", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing accounts:pause permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/proposals": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/accounts/{account_id}/proposals`. Returns the\nin-flight multisig proposal queue for one account, paginated\nnewest-first by `(nonce DESC, commitment DESC)`. Single-key Miden\nand EVM accounts always return an empty page per FR-017.", + "operationId": "list_account_proposals_handler", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Per-account in-flight proposal queue page", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PagedResult_DashboardProposalEntry" + } + } + } + }, + "400": { + "description": "Invalid limit or cursor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/snapshot": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "Decode and return the current vault snapshot for a Miden account.", + "operationId": "get_operator_account_snapshot", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Account snapshot", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardAccountSnapshot" + } + } + } + }, + "400": { + "description": "Unsupported for this network (e.g. EVM)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "Account state unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/unpause": { + "post": { + "tags": [ + "dashboard" + ], + "summary": "Unpause an account (idempotent). Requires the `accounts:pause`\npermission. Accepts an optional reason in the body.", + "operationId": "unpause_account_handler", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpauseAccountRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Account unpaused", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpauseResponse" + } + } + } + }, + "400": { + "description": "Invalid reason", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing accounts:pause permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/deltas": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/deltas`. Cross-account delta feed paginated\nnewest-first by `status_timestamp DESC`. Optional comma-separated\n`status` filter restricts to a subset of `{candidate, canonical,\nretained, discarded}`. Pending entries live on the proposal feed.", + "description": "Spec reference: `005-operator-dashboard-metrics` US6, FR-031..FR-035.", + "operationId": "list_global_deltas_handler", + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Cross-account delta feed page", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PagedResult_DashboardGlobalDeltaEntry" + } + } + } + }, + "400": { + "description": "Invalid limit, cursor, or status filter", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "Aggregate degraded (filesystem threshold exceeded)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/info": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/info` — point-in-time inventory and lifecycle\nsummary per feature `005-operator-dashboard-metrics` US2.", + "operationId": "get_dashboard_info_handler", + "responses": { + "200": { + "description": "Inventory and lifecycle summary", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardInfoResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules": { + "get": { + "tags": [ + "dashboard" + ], + "operationId": "list_modules", + "responses": { + "200": { + "description": "Module instances with their runtime state", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleCatalogView" + } + } + } + }, + "400": { + "description": "No policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules/{module_id}/disable": { + "post": { + "tags": [ + "dashboard" + ], + "operationId": "disable_module", + "parameters": [ + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Instance disabled", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment, or no policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PagedResult_DashboardProposalEntry" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "400": { - "description": "Invalid limit or cursor", + "403": { + "description": "Missing policies:write or modules:disable permission", "content": { "application/json": { "schema": { @@ -951,8 +1993,8 @@ } } }, - "401": { - "description": "No operator session", + "404": { + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -961,8 +2003,8 @@ } } }, - "404": { - "description": "Account not found", + "409": { + "description": "The catalog does not mark the instance operator_can_disable", "content": { "application/json": { "schema": { @@ -999,37 +2041,46 @@ ] } }, - "/dashboard/accounts/{account_id}/snapshot": { - "get": { + "/dashboard/modules/{module_id}/enable": { + "post": { "tags": [ "dashboard" ], - "summary": "Decode and return the current vault snapshot for a Miden account.", - "operationId": "get_operator_account_snapshot", + "operationId": "enable_module", "parameters": [ { - "name": "account_id", + "name": "module_id", "in": "path", - "description": "Account identifier", + "description": "Module instance id", "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, "responses": { "200": { - "description": "Account snapshot", + "description": "Instance enabled", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardAccountSnapshot" + "$ref": "#/components/schemas/ModuleInstanceView" } } } }, "400": { - "description": "Unsupported for this network (e.g. EVM)", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1049,7 +2100,7 @@ } }, "403": { - "description": "Missing dashboard:read permission", + "description": "Missing policies:write permission", "content": { "application/json": { "schema": { @@ -1059,7 +2110,7 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -1089,7 +2140,7 @@ } }, "503": { - "description": "Account state unavailable", + "description": "The module failed its startup checks; nothing changed", "content": { "application/json": { "schema": { @@ -1106,18 +2157,17 @@ ] } }, - "/dashboard/accounts/{account_id}/unpause": { - "post": { + "/dashboard/modules/{module_id}/params": { + "put": { "tags": [ "dashboard" ], - "summary": "Unpause an account (idempotent). Requires the `accounts:pause`\npermission. Accepts an optional reason in the body.", - "operationId": "unpause_account_handler", + "operationId": "set_global_params", "parameters": [ { - "name": "account_id", + "name": "module_id", "in": "path", - "description": "Account identifier", + "description": "Module instance id", "required": true, "schema": { "type": "string" @@ -1128,7 +2178,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnpauseAccountRequest" + "$ref": "#/components/schemas/ParamsBody" } } }, @@ -1136,17 +2186,17 @@ }, "responses": { "200": { - "description": "Account unpaused", + "description": "Global params stored", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnpauseResponse" + "$ref": "#/components/schemas/ModuleInstanceView" } } } }, "400": { - "description": "Invalid reason", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1166,7 +2216,7 @@ } }, "403": { - "description": "Missing accounts:pause permission", + "description": "Missing policies:write_global permission", "content": { "application/json": { "schema": { @@ -1176,7 +2226,17 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "expected_version is set and the params changed since (GUARDIAN_MODULE_PARAMS_STALE)", "content": { "application/json": { "schema": { @@ -1213,53 +2273,57 @@ ] } }, - "/dashboard/deltas": { + "/dashboard/modules/{module_id}/params/history": { "get": { "tags": [ "dashboard" ], - "summary": "`GET /dashboard/deltas`. Cross-account delta feed paginated\nnewest-first by `status_timestamp DESC`. Optional comma-separated\n`status` filter restricts to a subset of `{candidate, canonical,\nretained, discarded}`. Pending entries live on the proposal feed.", - "description": "Spec reference: `005-operator-dashboard-metrics` US6, FR-031..FR-035.", - "operationId": "list_global_deltas_handler", + "operationId": "params_history", "parameters": [ { - "name": "limit", - "in": "query", - "required": false, + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, "schema": { "type": "string" } }, { - "name": "cursor", + "name": "before", "in": "query", + "description": "Only entries whose `id` is below this one, to page backwards.", "required": false, "schema": { - "type": "string" + "type": "integer", + "format": "int64", + "minimum": 0 } }, { - "name": "status", + "name": "limit", "in": "query", + "description": "At most this many entries (1 to 1,000; default 100).", "required": false, "schema": { - "type": "string" + "type": "integer", + "minimum": 0 } } ], "responses": { "200": { - "description": "Cross-account delta feed page", + "description": "Params changes, newest first", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PagedResult_DashboardGlobalDeltaEntry" + "$ref": "#/components/schemas/ParamsHistoryView" } } } }, "400": { - "description": "Invalid limit, cursor, or status filter", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1278,64 +2342,8 @@ } } }, - "413": { - "description": "Request body exceeds the configured size limit", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "429": { - "description": "Rate limit exceeded", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "503": { - "description": "Aggregate degraded (filesystem threshold exceeded)", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - } - }, - "security": [ - { - "operator_session": [] - } - ] - } - }, - "/dashboard/info": { - "get": { - "tags": [ - "dashboard" - ], - "summary": "`GET /dashboard/info` — point-in-time inventory and lifecycle\nsummary per feature `005-operator-dashboard-metrics` US2.", - "operationId": "get_dashboard_info_handler", - "responses": { - "200": { - "description": "Inventory and lifecycle summary", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DashboardInfoResponse" - } - } - } - }, - "401": { - "description": "No operator session", + "403": { + "description": "Missing dashboard:read permission", "content": { "application/json": { "schema": { @@ -1344,8 +2352,8 @@ } } }, - "403": { - "description": "Missing dashboard:read permission", + "404": { + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -2245,21 +3253,131 @@ "null" ] } - } - ], - "responses": { - "200": { - "description": "Pending proposals, each without its stored `transaction_request` (the single-proposal read returns it)", + } + ], + "responses": { + "200": { + "description": "Pending proposals, each without its stored `transaction_request` (the single-proposal read returns it)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProposalsResponse" + } + } + } + }, + "401": { + "description": "Authentication failed or replay rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "x-pubkey": [], + "x-signature": [], + "x-timestamp": [] + } + ] + }, + "put": { + "tags": [ + "client" + ], + "summary": "Add a cosigner signature to an existing multisig proposal. The approval\nis credited to the cosigner its signature cryptographically verifies\nfor, so an authenticated signer may also relay an approval another\ncosigner produced off channel. When the signature threshold is reached\nthe proposal is promoted to a delta.", + "operationId": "sign_delta_proposal", + "parameters": [ + { + "name": "x-auth-format", + "in": "header", + "description": "Optional request format: eip712 (ECDSA wallet), or session-v2 (session key, on session routes); omitted for raw wallet signatures", + "required": false, + "schema": { + "type": [ + "string", + "null" + ] + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignProposalRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Signature accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeltaObject" + } + } + } + }, + "400": { + "description": "Invalid signature", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed or replay rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Proposal not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ProposalsResponse" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "Authentication failed or replay rejected", + "409": { + "description": "Proposal already signed by this signer", "content": { "application/json": { "schema": { @@ -2297,12 +3415,12 @@ } ] }, - "put": { + "post": { "tags": [ "client" ], - "summary": "Add a cosigner signature to an existing multisig proposal. The approval\nis credited to the cosigner its signature cryptographically verifies\nfor, so an authenticated signer may also relay an approval another\ncosigner produced off channel. When the signature threshold is reached\nthe proposal is promoted to a delta.", - "operationId": "sign_delta_proposal", + "summary": "Create a new multisig delta proposal for cosigners to sign.", + "operationId": "push_delta_proposal", "parameters": [ { "name": "x-auth-format", @@ -2321,7 +3439,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SignProposalRequest" + "$ref": "#/components/schemas/DeltaProposalRequest" } } }, @@ -2329,17 +3447,17 @@ }, "responses": { "200": { - "description": "Signature accepted", + "description": "Proposal created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeltaObject" + "$ref": "#/components/schemas/DeltaProposalResponse" } } } }, "400": { - "description": "Invalid signature", + "description": "Invalid proposal payload", "content": { "application/json": { "schema": { @@ -2358,18 +3476,8 @@ } } }, - "404": { - "description": "Proposal not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "409": { - "description": "Proposal already signed by this signer", + "description": "Conflicting / too many pending proposals, or the account's stored requests would exceed their capacity (GUARDIAN_ACCOUNT_REQUEST_CAPACITY_EXCEEDED)", "content": { "application/json": { "schema": { @@ -2379,7 +3487,7 @@ } }, "413": { - "description": "Request body exceeds the configured size limit", + "description": "The stored transaction request exceeds the per-request limit (GUARDIAN_PROPOSAL_REQUEST_TOO_LARGE)", "content": { "application/json": { "schema": { @@ -2406,18 +3514,20 @@ "x-timestamp": [] } ] - }, + } + }, + "/delta/proposal/check": { "post": { "tags": [ "client" ], - "summary": "Create a new multisig delta proposal for cosigners to sign.", - "operationId": "push_delta_proposal", + "summary": "Dry run of `POST /delta/proposal`: the same checks and proposal-creation\npolicy modules, without storing a proposal or taking a slot. A refusal is\nthe same error proposal creation returns; `complete` is false when a module\nthat opts out of dry runs was skipped. Advisory: approval still decides.\nRate limited per account and signer (`GUARDIAN_MODULE_CHECK_RATE_PER_MIN`).", + "operationId": "check_delta_proposal", "parameters": [ { "name": "x-auth-format", "in": "header", - "description": "Optional request format: eip712 (ECDSA wallet), or session-v2 (session key, on session routes); omitted for raw wallet signatures", + "description": "Optional ECDSA request format: eip712; omitted for raw signatures", "required": false, "schema": { "type": [ @@ -2439,11 +3549,11 @@ }, "responses": { "200": { - "description": "Proposal created", + "description": "Proposal creation would pass", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeltaProposalResponse" + "$ref": "#/components/schemas/CheckProposalResponse" } } } @@ -2468,8 +3578,18 @@ } } }, + "403": { + "description": "A policy module refused (GUARDIAN_MODULE_DENIED)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "409": { - "description": "Conflicting / too many pending proposals, or the account's stored requests would exceed their capacity (GUARDIAN_ACCOUNT_REQUEST_CAPACITY_EXCEEDED)", + "description": "Conflicting / too many pending proposals", "content": { "application/json": { "schema": { @@ -2479,7 +3599,7 @@ } }, "413": { - "description": "The stored transaction request exceeds the per-request limit (GUARDIAN_PROPOSAL_REQUEST_TOO_LARGE)", + "description": "Request body exceeds the configured size limit", "content": { "application/json": { "schema": { @@ -2489,7 +3609,17 @@ } }, "429": { - "description": "Rate limit exceeded", + "description": "Too many checks for this account and signer", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "A policy module is unavailable (GUARDIAN_MODULE_UNAVAILABLE)", "content": { "application/json": { "schema": { @@ -3723,6 +4853,106 @@ ] } }, + "/policies": { + "get": { + "tags": [ + "client" + ], + "summary": "The policy modules that apply to the account, as far as each module's\ncatalog entry discloses them (RFC 0002 section 2.7), in evaluation order.\nEmpty when the Guardian has no modules or discloses none.", + "operationId": "get_policies", + "parameters": [ + { + "name": "account_id", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "x-auth-format", + "in": "header", + "description": "Optional ECDSA request format: eip712; omitted for raw signatures", + "required": false, + "schema": { + "type": [ + "string", + "null" + ] + } + } + ], + "responses": { + "200": { + "description": "Disclosed policies", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PoliciesResponse" + } + } + } + }, + "400": { + "description": "The account is not a Miden account (unsupported_for_network)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed or replay rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "x-pubkey": [], + "x-signature": [], + "x-timestamp": [] + } + ] + } + }, "/pubkey": { "get": { "tags": [ @@ -4543,6 +5773,73 @@ } } }, + "AccountModuleEntry": { + "type": "object", + "required": [ + "module_id", + "scope", + "enabled", + "orphaned" + ], + "properties": { + "account_layer": { + "type": [ + "object", + "null" + ] + }, + "enabled": { + "type": "boolean" + }, + "global_params": { + "type": [ + "object", + "null" + ] + }, + "module_id": { + "type": "string" + }, + "orphaned": { + "type": "boolean", + "description": "A stored entry naming an instance the catalog no longer declares; skipped at evaluation." + }, + "params": { + "type": [ + "object", + "null" + ] + }, + "scope": { + "type": "string" + } + } + }, + "AccountModulesView": { + "type": "object", + "required": [ + "account_id", + "account_params_version", + "modules" + ], + "properties": { + "account_id": { + "type": "string" + }, + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: moves with every write to its layers or assignment, and\nis recorded with each delta the account's modules approve.", + "minimum": 0 + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AccountModuleEntry" + } + } + } + }, "AccountStatus": { "type": "string", "enum": [ @@ -4708,6 +6005,48 @@ } } }, + "Assigned": { + "type": "object", + "required": [ + "module_id", + "params" + ], + "properties": { + "module_id": { + "type": "string" + }, + "params": { + "type": "object" + } + } + }, + "AssignmentBody": { + "type": "object", + "required": [ + "modules", + "reason" + ], + "properties": { + "expected_version": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "description": "The `account_params_version` the assignment was made against; see [`ParamsBody`].", + "minimum": 0 + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Assigned" + } + }, + "reason": { + "type": "string" + } + } + }, "Auth": { "oneOf": [ { @@ -4883,12 +6222,37 @@ "nonce": { "type": "string" }, - "typed_data": { - "type": "object", - "description": "EIP-712 typed-data payload the wallet signs to establish a session." + "typed_data": { + "type": "object", + "description": "EIP-712 typed-data payload the wallet signs to establish a session." + } + } + }, + "CheckProposalResponse": { + "type": "object", + "required": [ + "allowed", + "complete" + ], + "properties": { + "allowed": { + "type": "boolean", + "description": "Always true: a refusal is returned as an error." + }, + "complete": { + "type": "boolean", + "description": "False when a module that opts out of dry runs was skipped." } } }, + "ClientReason": { + "type": "string", + "description": "How a denial from an instance reaches the client (RFC 0002 section 4.1).", + "enum": [ + "full", + "generic" + ] + }, "ConfigureRequest": { "type": "object", "required": [ @@ -5463,6 +6827,13 @@ } ] }, + "module_catalog_hash": { + "type": [ + "string", + "null" + ], + "description": "Hash of the policy module catalog this replica loaded; `None` when\nno catalog is configured. Replicas of one deploy report the same hash." + }, "release_sweep": { "oneOf": [ { @@ -5707,6 +7078,17 @@ "$ref": "#/components/schemas/DecodedNote" } }, + "modules": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/ModuleApproval", + "description": "The policy module configuration that approved this delta: the catalog and params version\nit was judged under and the module failures an `on_error = allow` instance let through.\nAbsent when no module ran." + } + ] + }, "new_commitment": { "type": [ "string", @@ -6565,6 +7947,17 @@ } ] }, + "modules": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/ModuleApproval", + "description": "The policy module configuration that approved this delta, for operators: absent when no\nmodule ran, never included in client API responses, and served to operators on the\ndashboard delta detail." + } + ] + }, "note_counts": { "$ref": "#/components/schemas/NoteCounts" }, @@ -6836,6 +8229,15 @@ "client_abandoned" ] }, + "Disclosure": { + "type": "string", + "description": "What an account's cosigners may learn about an instance (RFC 0002 section 2.7).", + "enum": [ + "none", + "summary", + "params" + ] + }, "EcdsaMessageFormat": { "type": "string", "description": "Message format used by an ECDSA approval.", @@ -7108,6 +8510,26 @@ "canonicalization_disabled" ] }, + "FailedOpen": { + "type": "object", + "required": [ + "module_id", + "layer", + "failure" + ], + "properties": { + "failure": { + "type": "string", + "description": "`timeout`, `error`, `invalid_decision` or `circuit_open`; the\ndetail is logged." + }, + "layer": { + "type": "string" + }, + "module_id": { + "type": "string" + } + } + }, "HistoryEntry": { "type": "object", "description": "One canonical transaction in the history feed wire shape.\n`account_id` is omitted — the authenticated query scopes it.", @@ -7167,6 +8589,26 @@ "canonical" ] }, + "LayerRemovalBody": { + "type": "object", + "required": [ + "reason" + ], + "properties": { + "expected_version": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "description": "The `account_params_version` the removal was made against; see [`ParamsBody`].", + "minimum": 0 + }, + "reason": { + "type": "string" + } + } + }, "ListProposalsResponse": { "type": "object", "required": [ @@ -7256,6 +8698,169 @@ "mainnet" ] }, + "ModuleApproval": { + "type": "object", + "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, the two params versions and the account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", + "required": [ + "catalog_hash", + "params_version", + "account_params_version", + "signed_at", + "submitter" + ], + "properties": { + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: its layers and assignment.", + "minimum": 0 + }, + "catalog_hash": { + "type": "string", + "description": "SHA-256 of the catalog file the approving replica loaded." + }, + "failed_open": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FailedOpen" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "description": "The instance params version: every instance's global params and enabled flag.", + "minimum": 0 + }, + "proposer": { + "type": "string", + "description": "The matching proposal's creator; empty when no stored proposal matched." + }, + "signed_at": { + "type": "string", + "description": "RFC 3339 time the Guardian signed, the accounting time the modules evaluated with." + }, + "submitter": { + "type": "string", + "description": "The cosigner the acknowledgment was evaluated for." + } + } + }, + "ModuleCatalogView": { + "type": "object", + "required": [ + "catalog_hash", + "params_version", + "modules", + "undeclared" + ], + "properties": { + "catalog_hash": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "minimum": 0 + }, + "undeclared": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UndeclaredInstanceView" + }, + "description": "Stored instances the catalog no longer declares: kept, never evaluated, active again if\nthe catalog brings the id back." + } + } + }, + "ModuleInstanceView": { + "type": "object", + "required": [ + "module_id", + "kind", + "scope", + "hooks", + "enabled", + "catalog_enabled", + "enabled_drift", + "operator_can_disable", + "params", + "params_drift", + "file_managed_params", + "disclosure", + "client_reason", + "dry_run", + "circuit" + ], + "properties": { + "build": { + "type": [ + "string", + "null" + ], + "description": "`name version` from `describe` at startup; absent when the startup checks failed." + }, + "catalog_enabled": { + "type": "boolean" + }, + "circuit": { + "type": "string", + "description": "The instance's circuit breaker on the replica that answered: `closed`, `open` or\n`half_open`." + }, + "client_reason": { + "$ref": "#/components/schemas/ClientReason" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "disclosure": { + "$ref": "#/components/schemas/Disclosure" + }, + "dry_run": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "enabled_drift": { + "type": "boolean" + }, + "file_managed_params": { + "type": "boolean" + }, + "hooks": { + "type": "array", + "items": { + "type": "string" + } + }, + "kind": { + "type": "string" + }, + "module_id": { + "type": "string" + }, + "operator_can_disable": { + "type": "boolean" + }, + "params": { + "type": "object" + }, + "params_drift": { + "type": "boolean" + }, + "scope": { + "type": "string" + } + } + }, "NetworkConfig": { "oneOf": [ { @@ -7912,6 +9517,48 @@ } } }, + "ParamsBody": { + "type": "object", + "required": [ + "params", + "reason" + ], + "properties": { + "expected_version": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "description": "The params version the change was made against: `params_version` for a global write,\n`account_params_version` for an account layer. Set, a write after another change is\nrefused with 409 `GUARDIAN_MODULE_PARAMS_STALE`.", + "minimum": 0 + }, + "params": { + "type": "object" + }, + "reason": { + "type": "string" + } + } + }, + "ParamsHistoryView": { + "type": "object", + "required": [ + "module_id", + "entries" + ], + "properties": { + "entries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HistoryEntry" + } + }, + "module_id": { + "type": "string" + } + } + }, "PauseAccountRequest": { "type": "object", "required": [ @@ -7950,6 +9597,61 @@ } } }, + "PoliciesResponse": { + "type": "object", + "required": [ + "account_id", + "policies" + ], + "properties": { + "account_id": { + "type": "string" + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PolicyEntry" + } + } + } + }, + "PolicyEntry": { + "type": "object", + "description": "One policy as the account's cosigners see it.", + "required": [ + "module_id", + "hooks", + "description" + ], + "properties": { + "account_layer": { + "type": [ + "object", + "null" + ], + "description": "`disclosure = \"params\"` on a `scope = all` instance: this account's layer, when set." + }, + "description": { + "type": "string" + }, + "hooks": { + "type": "array", + "items": { + "type": "string" + } + }, + "module_id": { + "type": "string" + }, + "params": { + "type": [ + "object", + "null" + ], + "description": "`disclosure = \"params\"`: the instance's global params, or the account's own params for\nan assigned instance." + } + } + }, "ProposalMetadata": { "type": "object", "description": "Operator-stated intent lifted from a matching proposal.\nThe fields that bind a proposal to a block (`bound_block_num`, and the\nlegacy `chain_anchor`) remain only in the proposal payload, to avoid\nduplicating them in delta metadata and dashboard listings.", @@ -8196,6 +9898,17 @@ } } }, + "ReasonBody": { + "type": "object", + "required": [ + "reason" + ], + "properties": { + "reason": { + "type": "string" + } + } + }, "RegisterAccountRequest": { "type": "object", "required": [ @@ -8572,6 +10285,25 @@ } } }, + "UndeclaredInstanceView": { + "type": "object", + "required": [ + "module_id", + "enabled", + "params" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "module_id": { + "type": "string" + }, + "params": { + "type": "object" + } + } + }, "UnpauseAccountRequest": { "type": "object", "properties": { diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index 0984a9550..e9b851429 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -2,13 +2,13 @@ | | | |---|---| -| **Status** | Accepted for implementation; comments still welcome and can still change it. Implementation (milestone M2a, section 7) has not started | +| **Status** | Accepted. Milestones M2a and M2c (section 7) are implemented on branch `251-modules-m2a`, not yet merged to `main`. M2b is deferred past the first release (section 7). Comments are still welcome; protocol version 1 is not frozen yet: it freezes with the first published `guardian-module-sdk` release (section 7) | | **Depends on** | [RFC 0001](./0001-server-side-transaction-execution.md) (server-side transaction execution, merged in PR #510): the execution worker is the second caller of the pipeline | | **Feature** | [#251](https://github.com/OpenZeppelin/guardian/issues/251) ("Modularization: middleware architecture and pluggable modules"); first consumer [#182](https://github.com/OpenZeppelin/guardian/issues/182) (policy evaluation). [#252](https://github.com/OpenZeppelin/guardian/issues/252) (x402 facilitator) is a later consumer: its payment-policy half (caps, allowlists, replay) fits `before_transaction_approved` and `after_transaction_committed`, its facilitator half (`/verify`, `/settle`, a flow that starts and waits) does not fit allow/deny and is future work (section 7) | | **Audience** | Operators, module authors, integrators, and anyone reviewing the Guardian trust model | -| **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; plan and tasks follow the prototype | -| **Revision** | 25 (2026-11-03): accepted for implementation on merge of PR #544; changes in Appendix C | -| **Review sought** | Comments on the design and the M2a scope remain open until M2a ships, when `guardian.module.v1` freezes (section 7) | +| **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; the plan and the M2a tasks (`tasks.md`) | +| **Revision** | 34 (2026-11-12): M2b deferred past the first release (section 7); changes in Appendix C | +| **Review sought** | Review of the M2a and M2c implementation before it merges; comments on how stateful limits should be delivered (section 9) | | **Code baseline** | `main` at `ca503704`; execution-path citations read on `254-execution-impl` at `29c722b4` (PR #510, since merged to `main` as `1100f3a4`) and kept as dated evidence. Miden pins: protocol and standards 0.17.1. Appendices B and C cite the baselines of their revisions. Prototype findings (2026-10-13 to 2026-10-15) in `speckit/features/251-guardian-modules/research.md` | --- @@ -122,12 +122,6 @@ pub trait Module: Send + Sync { async fn describe(&self, guardian: &DescribeRequest) -> Result; async fn validate_params(&self, params: &[u8]) -> Result; async fn evaluate(&self, request: &HookRequest) -> Result; - async fn notify(&self, event: &CommitEvent) -> Result<(), ModuleError> { - Ok(()) - } - async fn notify_gap(&self, gap: &Gap) -> Result<(), ModuleError> { - Ok(()) - } } pub trait ModuleFactory: Send + Sync { @@ -135,9 +129,9 @@ pub trait ModuleFactory: Send + Sync { } ``` -**Instance identity.** Every message the Guardian sends to a module carries `instance_id`, the catalog `id` of the instance it is calling (`ValidateParamsRequest`, `HookRequest`, `CommitEvent`, `Gap`). One remote service can therefore back several instances, for example a sanctions service configured once per list, and keep their state, delivery watermarks and resync handling apart: a module keys all state by (`instance_id`, `account_id`). Each instance has its own `auth` credential, and the `serve` harness binds credentials to instance ids (`.instance("sanctions-ofac", token_file)`), rejecting with `PERMISSION_DENIED` a request whose `instance_id` does not match the credential that authenticated it. An operator who prefers full isolation can still give each instance its own endpoint; the protocol does not depend on it. +**Instance identity.** Every message the Guardian sends to a module carries `instance_id`, the catalog `id` of the instance it is calling (`ValidateParamsRequest`, `HookRequest`, and with M2b `CommitEvent` and `Gap`). One remote service can therefore back several instances, for example a sanctions service configured once per list, and keep their state, delivery watermarks and resync handling apart: a module keys all state by (`instance_id`, `account_id`). Each instance has its own `auth` credential, and the `serve` harness binds credentials to instance ids (`.instance("sanctions-ofac", token)`), rejecting with `PERMISSION_DENIED` a request whose `instance_id` does not match the credential that authenticated it. An operator who prefers full isolation can still give each instance its own endpoint; the protocol does not depend on it. -The trait, the factory and all protocol types live in a separately published crate, `guardian-module-sdk`, so a kind can be written without depending on the server (section 2.5). `notify` and `notify_gap` have default no-ops, so a stateless kind implements only `describe`, `validate_params` and `evaluate`; stateful kinds override it to reset or re-seed state after a gap (section 3.3). Besides the trait, the SDK provides what the prototype showed every module needs: `Decision::allow` and `Decision::deny`, `ParamsVerdict::ok` and `ParamsVerdict::invalid`, reason-code validation, typed accessors over the generated messages (for example the fungible amount of an `Asset`), and `ModuleInstanceConfig`, the configuration a factory receives, whose bearer token is a secret type, redacted from debug output and zeroized when dropped. The `GrpcModule` implementation (and `HttpModule`, when that kind ships) calls the `NotifyGap` RPC, and the `serve` harness routes `NotifyGap` to `notify_gap`, so in-process and remote modules see gaps the same way. +The trait, the factory and all protocol types live in a separately published crate, `guardian-module-sdk`, so a kind can be written without depending on the server (section 2.5). A kind implements `describe`, `validate_params` and `evaluate`. The stateful methods of section 3.3 (`notify`, `notify_gap`) join the trait with M2b, with default bodies, so existing kinds keep compiling. Besides the trait, the SDK provides what the prototype showed every module needs: `Decision::allow` and `Decision::deny`, `ParamsVerdict::ok` and `ParamsVerdict::invalid`, reason-code validation, typed accessors over the generated messages (for example the fungible amount of an `Asset`), and `ModuleInstanceConfig`, the configuration a factory receives, whose bearer token is a secret type, redacted from debug output and zeroized when dropped. With M2b, the `GrpcModule` implementation (and `HttpModule`, when that kind ships) will call the `NotifyGap` RPC and the `serve` harness route it to `notify_gap`, so in-process and remote modules see gaps the same way. First-party kinds, registered by the official binary (through `ServerBuilder::from_env()` once M2c ships, section 7) and present in the official image: @@ -145,7 +139,7 @@ First-party kinds, registered by the official binary (through `ServerBuilder::fr |---|---|---|---| | `grpc` | Remote | `endpoint = "grpc://host:port"` (TLS), `auth` | Calls a service implementing `guardian.module.v1.GuardianModule` | | `http` | Remote | `endpoint = "https://host[:port]"`, `auth` | Not in M2; added if operators ask for it (section 7). Same messages in the proto3 JSON mapping at `GET /v1/describe`, `POST /v1/validate-params`, `POST /v1/evaluate`, `POST /v1/notify`, `POST /v1/notify-gap`. HTTP 404 or 501 from `/v1/notify-gap` is treated like gRPC `UNIMPLEMENTED` (section 3.3) | -| `basic-policy` | In process | none | Reference policy: recipient allowlist and denylist, asset allowlist, per-transaction amount cap, signer allowlist or denylist, account code allowlist. Stateless: supports `before_transaction_approved`, `before_proposal_created` and `before_account_registered` (section 2.3). Rules and reason codes in section 3.1, "`basic-policy` rules" | +| `spending-limit`, `recipient-policy`, `signer-policy`, `code-policy` | In process | none | Reference policies, one concern each: a per-transaction amount cap per asset and an asset allowlist; a recipient allowlist or denylist; a signer allowlist or denylist; an account code allowlist. Stateless. The first two support `before_proposal_created` and `before_transaction_approved`, the other two also `before_account_registered` (section 2.3). Params, rules and reason codes in section 3.1, "Built-in policies" | Operator-registered kinds run in process (section 2.5). The proto in section 3 is the single schema for both remote kinds, so there is one schema to version. A conformance suite in `guardian-module-sdk` runs the same cases against in-process and gRPC modules (and HTTP modules once that kind ships) and asserts identical decisions. Deferring `http` keeps the first suite free of the proto3 JSON mapping rules (base64 `bytes`, decimal-string `int64`, RFC 3339 timestamps); `grpc://` endpoints already meet R3's "registered by URL". @@ -166,12 +160,12 @@ Each catalog entry: | `endpoint` | Remote kinds only: `grpc://…`, always TLS (`https://…` for `http` once it ships). Plain text needs the explicit `grpc+insecure://…` scheme and a loopback host, and is refused in the prod stage (section 5.2) | | `scope` | `all`, `default` or `assigned` (see scopes below) | | `hooks` | Subset of the hooks in section 2.3 | -| `timeout_ms` | Required; from 1 to `GUARDIAN_MODULE_TIMEOUT_MAX_MS` (default 1000) | +| `timeout_ms` | Required; from 1 to 1000 | | `on_error` | `deny` (default) or `allow` (section 4) | -| `auth` | Remote kinds only, mandatory in the prod stage: secret reference for the bearer token (section 5.2) | -| `tls` | Remote kinds only, optional: `ca_file` (PEM bundle for a private CA; the system roots otherwise) and `client_cert` and `client_key` secret references for mTLS (section 5.2) | -| `params` | Initial global parameters as a JSON object, written to the metadata store the first time the instance id is seen and managed through the operator API afterwards (see layered parameters below) (TOML tables in the catalog are converted to JSON). Modules receive params as UTF-8 JSON bytes in RFC 8785 canonical form (JCS). The decoded bytes are identical on every transport: in process and over gRPC they arrive as raw bytes, while over `http` (once it ships) the proto3 JSON mapping carries them as a base64 string that decodes to the same bytes (likewise `int64` fields arrive as decimal strings and `Timestamp` fields as RFC 3339 strings, per the standard mapping). See "Parameters and secrets" below | -| `require_fresh_state_ms` | Optional maximum notify lag in milliseconds (section 3.3) | +| `auth` | Remote kinds only, mandatory in the prod stage: `token_secret`, the secret name of the bearer token (section 5.2) | +| `tls` | Remote kinds only, optional: `ca_file` (PEM bundle for a private CA, relative to the catalog's directory; the system roots otherwise) and `client_cert_secret` and `client_key_secret`, secret names, for mTLS (section 5.2) | +| `params` | Initial global parameters as a JSON object, written to the metadata store the first time the instance id is seen and managed through the operator API afterwards (see layered parameters below) (TOML tables in the catalog are converted to JSON). Modules receive params as UTF-8 JSON bytes, compact and with object keys sorted (not full RFC 8785 canonicalization: numbers and strings are as `serde_json` writes them). The decoded bytes are identical on every transport: in process and over gRPC they arrive as raw bytes, while over `http` (once it ships) the proto3 JSON mapping carries them as a base64 string that decodes to the same bytes (likewise `int64` fields arrive as decimal strings and `Timestamp` fields as RFC 3339 strings, per the standard mapping). See "Parameters and secrets" below | +| `require_fresh_state_ms` | M2b, not accepted yet (a catalog that sets it does not start): optional maximum notify lag in milliseconds (section 3.3) | | `enabled` | Default `true`. A one-time seed, read only the first time an instance id is seen; afterwards the runtime flag in the metadata store governs and later edits of this field have no effect (see runtime changes below) | | `disclosure`, `description`, `client_reason`, `dry_run` | What the account's cosigners may learn about the instance: the policy summary, generic or full denials, and the dry-run check (section 2.7). Defaults disclose nothing beyond today's denials | | `operator_can_disable` | Default `false`. When `true`, the operator API may disable this instance at runtime. Enabling is always allowed (see runtime changes below) | @@ -179,27 +173,29 @@ Each catalog entry: ```toml [[module]] id = "spend-cap" -kind = "basic-policy" +kind = "spending-limit" scope = "default" hooks = ["before_transaction_approved"] timeout_ms = 50 on_error = "deny" -params = { max_amount_per_tx = { "0x5e0f...c3" = "1000000" } } +params = { max_per_transaction = { "0x5e0f...c3" = "1000000" } } [[module]] id = "risk-vendor" kind = "grpc" endpoint = "grpc://risk:7443" scope = "assigned" -hooks = ["before_transaction_approved", "after_transaction_committed"] +hooks = ["before_transaction_approved"] timeout_ms = 300 on_error = "allow" auth = { token_secret = "guardian/modules/risk-vendor-token" } ``` -**Parameters and secrets.** Params are a JSON object. A value of the form `{"$secret": ""}` is a secret reference, resolved by the Guardian through its secrets backend. `$secret` is a reserved key at any depth: the Guardian scans params recursively, so a reference nested inside another object is found and treated exactly like a top-level one, and no module param may use `$secret` as an ordinary key. Secret references are allowed only in catalog entries of in-process kinds, and are resolved when the instance is created. They are rejected in catalog entries of remote kinds (a remote module holds its own credentials) and in per-account params written through the operator API (otherwise a session could read arbitrary secrets through a module). Resolved secret values are never placed in a `HookRequest`, so they never reach a remote module. An in-process instance whose catalog params contain references receives, in its own `HookRequest.params`, the unresolved form with the references intact; it holds the resolved values from its factory, which received them when the instance was created. The `serve` harness and the conformance suite follow the same rule and never substitute. +The example uses only what this release accepts. A stateful module (M2b, section 7) would also subscribe to `after_transaction_committed` and may set `require_fresh_state_ms`; a catalog naming either does not start until M2b ships. + +**Parameters and secrets.** Params are a JSON object. A value of the form `{"$secret": ""}` is a secret reference, resolved by the Guardian through its secrets backend (`GUARDIAN_MODULE_SECRET_PROVIDER`: AWS Secrets Manager by default in the prod stage, owner-only files below `GUARDIAN_MODULE_SECRET_DIR` otherwise). `$secret` is a reserved key at any depth: the Guardian scans params recursively, so a reference nested inside another object is found and treated exactly like a top-level one, and no module param may use `$secret` as an ordinary key. Secret references are allowed only in catalog entries of in-process kinds, and are resolved when the instance is created. They are rejected in catalog entries of remote kinds (a remote module holds its own credentials) and in per-account params written through the operator API (otherwise a session could read arbitrary secrets through a module). Resolved secret values are never placed in a `HookRequest`, so they never reach a remote module. An in-process instance whose catalog params contain references receives, in its own `HookRequest.params`, the unresolved form with the references intact; it holds the resolved values from its factory, which received them when the instance was created. The `serve` harness and the conformance suite follow the same rule and never substitute. -The catalog is loaded in `ServerBuilder::build()`, after every `with_module_kind` call, so custom kinds are registered before any instance names them. `build()` creates every instance through its kind's factory, calls `describe` on it and checks that it supports the hooks it is configured for and speaks a supported `protocol_version`, then calls `validate_params` on the instance's stored global params (the catalog's `params` on first start), in the same unresolved form the module later receives in `HookRequest.params` (secret references intact), so a mistyped value in the catalog fails at startup rather than on the first transaction. In the prod stage a mismatch or an unreachable enabled module stops startup, mirroring `reject_filesystem_in_prod`; a disabled instance that fails these checks is logged and stays disabled, and enabling it runs the same checks first. Failing to create the instance at all, because its kind is not registered or its factory rejects the configuration (for example a malformed endpoint), is one of these failures: it stops startup for an enabled instance and leaves a disabled one disabled, so an operator can stage an instance for a module or a build that is not deployed yet. +The catalog is loaded in `ServerBuilder::build()`, after every `with_module_kind` call, so custom kinds are registered before any instance names them. `build()` creates every instance through its kind's factory, calls `describe` on it and checks that it supports the hooks it is configured for and speaks a supported `protocol_version`, then calls `validate_params` on the instance's stored global params (the catalog's `params` on first start), in the same unresolved form the module later receives in `HookRequest.params` (secret references intact), so a mistyped value in the catalog fails at startup rather than on the first transaction. A mismatch stops startup, and so does an unreachable enabled module that is new to this Guardian (no stored instance row), so a wrong endpoint in a new catalog entry is found when it is deployed. An enabled instance that has started here before and whose module does not answer does not stop startup: it starts unavailable, with its breaker held open so its accounts follow `on_error`, and each health probe runs the full startup checks (the params that apply included) until they pass. A third party's outage therefore cannot keep the Guardian from restarting or scaling out, while nothing is approved that the module would have judged. A module that answers but refuses the call, the params or the protocol version still stops startup; a disabled instance that fails these checks is logged and stays disabled, and enabling it runs the same checks first. Failing to create the instance at all, because its kind is not registered or its factory rejects the configuration (for example a malformed endpoint), is one of these failures: it stops startup for an enabled instance and leaves a disabled one disabled, so an operator can stage an instance for a module or a build that is not deployed yet. **Scopes** decide which accounts a module applies to without the operator visiting every account: @@ -223,7 +219,7 @@ Two rules keep `default` predictable: ```json { "modules": [ - { "module_id": "spend-cap", "params": { "max_amount_per_tx": { "0x5e0f...c3": "500000" } } } + { "module_id": "spend-cap", "params": { "max_per_transaction": { "0x5e0f...c3": "500000" } } } ], "reason": "Raise treasury cap, ticket OP-42" } @@ -235,30 +231,30 @@ Two rules keep `default` predictable: ```json { "modules": [ - { "module_id": "compliance-caps", "scope": "all", "enabled": true, "global_params": { "max_amount_per_tx": { "0x5e0f...c3": "10000" } }, "account_layer": { "max_amount_per_tx": { "0x5e0f...c3": "2000" } } }, - { "module_id": "spend-cap", "scope": "default", "enabled": true, "params": { "max_amount_per_tx": { "0x5e0f...c3": "500000" } } }, + { "module_id": "compliance-caps", "scope": "all", "enabled": true, "global_params": { "max_per_transaction": { "0x5e0f...c3": "10000" } }, "account_layer": { "max_per_transaction": { "0x5e0f...c3": "2000" } } }, + { "module_id": "spend-cap", "scope": "default", "enabled": true, "params": { "max_per_transaction": { "0x5e0f...c3": "500000" } } }, { "module_id": "legacy-risk", "scope": "assigned", "orphaned": true, "params": { "threshold": 70 } } ] } ``` An `all` instance shows its global params and the account's layer, if any; a `default` or `assigned` instance shows the account's own params. Secret references are shown as references, never resolved. -- `GET /dashboard/modules` (permission `dashboard:read`) lists every declared instance and every stored instance flag the catalog no longer declares, with the catalog's seed value next to the stored flag, so drift between the file and the runtime state is visible without reading startup logs (seed rules below), together with the current params version and the instance's circuit state on the replica that answered (section 4.4). `enabled_drift` is true when the catalog's `enabled` differs from the stored flag, `params_drift` when the catalog's `params` differ from the params it seeded: +- `GET /dashboard/modules` (permission `dashboard:read`) lists every declared instance and every stored instance flag the catalog no longer declares, with the catalog's seed value next to the stored flag, so drift between the file and the runtime state is visible without reading startup logs (seed rules below), together with the current instance params version and the instance's circuit state on the replica that answered (section 4.4). `enabled_drift` is true when the catalog's `enabled` differs from the stored flag, `params_drift` when the catalog's `params` differ from the params it seeded: ```json { "catalog_hash": "0x3a…", "params_version": 7, "modules": [ - { "module_id": "risk-vendor", "kind": "grpc", "scope": "assigned", "hooks": ["before_transaction_approved", "after_transaction_committed"], "catalog_enabled": true, "enabled": false, "enabled_drift": true, "params_drift": false, "file_managed_params": false, "operator_can_disable": true, "build": "risk-vendor 1.4.2", "circuit": "closed" }, + { "module_id": "risk-vendor", "kind": "grpc", "scope": "assigned", "hooks": ["before_transaction_approved"], "catalog_enabled": true, "enabled": false, "enabled_drift": true, "params_drift": false, "file_managed_params": false, "operator_can_disable": true, "build": "risk-vendor 1.4.2", "circuit": "closed" }, { "module_id": "legacy-risk", "declared": false, "enabled": true } ] } ``` -- `PUT /dashboard/modules/{module_id}/params` (permission `policies:write_global`) takes `{ "params": { ... }, "reason": "" }` and replaces the instance's global params. For an `all` instance the change applies to every account at once; for a `default` or `assigned` instance it is the value copied into later assignments. +- `PUT /dashboard/modules/{module_id}/params` (permission `policies:write_global`) takes `{ "params": { ... }, "reason": "" }` and replaces the instance's global params. For an `all` instance the change applies to every account at once; for a `default` or `assigned` instance it is the value copied into later assignments. This write and the account writes below (layer set or removed, assignment) also take an optional `expected_version`: the instance `params_version` the operator read for a global write, the account's `account_params_version` for the others. It is compared inside the write's lock, and a write made after another change to the same rows is refused with 409 `GUARDIAN_MODULE_PARAMS_STALE` and writes nothing, so two operators editing from the same read cannot silently drop each other's change. - `PUT /dashboard/accounts/{account_id}/modules/{module_id}/params` (permission `policies:write`) takes `{ "params": { ... }, "reason": "" }` and sets the account's layer on an `all` instance; `DELETE` on the same path, with a reason, removes it. For `default` and `assigned` instances the account's params are set through the assignment `PUT` above. -- `GET /dashboard/modules/{module_id}/params/history` (permission `dashboard:read`) lists the stored params changes of the instance, global and per account, with operator, reason and time, newest first and paginated by version (`?before=&limit=`). +- `GET /dashboard/modules/{module_id}/params/history` (permission `dashboard:read`) lists the stored params changes of the instance, global and per account, with operator, reason and time, newest first and paginated by entry id (`?before=&limit=`), since `version` counts per instance or per account and is not unique across the history. - `POST /dashboard/modules/{module_id}/enable` and `/disable` take `{ "reason": "" }`. - `POST /dashboard/modules/{module_id}/resync` takes `{ "reason": "", "account_ids": ["0x..."] }` (omit `account_ids` for every affected account) and starts the resync: it moves delivery past the dropped history and sends `NotifyGap`, and the pair stays refused until the module acknowledges the Gap (section 3.3). - **Refusals.** Missing permissions return the existing `GUARDIAN_INSUFFICIENT_OPERATOR_PERMISSION` (403, `meta.missing_permissions`, `crates/server/src/error.rs:106,209,312`) **[READ]**. A missing reason, an invalid or budget-exceeding assignment, an entry naming an `all` instance and secret references in params return `invalid_input` (400). An unknown module id returns `GUARDIAN_MODULE_NOT_FOUND` (404) and an unknown account `account_not_found` (404). Disabling an instance without `operator_can_disable` returns `GUARDIAN_MODULE_NOT_DISABLEABLE` (409). Enabling an instance that fails its startup checks returns `GUARDIAN_MODULE_UNAVAILABLE` (503). @@ -274,25 +270,25 @@ Two rules keep `default` predictable: - **Exceptions that loosen use `default`.** A rule some accounts must be allowed to relax, such as a treasury account with a higher cap, belongs in a `default` instance: copied to new accounts, and replaceable or removable per account through the assignment. - **Denials name the layer.** `GUARDIAN_MODULE_DENIED` carries `meta.layer` (`global` or `account`), so an operator can tell which list blocked a transaction. - **History and version.** Every params write appends to a history with the previous and new params, the operator identity and the reason, so a mistake can be found and reverted. The params store has a version that increases with every write; each signed delta records it next to `module_catalog_hash`, so "which configuration approved this transaction" stays exact. -- **Secrets stay in the file.** Params set through the API cannot contain `$secret` references. An instance whose catalog params contain references keeps its global params file-managed: the API refuses to change them, and its account layers carry no references. +- **Secrets stay in the file.** Params set through the API cannot contain `$secret` references. An instance whose catalog params contain references keeps its global params file-managed: the API refuses to change them, and its account layers carry no references. Its stored seed records the catalog params as written (references, never resolved values), so a later start can tell the instance was file-managed: when the references are removed, the new catalog params apply and are stored in place of the empty placeholder, rather than the module running with `{}`; when references are added to an operator-managed instance, the catalog params apply and a warning says the stored operator params no longer do. ```toml [[module]] id = "blocklist" -kind = "basic-policy" +kind = "recipient-policy" scope = "all" hooks = ["before_proposal_created", "before_transaction_approved"] timeout_ms = 50 on_error = "deny" -params = { recipient_denylist = ["0xaaa...", "0xbbb..."] } +params = { denylist = ["0xaaa...", "0xbbb..."] } ``` ```http PUT /dashboard/modules/blocklist/params -{ "params": { "recipient_denylist": ["0xaaa...", "0xbbb...", "0xddd..."] }, "reason": "Add 0xddd, ticket OP-90" } +{ "params": { "denylist": ["0xaaa...", "0xbbb...", "0xddd..."] }, "reason": "Add 0xddd, ticket OP-90" } PUT /dashboard/accounts/0x7bfb...a1/modules/blocklist/params -{ "params": { "recipient_denylist": ["0xccc..."] }, "reason": "Customer block, ticket OP-91" } +{ "params": { "denylist": ["0xccc..."] }, "reason": "Customer block, ticket OP-91" } ``` That account is then checked against `0xaaa`, `0xbbb` and `0xddd` by the global layer and against `0xccc` by its own; every other account only against the global list. @@ -303,10 +299,11 @@ That account is then checked against `0xaaa`, `0xbbb` and `0xddd` by the global |---|---|---| | `module_instances` | Runtime state of each instance: the `enabled` flag, the global params, and the params the catalog seeded them with (for drift) | `module_id` | | `module_account_params` | Per-account params: account layers on `all` instances and assignments of `default` and `assigned` instances, told apart by `kind` (`layer` or `assignment`), with `position` for the assignment order | `(account_id, module_id)`, with an index on `module_id` | -| `module_params_history` | Append-only record of every params change and every enable or disable (recorded as `{"enabled": previous}` to `{"enabled": new}`): module, account (absent for global), previous and new value, operator, reason, time, and the params version of the write that made it | Row id; `version` is shared by the rows of one write | -| `module_state_version` | One row: the params version | None (single row) | +| `module_params_history` | Append-only record of every params change and every enable or disable (recorded as `{"enabled": previous}` to `{"enabled": new}`): module, account (absent for global), previous and new value, operator, reason, time, and the version of the write that made it: the instance params version for a global entry, the account's params version for an account entry | Row id, which orders the history and pages it; `version` is shared by the rows of one write | +| `module_state_version` | One row: the instance params version | None (single row) | +| `module_account_version` | One row per account a write has touched: the account's params version | `account_id` | -A params write takes the `module_state_version` row lock, increments it, updates its row and appends the history rows, all in one transaction. An evaluation reads the version, the global rows and the account's rows, then the version again, and retries if it moved: since every write moves it, a request never combines a global rule and an account layer that were never committed together. A write derived from an earlier read (a module migrating stored params, section 3.5) is conditional on the stored value still being the one read, so it never overwrites a newer operator write. Writes therefore serialize and the version moves in commit order, which a sequence would not give: two writes could draw versions 10 and 11, 11 could commit first, and a replica that cached at 11 would never see 10. Operator writes are rare, so serializing them costs nothing that matters. Evaluation reads the account's rows with one indexed query, only when modules are configured; global params can be cached per replica and refreshed when the latest version changes. The filesystem backend keeps the same tables in one file, `module_state.json` in `/modules` (directory overridable with `GUARDIAN_MODULES_STATE`), replaced atomically (written, synced, renamed), so a write and its history land together; deltas gain the `module_params_version` column next to `module_catalog_hash`. +There are two kinds of params version, so that a write to one account touches nothing shared. A write to an instance (its global params or its enabled flag) takes the `module_state_version` row lock, increments it, updates its row and appends the history rows, all in one transaction. A write to an account's layers or assignment, including the default copy at registration, does the same with that account's `module_account_version` row instead. Writes to one instance version or one account therefore serialize and each version moves in commit order, which a sequence would not give: two writes could draw versions 10 and 11, 11 could commit first, and a replica that cached at 11 would never see 10. Writes to different accounts never wait for each other or for instance writes, and since replicas cache only the instance rows, keyed on the instance params version, an account write invalidates no cache; the account's rows are read on every evaluation anyway. An evaluation reads both versions, the instance rows (unless its cache holds that instance version) and the account's rows in one statement, so a request never combines a global rule and an account layer that were never committed together. A write derived from an earlier read (a module migrating stored params, section 3.5) is conditional on the stored value still being the one read, so it never overwrites a newer operator write. The filesystem backend keeps the same tables in one file, `module_state.json` in `/modules` (directory overridable with `GUARDIAN_MODULES_STATE`), replaced atomically (written, synced, renamed), so a write and its history land together. Each signed delta records the catalog hash and both versions in its evaluation trace (below). | Operator API can | Operator API cannot | |---|---| @@ -325,20 +322,21 @@ This revision specifies the operator API only; no operator dashboard page is pla **Runtime changes without a restart.** The catalog file is read only at startup. Hot reload was considered and rejected (section 8): on ECS, the production target, configuration reaches tasks through the task definition and image, so there is no file to change without a deploy; file watching is unreliable across network and container mounts; and with several replicas a reload reaches one process, so for a newly added `all` module the other replicas keep signing without it. The needs behind a reload are met by state in the metadata store instead, which every replica reads, so a change applies to all replicas at once: - **Global params, account layers and per-account assignment** (above). -- **Seed rule for `enabled`.** The catalog's `enabled` value is written to the metadata store only the first time an instance id is seen. After that the stored flag is the only switch: a redeploy that changes `enabled` in the file changes nothing, and the server logs a warning at startup when the file and the stored flag differ, lists the instance with `"enabled_drift": true` in `GET /dashboard/modules`, and exports `guardian_module_enabled_drift{module}`. Removing an instance from the catalog stops it but keeps its stored flag; adding the same id back resumes with that stored flag, not the file's value. The file is therefore not the switch for an existing instance; the operator API is. -- **Runtime enable and disable of declared instances.** `POST /dashboard/modules/{module_id}/enable` (permission `policies:write`) and `/disable` (`policies:write` or `modules:disable`), each with a required reason and an audit record, switch evaluation on or off for every account. The two directions carry different risk. Enabling only tightens policy and is always allowed, so an operator can declare an instance with `enabled = false` and switch it on later without a restart. Disabling loosens policy: an API that could disable any module would let a stolen operator session switch off sanctions screening for every account, which undoes invariant 4. It is therefore allowed only for instances with `operator_can_disable = true`. An instance declared with `enabled = false` and `operator_can_disable = false` is deliberately one-way: a staged rollout that an operator can switch on once and cannot switch off from a session; compliance instances leave the flag off, while advisory modules such as a fail-open risk scorer can turn it on as an emergency stop for a faulty module. The flag lives in `module_instances`, and the pipeline reads it per evaluation through the per-replica cache, so a switch reaches every replica on its next evaluation; it is also the flag that decides at startup whether an instance failing its checks stops the server. `guardian_module_disabled{module}` is exported for alarms. A disabled instance is skipped by `evaluate` but keeps receiving `notify`, so its state is current when it is enabled. +- **Seed rule for `enabled`.** The catalog's `enabled` value is written to the metadata store only the first time an instance id is seen. After that the stored flag is the switch, with one exception that only tightens policy: an instance the catalog declares `enabled = true` and not `operator_can_disable` is enabled at startup when it is stored as disabled, with a history entry by `catalog`, since no operator may hold such an instance off under that catalog (the disable predates it). Otherwise a redeploy that changes `enabled` in the file changes nothing, and the server logs a warning at startup when the file and the stored flag differ, lists the instance with `"enabled_drift": true` in `GET /dashboard/modules`, and exports `guardian_module_config_drift{module}`. Removing an instance from the catalog stops it but keeps its stored flag; adding the same id back resumes with that stored flag, not the file's value. The file is therefore not the switch for an existing instance; the operator API is. +- **Runtime enable and disable of declared instances.** `POST /dashboard/modules/{module_id}/enable` (permission `policies:write`) and `/disable` (`policies:write` or `modules:disable`), each with a required reason and an audit record, switch evaluation on or off for every account. The two directions carry different risk. Enabling only tightens policy and is always allowed, so an operator can declare an instance with `enabled = false` and switch it on later without a restart. Disabling loosens policy: an API that could disable any module would let a stolen operator session switch off sanctions screening for every account, which undoes invariant 4. It is therefore allowed only for instances with `operator_can_disable = true`. An instance declared with `enabled = false` and `operator_can_disable = false` is deliberately one-way: a staged rollout that an operator can switch on once and cannot switch off from a session; compliance instances leave the flag off, while advisory modules such as a fail-open risk scorer can turn it on as an emergency stop for a faulty module. The flag lives in `module_instances`, and the pipeline reads it per evaluation through the per-replica cache, so a switch reaches every replica on its next evaluation; it is also the flag that decides at startup whether an instance failing its checks stops the server. `guardian_module_enabled{module}` (0 when disabled) is exported for alarms. A disabled instance is skipped by `evaluate` but keeps receiving `notify`, so its state is current when it is enabled. -Only adding an instance, removing one, or changing its kind, endpoint, auth, hooks, timeout or `on_error` needs a deploy, and deploy review is the bar wanted for those changes. A rolling deploy still leaves replicas on different catalogs for its duration, so each replica exports the hash of the catalog it loaded (`guardian_module_catalog_info{hash}` and in `/dashboard/info`) and logs each instance's module build (`name version` from `describe`) at startup, also shown in `GET /dashboard/modules`. The catalog file itself lives in the deploy repository, where its hash finds it. +Only adding an instance, removing one, or changing its kind, endpoint, auth, hooks, timeout or `on_error` needs a deploy, and deploy review is the bar wanted for those changes. A rolling deploy still leaves replicas on different catalogs for its duration, so each replica exports the hash of the catalog it loaded (`guardian_module_catalog_info{catalog_hash}` and in `/dashboard/info`) and logs each instance's module build (`name version` from `describe`) at startup, also shown in `GET /dashboard/modules`. The catalog file itself lives in the deploy repository, where its hash finds it. **Evaluation trace.** Every delta the Guardian signs after modules ran records which configuration approved it, shown in the dashboard delta detail and not exposed through the client API: | Field | Holds | |---|---| | `catalog_hash` | SHA-256 of the catalog file the approving replica loaded | -| `params_version` | The params version the evaluation read; the history replayed to it gives every global param, layer, assignment and enabled flag | -| `failed_open` | Each evaluation that failed and was let through by `on_error = allow`: module, layer and failure kind (`timeout`, `error`, `invalid_decision`, `request_unavailable`); omitted when empty, the detail goes to the log | +| `params_version` | The instance params version the evaluation read; the global history entries replayed to it give every global param and enabled flag | +| `account_params_version` | The account's params version the evaluation read; the account's history entries replayed to it give its layers and assignment | +| `failed_open` | Each evaluation that failed and was let through by `on_error = allow`: module, layer and failure kind (`timeout`, `error`, `invalid_decision`, `circuit_open`); omitted when empty, the detail goes to the log | -Allowed evaluations are not listed: the catalog, the params version and the account determine which modules ran. Denials create no delta. Each is logged with `request_id`, account, hook, module, layer, `reason_code`, the module's `message`, the catalog hash and the params version, so "why was this account refused" is answered from the logs; M2a has no API for denials, and a durable decision log is future work (section 7). A durable record of module builds per configuration, a hash of the request and the inputs not stored elsewhere (accounting time, proposer) are added with the replay tool that would consume them. +Allowed evaluations are not listed: the catalog, the two params versions and the account determine which modules ran. Proposal creation and registration sign no delta, so a failure let through there is written to the audit log instead, as a `modules.failed_open` event with the hook, submitter, catalog hash, both params versions, the failures and, for a proposal, its id. Denials create no delta. Each is logged with `request_id`, account, hook, module, layer, `reason_code`, the module's `message`, the catalog hash and both params versions, so "why was this account refused" is answered from the logs; M2a has no API for denials, and a durable decision log is future work (section 7). A durable record of module builds per configuration, a hash of the request and the inputs not stored elsewhere (accounting time, proposer) are added with the replay tool that would consume them. **Order:** `scope = all` modules in catalog order, each with its global layer first and the account's layer, if any, right after it; then the account's stored assignment in its stored order. Copied `default` modules are stored first, in catalog order, and the operator may reorder them afterwards. Evaluation stops at the first deny. `all` modules always run before the account's own modules, so when an `all` module denies, `meta.module` names it and any account-level module that would also have denied is never called. Operators debugging per-account policy should check the `all` modules first. @@ -350,13 +348,13 @@ Account self-service configuration is out of scope for this revision (section 7) |---|---|---| | `before_transaction_approved` | Gate | Inside the single function that produces the Guardian ack. On `main` the only production ack is `push_delta` before `state.ack.ack_delta` (`crates/server/src/services/push_delta.rs:181`) **[READ]**. PR #510 (`254-execution-impl`) adds a second caller, the execution worker, and routes both through `ack_delta_internal::acknowledge_delta` (`push_delta.rs:145`, `execute_proposal/worker.rs:389` at `29c722b4`) **[READ]**; the pipeline runs inside that shared function, so no caller can ack around it. The pause and release check runs earlier (`push_delta.rs:35`, before the ack at `:181`) **[READ]**, so a paused or released account is refused before any module sees its transaction. A denial on the execution path does not reach a `push_delta` caller; it ends the execution with a typed abort the multisig SDKs read (section 4.1) | | `before_proposal_created` | Gate (filter) | `push_delta_proposal` (`crates/server/src/services/push_delta_proposal.rs:47`) after queue admission, the pending-proposal limit (`:173-186`), tail reconstruction (`:188`), `verify_delta` (`:210`) and the proposer signature check (`:228-251`), and before the proposal is stored (`submit_delta_proposal`, `:275`) **[READ]**. The request has the same shape as at the ack: `before` is the tail the proposal is pinned to, `after` comes from applying the delta to that tail, as `push_delta` does (`push_delta.rs:143`) **[READ]**, done only when a module will be called, and `pending` is built as for the ack (section 3.4). `accounting_time` is the evaluation time and is not stored, since nothing is signed. A deny refuses the proposal with `GUARDIAN_MODULE_DENIED` and nothing is stored, so it takes no proposal slot. See "Proposal filtering" below | -| `before_account_registered` | Gate | `configure_account` (`crates/server/src/services/configure_account.rs:32`) after the credential, canonical signer set and Guardian commitment checks, and before the account is claimed, its replay timestamp consumed or anything stored. New and existing accounts run different module sets; see "Registration" below | -| `after_transaction_committed` | Notify | Outbox row written in the same storage write that makes the delta committed. In candidate mode that is `promote_candidate` on the Postgres backend (`crates/server/src/storage/postgres.rs:1786`) **[READ]**; the filesystem backend does not support this hook (section 3.3). With canonicalization disabled the delta commits at push time (`DeltaCommitStrategy::Optimistic`, `crates/server/src/services/delta_commit.rs:18-31`) **[READ]**, and the row is written in that commit | +| `before_account_registered` | Gate | `configure_account` (`crates/server/src/services/configure_account.rs:32`) after the credential, canonical signer set and Guardian commitment checks, and before the account is claimed, its replay timestamp consumed or anything stored. One exception: when the account is registered and the requesting key is not one of its stored signers, the replay timestamp is consumed and the submitted state vouched for (on chain, or as a first state at nonce 0) before the hook runs, so nobody outside an account can submit a made-up state for it and read its module verdicts or hand its modules forged states. New and existing accounts run different module sets; see "Registration" below | +| `after_transaction_committed` (M2b, not in this release) | Notify | Outbox row written in the same storage write that makes the delta committed. In candidate mode that is `promote_candidate` on the Postgres backend (`crates/server/src/storage/postgres.rs:1786`) **[READ]**; the filesystem backend does not support this hook (section 3.3). With canonicalization disabled the delta commits at push time (`DeltaCommitStrategy::Optimistic`, `crates/server/src/services/delta_commit.rs:18-31`) **[READ]**, and the row is written in that commit | **Registration.** `configure_account` serves first configurations and existing accounts alike, including re-onboarding after a release. Since #558 a first configuration claims the account by creating its metadata row (`configure_account.rs:198-220`), then consumes the request's replay timestamp (`:237`), then stores the initial state (`:261`); a claim whose state was never stored is detected on the next request as an unfinished claim (`:78-96`) and treated as a first configuration again (`:98`) **[READ]**. The hook follows the same three cases: -- **New account** (`existing.is_none()`): there is no assignment yet, so `scope = all` and `scope = default` instances run, each only if it declares this hook, `default` ones with their current global params because they are about to apply to the account. `before` is absent. On success the `default` instances are copied into the account's assignment with exactly the params the evaluation used, read in the same consistent snapshot (section 2.2, "Storage"); a global params write that lands between the evaluation and the claim applies to later accounts only. On Postgres the copy is written in the same transaction as the claim. On the filesystem backend, which is development only, the claim and the module state are separate files, so the copy is written first, as one atomic replace of the module state, replacing any copy an earlier attempt left for the same account id: until the claim exists no operator can have edited it (the operator API answers `account_not_found`), so the copy that wins is the one from the evaluation of the request that claims the account, or, if two first configurations race, from the last one to write before the claim. A copy left by an attempt that never claims stays in the module state, unused, since nothing evaluates an account that does not exist. Because `default` instances run here, a down fail-closed `default` instance blocks new registrations. -- **Unfinished claim** (`existing.is_some()` and no stored state): the claim normally holds the copied defaults, so `scope = all` instances and the stored assignment run, with `before` absent. The copy is repeated only if the account has no assignment history at all, which happens only when a crash fell between the claim and the copy on a backend where they are separate writes; an assignment an operator later emptied keeps its history and is not refilled. +- **New account** (`existing.is_none()`): there is no assignment yet, so `scope = all` and `scope = default` instances run, each only if it declares this hook, `default` ones with their current global params because they are about to apply to the account. `before` is absent. Once the request has claimed the account, every `default` instance is copied into the account's assignment with exactly the params the evaluation used (its global params), a disabled one included: disabling is an incident switch, not a decision that new accounts go without the instance, so it runs for them once re-enabled, read in the same consistent snapshot (section 2.2, "Storage"); a global params write that lands between the evaluation and the copy applies to later accounts only. The copy is written right after the claim and before the replay timestamp is consumed, and only if the account has no assignment and no assignment history, under the module state lock, so an operator write that reached the new account first wins and is never overwritten. A request that loses the claim copies nothing. A crash between the claim and the copy leaves an unfinished claim with no assignment history, whose retry repeats the copy (below), so the claim and the copy need not share one transaction and the rule is the same on both backends. Because `default` instances run here, a down fail-closed `default` instance blocks new registrations. +- **Unfinished claim** (`existing.is_some()` and no stored state): the claim normally holds the copied defaults, so `scope = all` instances and the stored assignment run, with `before` absent. The copy is repeated, and the retry judged by the `default` instances, only if the account has no module history at all (no layer and no assignment was ever written for it), which happens only when a crash fell between the claim and the copy; an account an operator configured meanwhile, with a layer or an assignment it may have emptied, keeps that configuration and is judged by it. - **Existing account**: the stored assignment is preserved and never replaced by catalog defaults, and `scope = all` instances plus the stored assignment run, with `before` read from the stored state (section 3.2). Otherwise any cosigner, who can call `/configure` with their own key, could wipe a tighter policy an operator assigned. - **Lost claim.** Two first configurations can race; the one that loses the claim continues as a reconfiguration of the winner's account (`configure_account.rs:221-232`, test `losing_first_configuration_from_another_signer_reconfigures_the_winners_account`) **[READ]**. Its earlier pass ran against catalog defaults, not the winner's assignment, so the pipeline runs again as for an unfinished claim or an existing account, whichever the winner's account now is, before the loser consumes anything. - **Paused and released accounts.** Unlike the transaction hooks, registration has no pause or release check, because `configure_account` deliberately serves both: it keeps the pause flag on reconfiguration and reactivates a released account on re-onboarding (`configure_account.rs:278-330`) **[READ]**. The hook runs for them as for any existing account; on success the pause flag is kept, and a released account is reactivated only if every module allows. @@ -375,22 +373,22 @@ Account self-service configuration is out of scope for this revision (section 7) - **The verdict is current, not final.** For stateful modules the answer can change between creation and the ack: a window fills or resets. A proposal that passed can still be refused at the ack, and one that was refused can be created again later. Open proposals are not part of `pending`; counting them would let proposals nobody intends to execute reserve an account's budget. Two proposals that each fit the remaining budget can both be created, and the ack refuses the second. - **Disclosure.** Instances subscribed to this hook receive proposals that may never execute, which widens what a vendor sees (invariant 5). -**Example: a signer allowlist.** An operator wants every account's signers drawn from a list of vetted keys. A signer change writes public key commitments into the multisig map slot `miden::standards::auth::multisig::approver_public_keys`, and the threshold lives in `miden::standards::auth::multisig::threshold_config` (`crates/contracts/tests/auth/multisig.rs:39-40`, `crates/server/src/delta_summary/projection.rs:429`) **[READ]**. The module does not parse those slots: the Guardian decodes them into `before` and `after` (section 3.2), so `basic-policy` runs one rule at every hook. Which signers it checks is a param, because both policies are useful: +**Example: a signer allowlist.** An operator wants every account's signers drawn from a list of vetted keys. A signer change writes public key commitments into the multisig map slot `miden::standards::auth::multisig::approver_public_keys`, and the threshold lives in `miden::standards::auth::multisig::threshold_config` (`crates/contracts/tests/auth/multisig.rs:39-40`, `crates/server/src/delta_summary/projection.rs:429`) **[READ]**. The module does not parse those slots: the Guardian decodes them into `before` and `after` (section 3.2), so `signer-policy` runs one rule at every hook. Which signers it checks is a param, because both policies are useful: -- `signer_check = "added"` checks the signers `after` adds, `after.signer_commitments` minus `before.signer_commitments` (all of them at registration, where `before` is absent). Signers that predate the list are kept and do not block unrelated transactions. -- `signer_check = "all"` checks every signer in `after`, so once the list is in force an account whose current signers are not all on it can do nothing until its signers are replaced. +- `check = "added"` checks the signers `after` adds, `after.signer_commitments` minus `before.signer_commitments` (all of them at registration, where `before` is absent). Signers that predate the list are kept and do not block unrelated transactions. +- `check = "all"` checks every signer in `after`, so once the list is in force an account whose current signers are not all on it can do nothing until its signers are replaced. -Each checked signer is matched against `signer_allowlist` or `signer_denylist`. The module compares states, not the proposal type, so adding, replacing and updating signers are all covered whatever `unverified_metadata` claims. One instance subscribes to three hooks, because each closes a different path: +Each checked signer is matched against the instance's `allowlist` or `denylist`. The module compares states, not the proposal type, so adding, replacing and updating signers are all covered whatever `unverified_metadata` claims. One instance subscribes to three hooks, because each closes a different path: ```toml [[module]] -id = "signer-policy" -kind = "basic-policy" +id = "vetted-signers" +kind = "signer-policy" scope = "all" hooks = ["before_proposal_created", "before_transaction_approved", "before_account_registered"] timeout_ms = 20 on_error = "deny" -params = { signer_check = "all", signer_allowlist = ["0x…", "0x…"] } +params = { check = "all", allowlist = ["0x…", "0x…"] } ``` - `before_proposal_created` refuses the proposal before any cosigner signs it or it takes a slot. @@ -415,7 +413,7 @@ Rust code cannot be loaded into a running binary safely, so whether a module nee | Module | Official image | Guardian rebuild | |---|---|---| -| First-party in-process kinds (`basic-policy` and later first-party kinds) | Included | No; declare instances in the catalog | +| First-party in-process kinds (the four built-in policies and later first-party kinds) | Included | No; declare instances in the catalog | | Remote modules, any author and language (kind `grpc`; `http` later) | Supported | No; run the module as its own service | | Third-party or operator-written in-process kinds | Not included | Yes; custom build through `ServerBuilder` | @@ -428,11 +426,11 @@ There are two ways to use a module someone else wrote, for example a crate publi ```rust #[tokio::main] async fn main() -> anyhow::Result<()> { - guardian_module_sdk::serve(acme_sanctions::AcmeSanctions::from_env()?) - .grpc("0.0.0.0:7443") + guardian_module_sdk::serve::serve(acme_sanctions::AcmeSanctions::from_env()?) .instance("sanctions-ofac", std::fs::read_to_string("/run/secrets/module_token")?.trim()) - .run() - .await + .run("0.0.0.0:7443".parse()?) + .await?; + Ok(()) } ``` @@ -452,15 +450,15 @@ services: The module runs in its own process and sees only what the protocol sends it. It does not depend on the Guardian's Miden pins, because it reads `MidenTransaction` rather than Miden types. Module authors are encouraged to publish both the crate and a ready-made image built with `serve`. -**As an in-process kind (for code the operator wrote or audited).** `guardian-server` already exposes `ServerBuilder` (`crates/server/src/main.rs:4`) **[READ]**, but the official `main.rs` wires about 60 lines of environment configuration (storage, ack registry, CORS, network, canonicalization, release sweep, limits, ports) before calling it (`crates/server/src/main.rs:14-78`) **[READ]**. That wiring moves into the library as `ServerBuilder::from_env()`, so the official binary and every custom one share it. A custom binary then registers its kinds and starts the server: +**As an in-process kind (for code the operator wrote or audited).** `guardian-server` exposes `ServerBuilder`. The environment configuration the official binary needs (storage, ack registry, CORS, network, canonicalization, Guardian execution, release sweep, block watch, limits, ports) lives in the library as `ServerBuilder::from_env()` (`crates/server/src/builder/env.rs`), so the official `main.rs` is that call and `build`, and every custom binary shares the same wiring. Builder methods called after `from_env` override what the environment set. A custom binary registers its kinds and starts the server: ```rust #[tokio::main] async fn main() -> anyhow::Result<()> { ServerBuilder::from_env() .await? - .with_module_kind("acme-sanctions", acme_sanctions::Factory) - .with_module_kind("treasury-rules", treasury_rules::Factory) + .with_module_kind("acme-sanctions", Arc::new(acme_sanctions::Factory)) + .with_module_kind("treasury-rules", Arc::new(treasury_rules::Factory)) .build() .await? .run() @@ -469,7 +467,7 @@ async fn main() -> anyhow::Result<()> { } ``` -The operator depends on `guardian-server` at a release tag and builds with `--locked` against the `Cargo.lock` from that tag. The Guardian relies on exact Miden and Plonky3 versions, and a freshly resolved lockfile can select different transitive versions that build cleanly but break transaction execution. Each release therefore ships a `custom-guardian` template (manifest, `main.rs`, `Dockerfile` mirroring the official one, and the release `Cargo.lock`), to which the operator adds only their own crates. +The operator depends on `guardian-server` at a release tag and builds with `--locked` against the `Cargo.lock` from that tag. The Guardian relies on exact Miden and Plonky3 versions, and a freshly resolved lockfile can select different transitive versions that build cleanly but break transaction execution. Each release therefore ships a `custom-guardian` template (manifest, `main.rs`, a `Dockerfile` on the official image's toolchain and base, and the release `Cargo.lock`), to which the operator adds only their own crates. The `Custom Guardian Template` workflow builds it from `examples/custom-guardian` on every release (`scripts/custom-guardian-template.sh`: both Guardian crates at the release tag, and a `[patch.crates-io]` entry pointing the crates.io SDK there too, so the SDK the kinds implement is the one the server links; the release lockfile with only the Guardian crates' source changed, which the script checks), builds its Docker image with `--locked`, and only then attaches `custom-guardian-.tar.gz` to the release. `guardian-server` is not published to crates.io; the release tag is how it is consumed as a library. ```toml [[module]] @@ -533,7 +531,7 @@ A cosigner learns that a module refuses a transaction when the proposal is creat "account_id": "0x7bfb...a1", "policies": [ { "module_id": "recipients", "hooks": ["before_proposal_created", "before_transaction_approved"], "description": "Payments only to the treasury's approved counterparties" }, - { "module_id": "spend-cap", "hooks": ["before_transaction_approved"], "description": "At most 500,000 USDC per transaction", "params": { "max_amount_per_tx": { "0x5e0f...c3": "500000" } } } + { "module_id": "spend-cap", "hooks": ["before_transaction_approved"], "description": "At most 500,000 USDC per transaction", "params": { "max_per_transaction": { "0x5e0f...c3": "500000" } } } ] } ``` @@ -544,7 +542,7 @@ A wallet shows the two descriptions next to the transaction form; nothing in the **Client message.** A module may set `Decision.client_message` (plain text, at most 256 characters) for the person who sent the request, in addition to the logged `message`. The Guardian forwards it in `meta.client_message` only for an instance with `client_reason = "full"`, and drops it otherwise. -**Client SDKs.** The base clients mirror the RPCs (Rust `get_policies` and `check_delta_proposal`; TypeScript `getPolicies` and `checkDeltaProposal`). Both multisig SDKs expose the summary and the check in terms of transactions (Rust `get_policies`, `check_transaction` and `check_transaction_with_options`; TypeScript `getPolicies` and `checkTransaction`), so a wallet can show the rules in the form and check a transaction before the user submits it. The check builds the transaction exactly as proposing it would, so it judges the same payload. +**Client SDKs.** The base clients mirror the RPCs (Rust `get_policies` and `check_delta_proposal`; TypeScript `getPolicies` and `checkDeltaProposal`). Both multisig SDKs expose the summary and the check in terms of transactions (Rust `get_policies`, `check_transaction`, `check_transaction_with_options` and `check_custom_transaction`; TypeScript `getPolicies` and `checkTransaction`), so a wallet can show the rules in the form and check a transaction before the user submits it. Each SDK drafts a proposal once (summary, metadata and payload, unsigned) and either sends the draft to the check or pushes it (Rust adds the proposer's signature to the push), so a check judges the payload creation would send, without any signature. --- @@ -560,15 +558,12 @@ service GuardianModule { rpc Describe(DescribeRequest) returns (ModuleInfo); rpc ValidateParams(ValidateParamsRequest) returns (ParamsVerdict); rpc Evaluate(HookRequest) returns (Decision); - rpc Notify(CommitEvent) returns (NotifyAck); - rpc NotifyGap(Gap) returns (NotifyAck); } enum Hook { HOOK_UNSPECIFIED = 0; HOOK_BEFORE_TRANSACTION_APPROVED = 1; HOOK_BEFORE_ACCOUNT_REGISTERED = 2; - HOOK_AFTER_TRANSACTION_COMMITTED = 3; HOOK_BEFORE_PROPOSAL_CREATED = 4; } @@ -593,18 +588,16 @@ message ParamsVerdict { string message = 2; bytes normalized_params = 3; // UTF-8 JSON; empty: store the params as sent (section 3.5) } -message NotifyAck {} - message HookRequest { string request_id = 1; // one per hook invocation, shared by every module and layer called in it (section 3.1) Hook hook = 2; bool dry_run = 3; // a policy check: nothing is stored or signed whatever the decision (section 2.7) string network = 4; // network family: "miden" - string network_id = 5; // the account's network within the family: "mainnet", "testnet", "devnet", "cedar" or "local" (section 3.1) + string network_id = 5; // the network this Guardian serves within the family: "mainnet", "testnet", "devnet", "cedar" or "local"; from its own configuration, never from the request (section 3.1) string account_id = 6; string instance_id = 7; // catalog id of the instance being called bytes params = 8; // UTF-8 JSON, params of the layer being evaluated (global, account layer, or the account's own for default/assigned) - google.protobuf.Timestamp accounting_time = 9; // recorded as signed_at if this transaction is signed (section 3.4); at before_proposal_created and in a dry run, the evaluation time, never recorded + google.protobuf.Timestamp accounting_time = 9; // the evaluation time, from the Guardian's clock string submitter = 10; // signer commitment that authenticated this request; verified (section 3.2) bool submitter_session = 11; // the request was authenticated by a session key the submitter delegated (section 3.2) optional AccountView before = 12; // the account as the Guardian holds it; absent for a first configuration (section 3.2) @@ -617,56 +610,37 @@ message HookRequest { message AccountView { string commitment = 1; - string auth_scheme = 2; // "falcon" or "ecdsa", from the registered auth configuration (section 3.2) + string auth_scheme = 2; // the scheme every signer shares, "falcon" or "ecdsa", or "mixed" (section 3.2) repeated string signer_commitments = 3; optional uint32 default_threshold = 4; // absent for single-key accounts map procedure_thresholds = 5; // procedure root -> threshold; only overrides the account's code can apply (section 3.2) string code_commitment = 6; // commitment of the account's code repeated string procedure_roots = 7; // roots of the procedures the account's code exports + map signer_schemes = 8; // signer commitment -> "falcon" or "ecdsa"; one entry per signer (section 3.2) } message TransactionSubject { TransactionProjection projection = 1; // the contract modules should rely on, per network RawTransaction raw = 2; // the network's own encoding; UNSTABLE across that network's protocol bumps - repeated PendingTransaction pending = 3; // signed for this account, not yet acknowledged by this module (section 3.4) string proposer = 4; // signer commitment that created the matching proposal; verified; empty when there is none (section 3.2) - bool proposer_session = 5; // the proposer created it through a delegated session key (section 3.2) - bytes unverified_metadata = 6; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) -} - -message PendingTransaction { - string new_commitment = 1; // = event_id once committed - TransactionProjection projection = 2; - google.protobuf.Timestamp signed_at = 3; // the accounting clock (section 3.4) - PendingState state = 4; - uint64 nonce = 5; // account nonce after this transaction; compared with the module's watermark - optional google.protobuf.Timestamp committed_at = 6; // set when state = committed - string submitter = 7; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) - string proposer = 8; // as in TransactionSubject at that ack; empty when there was no matching proposal - bool proposer_session = 9; // as in TransactionSubject at that ack -} -enum PendingState { - PENDING_STATE_UNSPECIFIED = 0; - PENDING_STATE_CANDIDATE = 1; // signed, waiting to become committed - PENDING_STATE_COMMITTED = 2; // committed, notify not yet acknowledged by this module + bytes unverified_metadata = 5; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) } message RegistrationSubject { - AccountStateProjection initial_state = 1; // the account about to be accepted, per network + AccountStateProjection initial_state = 1; // the account about to be accepted, per network: its whole vault and storage } enum Effect { - EFFECT_UNSPECIFIED = 0; // a module that does not set `effect`: `allow` decides + EFFECT_UNSPECIFIED = 0; // never a decision: a module failure EFFECT_ALLOW = 1; EFFECT_DENY = 2; } message Decision { - bool allow = 1; // read only when effect is unspecified - string reason_code = 2; // required on a deny; ignored on an allow + Effect effect = 1; // unspecified, or a value the Guardian does not know, is a module failure + string reason_code = 2; // required on a deny, [a-z0-9_]{1,64}; a deny with another code is still a deny, reported as policy_denied; ignored on an allow string message = 3; // logged, never forwarded to clients - Effect effect = 4; // wins over allow when set; a value the Guardian does not know is a module failure - string client_message = 5; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) + string client_message = 4; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) } // A transaction as its network describes it. One variant per network; a module reads the @@ -691,14 +665,15 @@ message RawTransaction { } message MidenTransaction { - int64 nonce_delta = 1; - uint32 reference_block = 2; // the block the transaction was executed against - optional uint32 expiration_block = 3; // absent when the transaction sets no expiration (section 3.1) + uint64 nonce_delta = 1; + uint32 bound_block = 2; // the block the summary binds; the transaction executes against this block or a later one (section 3.1) + optional uint32 expiration_delta = 3; // blocks after the block the transaction executes against at which it expires; absent when its script sets none. Not an absolute height: that block is not known at approval (section 3.1) repeated VaultChange vault_changes = 4; repeated OutputNote output_notes = 5; repeated InputNote input_notes = 6; repeated StorageChange storage_changes = 7; optional string new_code_commitment = 8; // set when the transaction replaces the account's code (section 3.1) + optional uint64 approval_expiration_block = 9; // the block at which the cosigners' approval of this transaction lapses; absent when it never lapses (section 3.1) } message MidenAccountState { @@ -722,7 +697,8 @@ message OutputNote { repeated Asset assets = 5; string script_root = 6; optional string p2id_target = 7; // set only for known P2ID / P2IDE scripts - bool tx_fee = 8; // the fee note pay_fee creates; not a payment + bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note, and only while it carries no more of the fee asset than a transaction can owe) + optional string reclaimer = 9; // P2IDE only, set when its reclaim height is set: the account that can take the note once that height is reached, chosen freely by the note's creator; a recipient rule must judge it as well as p2id_target } enum NoteType { NOTE_TYPE_UNSPECIFIED = 0; NOTE_TYPE_PUBLIC = 1; NOTE_TYPE_PRIVATE = 2; } @@ -744,42 +720,18 @@ message StorageSlot { StorageSlotKind kind = 2; oneof content { string value = 3; MapChanges map = 4; } } - -message CommitEvent { - string event_id = 1; // = new_commitment; stable across redelivery - string instance_id = 2; - string account_id = 3; - string network = 4; // as in HookRequest - string network_id = 5; // as in HookRequest - string prev_commitment = 6; - string new_commitment = 7; - uint64 nonce = 8; // account nonce after this transaction; the delivery watermark (section 3.3) - TransactionProjection projection = 9; - google.protobuf.Timestamp committed_at = 10; - google.protobuf.Timestamp signed_at = 11; // the accounting clock, identical to the value the module saw in pending (section 3.4) - string submitter = 12; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) - string proposer = 13; // as in TransactionSubject at that ack; empty when there was no matching proposal (section 3.2) - bool proposer_session = 14; // as in TransactionSubject at that ack -} - -message Gap { - string instance_id = 1; - string account_id = 2; - string network = 3; // as in HookRequest - string network_id = 4; // as in HookRequest - google.protobuf.Timestamp dropped_before = 5; // restart position: events for the account committed before this and not acknowledged may be missing - uint64 resume_from_nonce = 6; // first nonce delivered after the gap; the module's watermark becomes resume_from_nonce - 1 (section 3.3) -} ``` +Version 1 as first published carries only the stateless contract. The stateful additions of sections 3.3 and 3.4 (the `Notify` and `NotifyGap` RPCs, `CommitEvent`, `Gap`, `NotifyAck`, `TransactionSubject.pending` with `PendingTransaction` and `PendingState`, and the `after_transaction_committed` hook) are added with M2b, as a named capability within version 1 (section 3.5), so modules built against this contract keep working. + ### 3.1 Typed projection **Encodings.** All string-typed values in the protocol follow one convention, normalized by the Guardian at the boundary (AGENTS.md section 12, Hex/Bytes Boundary Rule): -- Words, digests, commitments and roots (`AccountView.commitment`, `signer_commitments`, `procedure_thresholds` keys, `code_commitment`, `procedure_roots`, `new_code_commitment`, `prev_commitment`, `new_commitment`, `note_id`, `recipient_digest`, `script_root`, `nft_id`, storage values, map keys and values): `0x` followed by 64 lowercase hex characters. +- Words, digests, commitments and roots (`AccountView.commitment`, `signer_commitments`, `procedure_thresholds` keys, `code_commitment`, `procedure_roots`, `new_code_commitment`, `note_id`, `recipient_digest`, `script_root`, `nft_id`, storage values, map keys and values): `0x` followed by 64 lowercase hex characters. - Amounts and other single field elements (`fungible_amount`): unsigned decimal strings, so values above 2^53 survive JSON. - Account ids (`account_id`, `faucet_id`, `p2id_target`): the Guardian's canonical `0x` lowercase hex form of the account id. -- Nonces (`nonce`, `resume_from_nonce`): `uint64`, which the proto3 JSON mapping renders as a decimal string, consistent with the amount rule. +- Nonces (`nonce_delta`; with M2b also `nonce` and `resume_from_nonce`): `uint64`, which the proto3 JSON mapping renders as a decimal string, consistent with the amount rule. The M2b commitments (`prev_commitment`, `new_commitment`) follow the word rule above. - Storage slots: the slot's `StorageSlotName` as its string form, which is stable across accounts and protocol bumps and is what the dashboard projector already emits (`crates/server/src/delta_summary/projection.rs:301`) **[READ]**. Miden 0.17 identifies slots by name and records each changed slot as a value or map patch with a create, update or remove operation (`miden-protocol-0.17.1/src/account/patch/storage/slot_patch.rs:27-30`, `value_patch.rs:18-26`, `map_patch.rs:20-33`) **[READ]**; `StorageChange` carries exactly that. A removed slot has `op = remove` and no content. A removed map entry has the empty word as its value, as in the existing projector. - Timestamps: `google.protobuf.Timestamp`, RFC 3339 in UTC in the JSON mapping, always taken from the Guardian's clock. @@ -787,9 +739,9 @@ message Gap { **Request identity.** `request_id` is unique per hook invocation and shared by every module and layer called in it, so a module's logs can be joined with the Guardian's denial log (section 2.2, "Evaluation trace"). A client retry is a new invocation with a new id. It is for correlation only: `evaluate` has no side effects (section 2.1), so there is nothing to deduplicate. -**Network.** `network` names the network family (`miden`); `network_id` names the account's network within it (`mainnet`, `testnet`, `devnet`, `cedar` or `local`), taken from the account's registered network configuration, since one Guardian can serve accounts on several Miden networks. A module must not infer the network from an address prefix: Cedar shares mainnet's bech32 prefix and a local node shares devnet's (`crates/server/src/metadata/network.rs:29-43`) **[READ]**. +**Network.** `network` names the network family (`miden`); `network_id` names the network this Guardian serves within it (`mainnet`, `testnet`, `devnet`, `cedar` or `local`), taken from the Guardian's own configuration (`GUARDIAN_NETWORK_TYPE`). It is never the `network_type` an account was registered with: that field is optional in `/configure`, defaults to `local`, and is chosen by the registrant, so a policy keyed on it could be steered by the account it judges. A module must not infer the network from an address prefix: Cedar shares mainnet's bech32 prefix and a local node shares devnet's (`crates/server/src/metadata/network.rs:29-43`) **[READ]**. -**Expiration and code.** `reference_block` is the summary's block number and `expiration_block` is `reference_block + expiration_delta`; a transaction without an expiration has an expiration delta of 0, and `expiration_block` is then absent rather than equal to the reference block, so a module can tell "never expires" from "expires now" and compute the validity window. `new_code_commitment` is set when the transaction's account delta carries a code patch, which the Guardian applies like any other change today (`merge_account_deltas`, `crates/server/src/network/miden/mod.rs:873`) **[READ]**; a module that pins account code denies on it (section 3.2). +**Blocks, expiration and code.** `bound_block` is the block the summary binds; the transaction executes against that block or a later one, which is not known when the Guardian approves. `expiration_delta` is the delta the transaction's script sets, counted from the block it executes against, so it is not an absolute height and is absent when the script sets none. `approval_expiration_block` is the absolute block at which the cosigners' approval of this summary lapses (the summary's first user parameter), absent when the approval never lapses: it is the bound a module uses for "this approval is valid until". `new_code_commitment` is set when the transaction's account delta carries a code patch, which the Guardian applies like any other change today (`merge_account_deltas`, `crates/server/src/network/miden/mod.rs:873`) **[READ]**; a module that pins account code denies on it (section 3.2). **Registration cost.** `RegistrationSubject.initial_state` is built from the account `configure_account` already decodes to read its state head (`get_state_head`, `crates/server/src/services/configure_account.rs:184`) **[READ]**. Building the vault and storage projection from it is new work on the registration path, and the implementation should build it only when a module that declares `before_account_registered` will be called. @@ -797,28 +749,28 @@ message Gap { `MidenTransaction` (defined in the proto above) is a flattened view the Guardian decodes once from the `TransactionSummary`. It has its own builder and types, mapped one to one onto the proto, so a change to the dashboard cannot move the module contract. The builder shares low-level helpers with the dashboard projector (`decode_full`, `crates/server/src/delta_summary/projection.rs:88`) **[READ]**, which already yields notes, vault changes and storage changes but not `nonce_delta`, `expiration_block`, `partial`, `recipient_digest`, `script_root`, `p2id_target` or the per-slot storage operation; how much of the rest it can reuse is measured by the prototype (`speckit/features/251-guardian-modules/research.md`, gate G2), and a field that cannot be derived is removed before protocol version 1 freezes. It is the only code that changes on a Miden protocol bump, so modules that read only the projection do not need a Miden decoder pinned to the Guardian's protocol line. `raw` is the exception: it carries the summary in Miden's binary serialization (`TransactionSummary::to_bytes`), and its encoding follows the Guardian's Miden pin and can change on any protocol bump, so a module that decodes it is tied to that pin. Both are decoded from exactly the summary the Guardian verifies and signs: the bare summary at approval, the proposal's `tx_summary` at creation. The decoder never unwraps or falls back to another field, so a request cannot have modules judge one summary while the Guardian signs another. -`p2id_target` is set only when the note script root is a known P2ID or P2IDE script. Recipient-based policies are enforceable because `TransactionSummary.output_notes` is a collection of `RawOutputNote::Full(Note) | Partial(PartialNote)` (`miden-protocol-0.17.1/src/transaction/tx_summary.rs:31-39`, `outputs/notes.rs:190`) **[READ]**: a full note carries recipient, assets and script even when its type is private. A partial note exposes only the recipient digest, so it is marked `partial = true` and a recipient policy must decide what to do with an unknown recipient. +`p2id_target` is set only when the note script root is a known P2ID or P2IDE script. A P2IDE note also names a reclaimer, chosen freely by the note's creator, that can consume the note once its reclaim height is reached; `reclaimer` carries it whenever that height is set, and a recipient rule must judge it as well as the target, or a note to an allowed target with a blocked reclaimer pays the blocked account. Recipient-based policies are enforceable because `TransactionSummary.output_notes` is a collection of `RawOutputNote::Full(Note) | Partial(PartialNote)` (`miden-protocol-0.17.1/src/transaction/tx_summary.rs:31-39`, `outputs/notes.rs:190`) **[READ]**: a full note carries recipient, assets and script even when its type is private. A partial note exposes only the recipient digest, so it is marked `partial = true` and a recipient policy must decide what to do with an unknown recipient. -**The fee is a note.** In Miden 0.17 `pay_fee` creates a public `TX_FEE` output note funded from the account's vault (`miden-standards-0.17.1/src/account/auth/singlesig.rs:45`) **[READ]**. Listed as an ordinary note, the fee looks like a payment: in the prototype a cap on the fee asset refused every transaction, consuming notes included, and a recipient allowlist would refuse every transaction too, since the fee note has no P2ID recipient. The Guardian therefore marks it with `OutputNote.tx_fee` (set when the note script is the standard `TX_FEE` script), and policies treat it as the fee, not a payment. +**The fee is a note.** In Miden 0.17 `pay_fee` creates a public `TX_FEE` output note funded from the account's vault (`miden-standards-0.17.1/src/account/auth/singlesig.rs:45`) **[READ]**. Listed as an ordinary note, the fee looks like a payment: in the prototype a cap on the fee asset refused every transaction, consuming notes included, and a recipient allowlist would refuse every transaction too, since the fee note has no P2ID recipient. The Guardian therefore marks it with `OutputNote.tx_fee`, and policies treat it as the fee, not a payment. The script alone does not identify the fee: `TX_FEE` is a standard script that any transaction script can use (`tx_fee::create_output_note` is public), with any assets, and anyone can consume the note, so a note marked by its script would move funds past every recipient, asset and amount rule. `tx_fee` is set only for the note `pay_fee` creates, recognized by everything `pay_fee` fixes: it is the transaction's only `TX_FEE` note, its serial number is `TxFeeNote::derive_serial_number(account, nonce before the transaction, block the summary binds)`, and it carries one fungible asset of the chain's fee faucet, no more of it than a transaction can owe. The Guardian reads the fee faucet and the verification base fee from the node's latest block header and its protocol configuration, and reads them again once that read is a minute old. The fee is the base fee times `ilog2(cycles) + 1`, which stays below 32 for any cycle count the kernel accepts, so the bound is 64 times the base fee: a note over it is a payment. On a chain whose base fee is zero `pay_fee` creates no note, so no note is marked there; otherwise a transaction script could create the one `TX_FEE` note itself, with the derivable serial number and any amount. Any other `TX_FEE` note, and every `TX_FEE` note when the transaction has more than one, is an ordinary output note. While the fee asset has never been read, a transaction that carries a `TX_FEE`-script note cannot be projected, so each instance's `on_error` applies (`GUARDIAN_MODULE_UNAVAILABLE` for a fail-closed one) instead of the note being judged as a payment and denied for good. -#### `basic-policy` rules +#### Built-in policies -The reference kind reads only the projection and the account views. Each rule denies with a fixed `reason_code` and a fixed `client_message` that names the rule, never a list entry or a limit, so an instance with `client_reason = "full"` tells the user what to change without disclosing params the operator kept back (`disclosure`, section 2.7): +Four first-party kinds, one concern each, so an instance carries only the params of the rule it enforces, and a kind refuses params that belong to another. Each kind supports only the hooks where its rule can refuse something, so a catalog that subscribes it to another hook does not start. They read only the projection and the account views. Each rule denies with a fixed `reason_code` and a fixed `client_message` that names the rule, never a list entry or a limit, so an instance with `client_reason = "full"` tells the user what to change without disclosing params the operator kept back (`disclosure`, section 2.7): -| Param | Rule | `reason_code` | -|---|---|---| -| `recipient_allowlist` | Every payment note's `p2id_target` is listed. A partial note, or one whose script is not a known P2ID or P2IDE script (no `p2id_target`), is refused, since its recipient cannot be checked | `recipient_not_allowed` | -| `recipient_denylist` | No payment note's `p2id_target` is listed; with `deny_unknown_recipients = true`, a partial or non-P2ID note is refused as well, since a denylist cannot otherwise check it | `recipient_blocked` | -| `asset_allowlist` | Every asset sent in a payment note or received in an input note is listed; vault changes are not used, because they cannot tell a fee from a payment | `asset_not_allowed` | -| `max_amount_per_tx` | Per listed faucet, the gross amount leaving the account (the sum of that faucet's fungible amounts over every output note, full or partial) is at most the cap. Amounts of different assets are not comparable, so the cap is per asset; input notes do not offset it, so a payment cannot be split across notes or netted against a receive; faucets not listed are uncapped; non-fungible assets are governed only by `asset_allowlist` | `amount_cap_exceeded` | -| `signer_allowlist` or `signer_denylist`, with `signer_check` | The checked signers (section 2.3, signer allowlist example) are all on the allowlist, or none is on the denylist; an instance sets at most one of the two | `signer_not_allowed` | -| `allowed_code_commitments`, with `code_check` | `code_check = "changed"` (default): at registration `after.code_commitment` is listed, and on a transaction `new_code_commitment`, when set, is listed. Code an account already runs is kept until it changes, as `signer_check = "added"` keeps signers: an account registered before the instance existed passes until it replaces its code or re-registers. `code_check = "all"`: `after.code_commitment` is listed at every gate hook, so once the list is in force an account on unlisted code can do nothing but upgrade to listed code. Pins the account to code the operator has reviewed (invariant 6) | `code_not_allowed` | +| Kind (hooks) | Param | Rule | `reason_code` | +|---|---|---|---| +| `spending-limit` (proposal creation, transaction approval) | `max_per_transaction` | Per listed faucet, the gross amount leaving the account (the sum of that faucet's fungible amounts over every output note, full or partial) is at most the cap. Amounts of different assets are not comparable, so the cap is per asset; input notes do not offset it, so a payment cannot be split across notes or netted against a receive; faucets not listed are uncapped; non-fungible assets are governed only by `allowed_assets`. Limits over a period need module state (M2b) and belong to this kind | `amount_cap_exceeded` | +| | `allowed_assets` | Every asset sent in a payment note or received in an input note is listed; vault changes are not used, because they cannot tell a fee from a payment | `asset_not_allowed` | +| `recipient-policy` (proposal creation, transaction approval) | `allowlist` | Every payment note's `p2id_target` is listed, and so is its `reclaimer` unless that is the paying account. A partial note, or one whose script is not a known P2ID or P2IDE script (no `p2id_target`), is refused, since its recipient cannot be checked. Excludes `denylist` | `recipient_not_allowed` | +| | `denylist`, with `deny_unknown` | No payment note's `p2id_target` or `reclaimer` is listed. A partial or non-P2ID note is refused as well once the list names anyone, since a blocked recipient could otherwise be paid through a note the denylist cannot check; `deny_unknown = false` opts out, and `true` applies it to an empty list too | `recipient_blocked` | +| `signer-policy` (registration, proposal creation, transaction approval) | `allowlist` or `denylist`, with `check` | The checked signers (section 2.3, signer allowlist example) are all on the allowlist, or none is on the denylist; an instance sets at most one of the two | `signer_not_allowed` | +| `code-policy` (registration, proposal creation, transaction approval) | `allowed`, with `check` | `check = "changed"` (default): at registration `after.code_commitment` is listed, and on a transaction `new_code_commitment`, when set, is listed. Code an account already runs is kept until it changes, as `check = "added"` keeps signers: an account registered before the instance existed passes until it replaces its code or re-registers. `check = "all"`: `after.code_commitment` is listed at every gate hook, so once the list is in force an account on unlisted code can do nothing but upgrade to listed code. Pins the account to code the operator has reviewed (invariant 6) | `code_not_allowed` | -The fee note (`tx_fee`) is excluded from every recipient, asset and amount rule. At `before_account_registered` there is no transaction, so only the signer and code rules apply; the transaction rules pass. A transaction request without a Miden projection is not judged: the module returns an error, as for any transaction it cannot judge (section 3.1), so the instance's `on_error` applies. +The fee note (`tx_fee`) is excluded from every recipient, asset and amount rule. A request a kind cannot judge, such as a transaction without a Miden projection, is not judged: the module returns an error, as for any transaction it cannot judge (section 3.1), so the instance's `on_error` applies. ### 3.2 Account views and proposal context -**One view of the account at every gate hook.** Rules about who controls an account (signer allowlists, a minimum signer count, a threshold floor) apply at registration and at every signer change, and a module should not need a code path per hook to evaluate them. `HookRequest` therefore carries, for every gate hook, the account before and after the request, in an `AccountView`: commitment, signer commitments, default threshold and per-procedure thresholds decoded from account state, and the auth scheme taken from the account's registered auth configuration (`Auth::scheme()`). The scheme is not decoded: schemes are stored per approver (`approver_schemes`), so storage could mix them, while the Guardian registers one scheme per account, which is what `auth_scheme` reports. The default threshold alone does not bound how many approvals a transaction needs: a procedure threshold overrides it for that procedure, so a threshold floor checks both. +**One view of the account at every gate hook.** Rules about who controls an account (signer allowlists, a minimum signer count, a threshold floor) apply at registration and at every signer change, and a module should not need a code path per hook to evaluate them. `HookRequest` therefore carries, for every gate hook, the account before and after the request, in an `AccountView`: commitment, signer commitments, default threshold and per-procedure thresholds decoded from account state, and each signer's scheme in `signer_schemes`. Schemes are per signer: since #565 an account's approvers can mix Falcon and ECDSA, so a multisig view decodes each approver's scheme from its state (`approver_schemes`), which also covers a signer an `after` view adds before the Guardian has registered it. A missing or unsupported scheme entry fails extraction rather than producing a signer without a scheme. `auth_scheme` summarizes `signer_schemes`: the scheme every signer shares, or `mixed`. The default threshold alone does not bound how many approvals a transaction needs: a procedure threshold overrides it for that procedure, so a threshold floor checks both. **Procedure thresholds and code.** On chain, an override applies only to a procedure the account's code exports and the transaction calls, never to the auth procedure itself, and a zero override means the default applies (`compute_transaction_threshold` in `multisig.masm`, `miden-standards-0.17.1`) **[READ]**. The storage map can still hold entries that change nothing, so `procedure_thresholds` carries only effective overrides: non-zero, on a procedure in `procedure_roots`, not on the auth procedure. A module that sets a floor therefore never denies on an inert entry. `code_commitment` and `procedure_roots` describe the code the account runs. The Guardian checks storage slots (the Guardian commitment, the signer set) but never the code (`validate_guardian_commitment`, `crates/server/src/network/miden/mod.rs:649-669`; `has_multisig_auth`, `network/miden/account_inspector.rs:98-101`) **[READ]**, so a module that must know the account enforces its approvals, for example by requiring the standard guarded multisig component, pins `code_commitment` at `before_account_registered` and denies a `MidenTransaction.new_code_commitment` it does not accept. @@ -828,17 +780,17 @@ The fee note (`tx_fee`) is excluded from every recipient, asset and amount rule. | `before_transaction_approved` | The base of the delta being acked (tail or canonical state) | The base with the delta applied | | `before_account_registered` | Absent for a first configuration, an unfinished claim included (section 2.3, "Registration"); for an existing account, the stored state, read for this purpose | The submitted `initial_state` | -**Single-key accounts** carry no multisig component, so nothing in their storage holds a signer set or thresholds. Their view is built from the registered signer instead: `signer_commitments` holds that one commitment, `default_threshold` is absent and `procedure_thresholds` is empty; `code_commitment` and `procedure_roots` are read from the account as for any other. Signer rules therefore apply to them, and threshold rules have nothing to check. Without this, every gate request for a single-key account would fail extraction and fall to `on_error`, so a fail-closed signer module would block every single-key account. +**Single-key accounts** carry no multisig component, so nothing in their storage holds a signer set or thresholds. Their view is built from the registered signer instead: `signer_commitments` holds that one commitment, `signer_schemes` its registered scheme, `default_threshold` is absent and `procedure_thresholds` is empty; `code_commitment` and `procedure_roots` are read from the account as for any other. Signer rules therefore apply to them, and threshold rules have nothing to check. Without this, every gate request for a single-key account would fail extraction and fall to `on_error`, so a fail-closed signer module would block every single-key account. -**Building the views is new work.** The Guardian decodes signer sets today, but not the whole view. `account_auth_binding` (`crates/server/src/services/candidate_chain.rs:316`) returns `AuthBinding { signers, guardian }`, with no threshold and no scheme (`crates/server/src/network/mod.rs:266-269`); its Miden implementation returns the signers it extracts even when the list is empty (`crates/server/src/network/miden/mod.rs:826-829`), and `should_update_auth` maps an empty list to "nothing to update" (`:844-845`) **[READ]**. An empty signer set read as a successful view would make every signer rule pass: nothing is added, nothing is checked. The implementation therefore adds one extraction that reads the signer, threshold and procedure-threshold slots and the scheme, and that returns an error for auth state it does not support or cannot decode, never an empty view. A failed extraction is treated as an error for every module called at that hook, so each module's `on_error` applies (section 4.2). At the transaction hooks both states are in hand: the base the delta is checked against and the result of applying it. At re-onboarding they are not: `configure_account` reads only the account metadata (`configure_account.rs:64`) **[READ]**, so building `before` adds a read of the stored state, made only when a module subscribed to `before_account_registered` will be called. The prototype confirmed the extraction: `threshold_config` holds `[threshold, num_approvers, 0, 0]`, approvers are read at indices `0..num_approvers` with a missing key treated as an error, and `procedure_thresholds` is read in full and then filtered to effective overrides (above). Decoding the account dominates the cost, about 1.1 ms per view in a release build and so about 2 ms per gate request; the projection takes microseconds. Since #523 the push path decodes the base account once and applies the summary to it (`verify_and_apply_delta`, `crates/server/src/network/mod.rs:313-318`, called at `push_delta.rs:143`) **[READ]**, so both views can be read from that one decode, `before` before the summary is applied and `after` from the result, by adding the view fields to `AppliedState`; proposal creation still calls `verify_delta` alone (`push_delta_proposal.rs:210`) **[READ]** and moves to `verify_and_apply_delta` when a module will be called. Building the views and the projection runs inside the bounded reconstruction task the push path already uses for `apply_delta` (`network::reconstructor()`), not on the request task, so request assembly is held to the same CPU bound and a malformed summary (for example an expiration height that overflows) is an error under `on_error`, never a panic. Modules that need the raw layout still have `MidenTransaction.storage_changes`, and vault effects stay in `TransactionSubject`: amount and recipient rules apply only to transactions, and a full vault view on every request would be large. +**Building the views is new work.** The Guardian decodes signer sets today, but not the whole view. `account_auth_binding` (`crates/server/src/services/candidate_chain.rs:316`) returns `AuthBinding { signers, guardian }`, with no threshold and no scheme (`crates/server/src/network/mod.rs:266-269`); its Miden implementation returns the signers it extracts even when the list is empty (`crates/server/src/network/miden/mod.rs:826-829`), and `should_update_auth` maps an empty list to "nothing to update" (`:844-845`) **[READ]**. An empty signer set read as a successful view would make every signer rule pass: nothing is added, nothing is checked. The implementation therefore adds one extraction that reads the signer, threshold and procedure-threshold slots and the scheme, and that returns an error for auth state it does not support or cannot decode, never an empty view. A failed extraction is treated as an error for every module called at that hook, so each module's `on_error` applies (section 4.2). At the transaction hooks both states are in hand: the base the delta is checked against and the result of applying it. At re-onboarding they are not: `configure_account` reads only the account metadata (`configure_account.rs:64`) **[READ]**, so building `before` adds a read of the stored state, made only when a module subscribed to `before_account_registered` will be called. The prototype confirmed the extraction: `threshold_config` holds `[threshold, num_approvers, 0, 0]`, approvers are read at indices `0..num_approvers` with a missing key treated as an error, and `procedure_thresholds` is read in full and then filtered to effective overrides (above). Decoding the account dominates the cost (see "Cost and where it runs" below); the projection takes microseconds. Since #523 the push path decodes the base account once and applies the summary to it (`verify_and_apply_delta`) **[READ]**, so both views and the projection are read from that one decode: `before` and the projection before the summary is applied, `after` from the result (`apply_delta_with_module_inputs`, returning `ModuleInputs`). Proposal creation, which otherwise only verifies the delta (`verify_delta`), uses the same call when a module will be called. Building the views and the projection runs inside the bounded reconstruction task the push path already uses for `apply_delta` (`network::reconstructor()`), not on the request task, so request assembly is held to the same CPU bound and a malformed summary (for example an expiration height that overflows) is an error under `on_error`, never a panic. Modules that need the raw layout still have `MidenTransaction.storage_changes`, and vault effects stay in `TransactionSubject`: amount and recipient rules apply only to transactions, and a full vault view on every request would be large. -**Cost and caching.** Decoding the account for a view is the main cost of a module request: about 1.3 ms per view in a release build, against microseconds for the projection and the in-process evaluation. Views are therefore cached per replica by the state commitment the Guardian computed (the stored tail, the applied state, the registration head; never a commitment a client sent), with the parts taken from the registered auth configuration applied after the lookup. States repeat: a chained push starts from the previous push's result, and a proposal's approval sees the same states as its creation. Measured end to end on `push_delta` with the cache, one in-process module adds about 3 to 4 ms at p50 and stays inside the 10 ms p99 target; a remote module over loopback costs no more at p50 (`speckit/features/251-guardian-modules/research.md`, "G3 end to end"). +**Cost and where it runs.** Decoding the account for a view is the main cost of a module request: about 1.3 ms per view in a release build, against microseconds for the projection and the in-process evaluation. The views and the projection are therefore built by the decode each request already makes, inside the bounded reconstruction task (section 4.3), never by request assembly: at the transaction hooks the decode that verifies and applies the delta against its base also yields both views and the projection (the chain fee, which tells the fee note apart, is loaded before it); at registration the initial state, and the stored state on a reconfiguration, are each decoded once for the view and the account state. Request assembly on the async worker only copies these parts into the request, and a part that could not be extracted fails the request for every module called, so each module's `on_error` applies. The ack path reads the account's plan before the reconstruction, so nothing is built for an account no module applies to. Registration with a module to call therefore waits for a reconstruction slot like a push does; without one it takes no slot, as before. An earlier revision cached views per replica by state commitment; with every view coming from a decode the request makes anyway the cache saved nothing, and a miss under load decoded inline on the async worker, so it was removed. Measured end to end before and after the move in `speckit/features/251-guardian-modules/research.md` ("Module inputs from the reconstruction decode"). **Proposal context.** `HookRequest.submitter` and the `TransactionSubject` fields below carry who acted on the transaction and what the proposer said about it. The two are trusted differently. -**Verified identities.** Both are signer commitments taken from request authentication (`ResolvedAccount.signer_commitment`, `crates/server/src/services/mod.rs:120`) **[READ]**, never from the payload. A proposal can also be created under a delegated session key (#537): `push_delta_proposal` accepts sessions (`resolve_account_allowing_session`, `push_delta_proposal.rs:75`), and for a session credential the resolved commitment is the cosigner that granted the session, not the session key (`services/mod.rs:193-199`) **[READ]**. `submitter` and `proposer` are therefore always cosigner commitments; `push_delta` and `/configure` do not accept sessions. Two flags keep delegation visible. `HookRequest.submitter_session` marks a request authenticated through a session; since only proposal creation accepts sessions, it is always false at the ack. `TransactionSubject.proposer_session` marks a proposal created through one: it is stored with the proposal, returned by the `ProposalContext` lookup together with the proposer, and repeated in `pending` and `CommitEvent` like `proposer`. A rule such as "delegated sessions may not propose signer changes" therefore holds at the ack, where it must be enforced (section 2.3, "Not a security boundary"), and not only at creation, where it is a filter. A transaction pushed without a stored proposal has an empty `proposer` and `proposer_session = false`; a rule that must hold treats it as an unknown proposer (below). +**Verified identities.** Both are signer commitments taken from request authentication (`ResolvedAccount.signer_commitment`, `crates/server/src/services/mod.rs:120`) **[READ]**, never from the payload. A proposal can also be created under a delegated session key (#537): `push_delta_proposal` accepts sessions (`resolve_account_allowing_session`, `push_delta_proposal.rs:75`), and for a session credential the resolved commitment is the cosigner that granted the session, not the session key (`services/mod.rs:193-199`) **[READ]**. `submitter` and `proposer` are therefore always cosigner commitments. `/configure` refuses session credentials; proposal creation, `push_delta` (#580) and Guardian execution requests accept them. `HookRequest.submitter_session` marks a request authenticated through a session, at proposal creation, at the ack of a push and at the ack of a Guardian execution, so a rule such as "a delegated session may not push signer changes" holds at the ack, where it must be enforced (section 2.3, "Not a security boundary"). Whether a stored proposal was created through a session is not sent: a session key authenticates requests but cannot add a cosigner's approval, so a proposal created through one still needs the account's threshold of cosigner signatures before the Guardian acks it, and no policy in this RFC's catalog needs the distinction. Version 1 can add it later as a new field. A transaction pushed without a stored proposal has an empty `proposer`; a rule that must hold treats it as an unknown proposer (below). -- `submitter` is the cosigner whose request is being evaluated: the proposer at `before_proposal_created`, the cosigner calling `push_delta` at `before_transaction_approved`. On the execution path it is the cosigner whose authenticated request created the execution attempt (RFC 0001). At the cited execution baseline that identity is not kept: the service authenticates the requester (`execute_proposal/service.rs:131` at `29c722b4`) but `ExecutionJob` holds no requester (`worker.rs:27-40`) **[READ]**. The implementation records the authenticated requester when it creates an attempt, stores it on the durable reservation so a worker resumed after a restart still has it, and carries it through the ack and into the stored delta. A repeated request for an attempt already active keeps the original requester. +- `submitter` is the cosigner whose request is being evaluated: the proposer at `before_proposal_created`, the cosigner calling `push_delta` at `before_transaction_approved`. On the execution path it is the cosigner whose authenticated request created the execution attempt (RFC 0001). At the cited execution baseline that identity is not kept: the service authenticates the requester (`execute_proposal/service.rs:131` at `29c722b4`) but `ExecutionJob` holds no requester (`worker.rs:27-40`) **[READ]**. The implementation records the authenticated requester when it creates an attempt and carries it to the ack. It is not stored on the reservation: the ack runs before the no-retry boundary, and an attempt interrupted before that boundary is never resumed (the first reconciliation pass after a restart fails it as `GUARDIAN_EXECUTION_ABANDONED`), so no worker acks without the request that started it. A repeated request for an attempt already active joins it and keeps the original requester. - `proposer` is the cosigner that created the proposal for this exact transaction. At `before_proposal_created` it equals `submitter`. At the ack it comes from the matching proposal, found by the proposal id derived from the transaction (`lookup_matching_proposal_payload`, `push_delta.rs:164,229`) **[READ]**, and is empty when there is none: a single-key account, a transaction signed offline and pushed without a stored proposal, or a proposal already deleted. That helper returns only the payload, and returns nothing on a storage error as well as on absence (`push_delta.rs:229-270`) **[READ]**, which is acceptable for dashboard metadata but not for policy: a storage fault would read as "no proposer". The pipeline instead uses a lookup returning `Result>`, where `ProposalContext` holds the proposer, its session flag and the metadata together. `Ok(None)` is absence and yields an empty `proposer`; an error is treated as an error for every module called, so `on_error` applies. - **The first creator stays the proposer.** The proposal id is derived from the transaction, so two cosigners can create the same proposal. Postgres keeps the first (`on_conflict(..).do_nothing()`, `storage/postgres.rs:1400-1404`), while the filesystem backend overwrites the stored file (`storage/filesystem.rs:704-718`) **[READ]**, which would hand attribution to the last creator. Both backends keep the first proposal and its proposer; a later create of the same id does not replace them. The filesystem backend changes to create-if-absent so modules developed against it see the same attribution as in production. Creation and signature updates become separate operations on both backends: today the filesystem backend implements `update_delta_proposal` as a re-submit (`storage/filesystem.rs:767-768`) **[READ]**, which create-if-absent would turn into a silent no-op for every cosigner signature. Create-if-absent applies only to creation; an update replaces the stored proposal and fails if it does not exist. @@ -931,7 +883,7 @@ A candidate that is discarded or superseded drops out of `pending`, so no releas **Recoverable rows.** A candidate the canonicalization worker parks as `Retained`, with any successors parked as orphans, and a client-abandoned discard (issues #345 and #319) are signed, are neither queued nor committed, and so are not in `pending`; yet the reconcile pass promotes such a row if it turns out to have landed (`promote_candidate` with `PromotableKind::Retained`, `crates/server/src/storage/mod.rs:413`) **[READ]**. Leaving them out does not let a limit be exceeded. A parked row is never the queue tail, so every delta admitted after it builds on the stored state without it (`gate_candidate_submission`, `storage/mod.rs:374`) **[READ]**, and an admitted delta at the parked row's nonce supersedes the row (`submit_candidate`, `storage/postgres.rs:1726`) **[READ]**. The parked row and any delta admitted after it share a base or descend from deltas that do, and Miden executes at most one delta per account state, so at most one of them lands. Every delta that lands was therefore evaluated with all of its ancestors counted, and a parked row that is later promoted writes its `module_events` row like any other promotion and is counted from then on **[RAN]**. What the snapshot cannot give for these rows is exactness: an evaluation may leave out a parked row that later lands instead of the delta being evaluated, which only ever undercounts a transaction that will not execute. -**Checked by model.** Sections 3.3 and 3.4 are model-checked with TLA+ (`.agents/skills/verify-module-counting/`, on the prototype branch): one account and one stateful module, concurrent `push_delta` requests, deltas executing on chain, promotion, retention and reconcile of parked rows, two replicas delivering under the notifier lease with calls and replies delayed, duplicated or lost, a replica that has lost the lease still sending, retention drops and resyncs, up to four deltas with amounts 1 and 2. Within those bounds the account never spends more than the cap, no delta is counted twice, and every queued or committed delta is counted. The same model found the resync ordering faults corrected in revision 23 (Appendix B). +**Checked by model.** Sections 3.3 and 3.4 are model-checked with TLA+ (the `verify-module-counting` skill, kept with the M2b work until M2b resumes): one account and one stateful module, concurrent `push_delta` requests, deltas executing on chain, promotion, retention and reconcile of parked rows, two replicas delivering under the notifier lease with calls and replies delayed, duplicated or lost, a replica that has lost the lease still sending, retention drops and resyncs, up to four deltas with amounts 1 and 2. Within those bounds the account never spends more than the cap, no delta is counted twice, and every queued or committed delta is counted. The same model found the resync ordering faults corrected in revision 23 (Appendix B). In optimistic mode two overlapping pushes can share a nonce (`submit_delta` upserts on `(account_id, nonce)`); the watermark then counts whichever is delivered first, one more reason stateful limits are exact only in candidate mode. @@ -939,14 +891,14 @@ In optimistic mode two overlapping pushes can share a nonce (`submit_delta` upse The list is exact for every delta that gets stored. `push_delta` reads the candidate queue (`crates/server/src/services/push_delta.rs:86`) **[READ]** before the pipeline runs and the delta is signed (`:181`), and the storage gate admits the delta under the account lock only if it extends the queue's tail (`crates/server/src/storage/mod.rs:374-399`) **[READ]**. A candidate admitted after the queue was read moves the tail, so the later delta is refused with a 409 and its signature is never returned. Two concurrent requests can both pass `evaluate`, but at most one is stored. -This argument holds in candidate mode, which the official server binary always configures (`crates/server/src/main.rs:44`, `with_canonicalization(Some(..))`) **[READ]**. With canonicalization disabled (`DeltaCommitStrategy::Optimistic`, `crates/server/src/services/delta_commit.rs:87-201`) **[READ]** there is no candidate queue and no storage gate of this kind: two overlapping pushes on the same base can both be evaluated against the same `pending` and both signatures can be returned. Both spend the same account nonce from the same state, so at most one can execute on chain, but a module may see both as committed. Stateful limits are exact only in candidate mode, and `docs/CONFIGURATION.md` will say so (section 7, docs). +This argument holds in candidate mode, which the official server binary always configures (`ServerBuilder::from_env`, `crates/server/src/builder/env.rs`, `with_canonicalization(Some(..))`) **[READ]**. With canonicalization disabled (`DeltaCommitStrategy::Optimistic`, `crates/server/src/services/delta_commit.rs:87-201`) **[READ]** there is no candidate queue and no storage gate of this kind: two overlapping pushes on the same base can both be evaluated against the same `pending` and both signatures can be returned. Both spend the same account nonce from the same state, so at most one can execute on chain, but a module may see both as committed. Stateful limits are exact only in candidate mode, and `docs/CONFIGURATION.md` will say so (section 7, docs). The execution worker (PR #510) builds `pending` from the same queue snapshot it uses for its own admission. It refuses to execute while any candidate is queued for the account (RFC 0001, revision 19), so its `pending` holds only committed entries the module has not acknowledged. Limits: - **Backlog cap.** Applies only to modules that subscribe to `after_transaction_committed`. The committed part grows while such a module is unreachable. Above `GUARDIAN_MODULE_PENDING_MAX` entries for an account (default 256), that module's `evaluate` for the account is treated as an error without being called and `on_error` applies. The candidate part is bounded by the candidate queue depth. -- **Request size cap.** `pending` bounds the entry count, not the bytes: one projection can carry many notes, and 256 of them can exceed the 4 MiB message limit most gRPC stacks apply by default (tonic's default receive limit) **[INFERRED]**. The Guardian encodes each `HookRequest` before sending it, and one larger than `GUARDIAN_MODULE_REQUEST_MAX_BYTES` (default 2 MiB) is treated as an error for that module without the call being made, so `on_error` applies, with `guardian_module_request_oversize_total{module}`. The same cap applies to registration requests, whose `initial_state` can be large. Module authors raise their server's receive limit to at least the cap; the conformance suite sends a request at the cap. +- **Request size cap.** `pending` bounds the entry count, not the bytes: one projection can carry many notes, and 256 of them can exceed the 4 MiB message limit most gRPC stacks apply by default (tonic's default receive limit) **[INFERRED]**. The Guardian encodes each `HookRequest` before sending it, and one larger than `GUARDIAN_MODULE_REQUEST_MAX_BYTES` (default 2 MiB) is refused without the call being made, whatever the instance's `on_error` (section 4.2), counted in `guardian_module_request_refused_total{module, reason = too_large}`. The same cap applies to registration requests, whose `initial_state` can be large. Module authors raise their server's receive limit to at least the cap; the conformance suite sends a request at the cap. - **Projections are stored, not recomputed.** The projection is computed once when the delta is signed and stored with the candidate and with the `module_events` row, together with the ack's `submitter` and `proposer`. Once the catalog subscribes any instance to `after_transaction_committed`, this module data is stored with every delta the Guardian signs, for every account, whether or not a subscribed module is assigned to it, so assigning a stateful module to an account later finds every queued candidate prepared. - **Activation fence.** Candidates queued before that point (signed before M2b, or by a replica still on an older catalog during a rolling deploy) carry no module data, and `pending` cannot include them faithfully: their `submitter` cannot be recovered, and a reconstructed accounting time could move them between windows. While such a candidate is queued for an account, the evaluation of every subscribed module for that account is treated as an error without the call being made, so `on_error` applies. The fence lifts when those candidates are promoted or discarded, normally within one canonicalization pass. Deployment and assignment tests cover it. The account views are not stored: they are rebuilt for each evaluation from states the Guardian holds anyway. - **No counting in `evaluate`.** Module authors keep state only from `notify`. The conformance suite evaluates the same request twice and checks that the module's state does not change. @@ -965,7 +917,6 @@ Remote modules are run by other teams and vendors and upgrade on their own sched | Capability | Meaning | |---|---| -| `decision.effect` | The Guardian reads `Decision.effect` | | `params.normalization` | The Guardian stores `ParamsVerdict.normalized_params` | | `notify` | The Guardian builds `pending` and delivers `Notify` and `NotifyGap` (M2b, section 3.4) | @@ -973,11 +924,11 @@ A stateful module requires `notify`, and a module that requires it is also refus **Supported range.** A Guardian accepts its current protocol version and, once a newer major exists, the previous one for a deprecation window of one Guardian release. For a module on the previous version it builds that version's request shape, logs a warning at startup and exports `guardian_module_protocol_deprecated{module}`, so operators see which modules to upgrade before the window closes. Two or more versions behind, or ahead of the Guardian, is refused. Version 1 is the only version until M2a freezes it, so the range is a single version for now. -**Decisions.** `Decision.effect` makes the outcome explicit, so later effects (for example a request for additional approval, section 7) can be added without a new protocol version. A module that predates the field leaves it unspecified and `allow` decides. An effect the Guardian does not recognise is a module failure, so `on_error` applies: a newer module cannot loosen policy on an older Guardian by returning something the Guardian does not understand. +**Decisions.** `Decision.effect` makes the outcome explicit, so later effects (for example a request for additional approval, section 7) can be added without a new protocol version. A decision that sets no effect, or one the Guardian does not recognise, is a module failure, so `on_error` applies: a newer module cannot loosen policy on an older Guardian by returning something the Guardian does not understand. -**Parameter migration.** Params belong to the module, which changes their shape between its own releases. `ValidateParams` may return `normalized_params`: the params in the module's current shape. The Guardian stores what the module returns. At startup and before enabling an instance, when the module normalizes the stored global params, the Guardian writes them with a history entry by `module: ` and reason "params migrated by the module", so an upgrade is a recorded data change instead of a startup failure. Operator writes store the normalized form too, and the response shows what was stored. Account layers and assignments are migrated when they are next written; until then the module receives them in the shape they were stored in, so a module must keep accepting the shapes of its previous release. Normalized params are subject to the same rules as the input: a JSON object, and no secret references through the operator API. +**Parameter migration.** Params belong to the module, which changes their shape between its own releases. `ValidateParams` may return `normalized_params`: the params in the module's current shape. The Guardian stores what the module returns. At startup, before enabling an instance, and when an instance whose module was unreachable at startup passes its delayed checks, when the module normalizes the stored global params, the Guardian writes them with a history entry by `module: ` and reason "params migrated by the module", so an upgrade is a recorded data change instead of a startup failure. Operator writes store the normalized form too, and the response shows what was stored. Account layers and assignments are migrated when they are next written; until then the module receives them in the shape they were stored in, so a module must keep accepting the shapes of its previous release. Normalized params are subject to the same rules as the input: a JSON object, and no secret references through the operator API. -**SDK compatibility.** `guardian-module-sdk` follows semantic versioning, and a protocol version change is a major SDK release. Types the SDK owns are `#[non_exhaustive]` with constructors (`ModuleInstanceConfig::new(..).with_endpoint(..)`, `ModuleTls::new`, `ClientIdentity::new`), so new fields do not break module code. Generated protocol types grow with new fields; module code builds them with `..Default::default()` or the SDK helpers (`Decision::allow`, `Decision::deny`, `ParamsVerdict::ok`, `ParamsVerdict::invalid`, `ParamsVerdict::normalized`). New trait methods get default bodies, as `notify` and `notify_gap` have. +**SDK compatibility.** `guardian-module-sdk` follows semantic versioning, and a protocol version change is a major SDK release. Types the SDK owns are `#[non_exhaustive]` with constructors (`ModuleInstanceConfig::new(..).with_endpoint(..)`, `ModuleTls::new`, `ClientIdentity::new`), so new fields do not break module code. Generated protocol types grow with new fields; module code builds them with `..Default::default()` or the SDK helpers (`Decision::allow`, `Decision::deny`, `ParamsVerdict::ok`, `ParamsVerdict::invalid`, `ParamsVerdict::normalized`). New trait methods get default bodies, as `notify` and `notify_gap` will when M2b adds them. ## 4. Errors and failure handling @@ -988,9 +939,9 @@ Both use the `{ code, message, meta }` envelope. | Code | HTTP | gRPC | Retryable | `meta` | |---|---|---|---|---| | `GUARDIAN_MODULE_DENIED` | 403 | `PERMISSION_DENIED` | no | `{ module, reason_code, layer }` | -| `GUARDIAN_MODULE_UNAVAILABLE` | 503 | `UNAVAILABLE` | yes | `{ module }` | +| `GUARDIAN_MODULE_UNAVAILABLE` | 503 | `UNAVAILABLE` | yes | `{ module }`, empty for an instance with `client_reason = "generic"`, so a failure names no more than a denial would | -On a deny, `reason_code` must match `[a-z0-9_]{1,64}`; a deny without a conforming code is a protocol error and follows `on_error`. On an allow, `reason_code` is ignored and may be empty, so an allow is never turned into an error by a missing code. The module's free-text `message` is logged but not forwarded to clients: a module may be a third party and should not place arbitrary text in front of end users. `meta.module` is the instance `id` from the catalog, which the operator chooses: an operator who does not want to reveal which vendor screens its traffic names the instance neutrally (for example `compliance-1`), and the vendor's kind name never reaches clients. The Rust and TypeScript SDKs expose both as typed errors with the same retry classification. A denial at `before_proposal_created` uses the same codes on the proposal creation call, and the proposal is not stored; both SDKs surface it from proposal creation with the same typed error, so a proposer sees the refusal before any cosigner signs. On the execution path (PR #510) a denial ends the execution with a typed abort reason `module_denied` carrying the same `{ module, reason_code, layer }`, and module unavailability with `module_unavailable`; both multisig SDKs read these from the execution status. +On a deny, `reason_code` must match `[a-z0-9_]{1,64}`. A deny without a conforming code is still a deny, reported with the generic code `policy_denied` and a WARN log naming the module's code: treating it as a protocol error would let an instance with `on_error = "allow"` sign what its module explicitly refused. On an allow, `reason_code` is ignored and may be empty, so an allow is never turned into an error by a missing code. The module's free-text `message` is logged but not forwarded to clients: a module may be a third party and should not place arbitrary text in front of end users. `meta.module` is the instance `id` from the catalog, which the operator chooses: an operator who does not want to reveal which vendor screens its traffic names the instance neutrally (for example `compliance-1`), and the vendor's kind name never reaches clients. The Rust and TypeScript SDKs expose both as typed errors with the same retry classification. A denial at `before_proposal_created` uses the same codes on the proposal creation call, and the proposal is not stored; both SDKs surface it from proposal creation with the same typed error, so a proposer sees the refusal before any cosigner signs. On the execution path (PR #510) a denial ends the execution as `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED`, whose `meta` carries the same `{ module, reason_code, layer }` and `client_message` (a generic denial carries only `reason_code: policy_denied`), and module unavailability with `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module`). Neither deletes the proposal, and nothing is proved or sent. Both multisig SDKs read them as typed failure codes from the execution status. **Generic denials.** For an instance with `client_reason = "generic"` (section 2.7), a denial reaches the client as `GUARDIAN_MODULE_DENIED` with `meta = { reason_code: "policy_denied" }`: no module, no module reason code, no layer, and no `client_message`. The full decision is logged and recorded as for any other denial, so operators still see which module refused and why. A client cannot tell a generic denial from one module from a generic denial from another. @@ -998,11 +949,15 @@ On a deny, `reason_code` must match `[a-z0-9_]{1,64}`; a deny without a conformi | Situation | `on_error = deny` | `on_error = allow` | |---|---|---| -| Timeout, transport error, malformed decision, unknown protocol version, stale state, pending backlog over the cap, request over the size cap, circuit open (section 4.4), account view extraction or proposal lookup failed (section 3.2) | `GUARDIAN_MODULE_UNAVAILABLE` | Continue; WARN log; `guardian_module_fail_open_total{module}` | +| Timeout, transport error, a decision with no known effect, unknown protocol version, stale state, pending backlog over the cap, circuit open (section 4.4) | `GUARDIAN_MODULE_UNAVAILABLE` | Continue; WARN log; `guardian_module_fail_open_total{module}` | +| The request could not be built: account view or projection extraction, or the proposal lookup or stored state read, failed (section 3.2) | `GUARDIAN_MODULE_UNAVAILABLE` | same: refused, not continued | +| Request over the size cap (section 3.4) | `GUARDIAN_MODULE_DENIED` with `reason_code = request_too_large` (generic denial for a generic instance) | same: refused, not continued | | `resync_required` set for the account, or a resync waiting for the module to acknowledge `NotifyGap` (section 3.3) | `GUARDIAN_MODULE_UNAVAILABLE` | Continue; WARN log; `guardian_module_fail_open_total{module}` | | Notify failure | Never affects requests; retried; `guardian_module_notify_lag_seconds{module}` drives an alarm | same | -A fail-closed module is a dependency on the approval path: when it is down, approvals stop for every account it applies to. That is intended for compliance and is why `on_error` is per module. The circuit breaker in section 4.4 makes that outcome immediate instead of costing a full timeout per request. +A fail-closed module is a dependency on the approval path: when it is down, approvals stop for every account it applies to. That is intended for compliance and is why `on_error` is per module. `on_error` covers the module's own failures only. A request the Guardian cannot build or that exceeds the size cap is shaped by the requester (a transaction padded with notes, an initial state the view extraction cannot read), so letting it through would let any requester switch fail-open instances off for their own transactions; both are refused whatever `on_error` says. One that cannot be built is refused as unavailable, since some causes are transient (the chain fee not loaded yet, a storage read that failed); one over the cap is denied, since resending it cannot succeed. Revisions before 32 let both through a fail-open instance. The circuit breaker in section 4.4 makes a fail-closed module's outage immediate instead of costing a full timeout per request. + +**Guardian execution.** A threshold-met proposal that Guardian executes is judged at its ack in the execution worker, after the execution is reserved and prepared, so a denial ends that attempt as failed (`ExecutionFailureCode::ModuleDenied`) and the proposal is kept. Deciding earlier, in the execution request, was considered and not adopted: the ack is the enforcement point and must decide anyway, so an earlier call would be a second evaluation of the same transaction, with its cost, a possibly different answer, and double counting once stateful modules (M2b) count what they evaluate. The failed attempt is the record of the denial. **Break-glass.** An instance with `operator_can_disable = true` is stopped with `POST /dashboard/modules/{module_id}/disable`. One without it can only be changed by a deploy: set `on_error = "allow"` or `operator_can_disable = true`, or remove the instance from the catalog. Editing its `enabled` field does nothing after the first seed (section 2.2), and once M2b ships, removing a subscribed instance and adding it back leaves its accounts in `resync_required` (section 3.3). The operator documentation carries this as a runbook, so the path is known before an outage. @@ -1013,21 +968,23 @@ Every evaluation records `guardian_module_evaluate_duration_seconds{module, outc Modules run in sequence, so their timeouts add up, while the execution worker holds its reservation lease (RFC 0001) and a client calling `push_delta` has its own request deadline. Sequential evaluation is kept on purpose. Calling independent modules in parallel would cut latency to the slowest module, but every module would receive the transaction even when an earlier one denies, which widens the disclosure in invariant 5 to vendors whose answer is not needed, and "first deny wins" would depend on timing rather than order. Operators keep latency down through per-module timeouts and the budget instead. A per-request budget bounds the total: - `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` (default 1000) limits the time spent in module calls for one hook invocation. This is the user-facing approval path, so the default allows a couple of remote modules at a few hundred milliseconds each, in line with external authorization deployments such as Envoy `ext_authz` (200 ms default timeout). The implementation plan records the measured `push_delta` p99 with the reference module and a remote module, and the default is revisited against it. -- Request assembly (account views and projection) is not module time and is not charged to the budget; it is bounded by the reconstruction task instead (section 3.2). That pool is shared with delta reconstruction, so assembly moved into it competes with pushes under load; M2a measures throughput at concurrency before and after the move. +- Request assembly is not module time and is not charged to the budget. The account views and the projection it uses are built by the request's own reconstruction decode, inside the reconstruction task (section 3.2), so they are bounded by that pool and add no decode of their own; assembly itself only copies them. Measured before and after in `speckit/features/251-guardian-modules/research.md`. - At runtime each module call gets the smaller of its own `timeout_ms` and the time left in the budget. A call cut short by the budget counts as a timeout, and its `on_error` applies. - At startup in the prod stage, the server refuses to start if, for any hook, the timeouts of the `all` and `default` instances, enabled or not, add up to more than the budget (the set every new account receives, which carries no account layers yet; disabled instances are counted because enabling needs no further check), or if the budget is not below the execution reservation lease. `assigned` instances are not summed at startup: a catalog may declare many optional instances that no account uses together. -- Per account, `PUT /dashboard/accounts/{account_id}/modules` rejects an assignment, and the account-layer `PUT` rejects a layer, whose effective set (`all` instances plus their account layers, which are a second call each, plus the listed ones) exceeds the budget on any hook (section 2.2). These static checks cover new accounts and new assignments only. A later deploy that raises a `timeout_ms`, adds an `all` instance, or brings back an orphaned id can push an account that fit at `PUT` time over budget; nothing re-validates stored assignments then. The runtime budget is the enforcement: once it is spent, later modules count as timed out and their `on_error` applies. At startup the server lists every account whose stored assignment and account layers exceed the budget (log and `guardian_module_over_budget_accounts`) without refusing to start, so a routine deploy cannot become an outage, and operators fix those assignments through the operator API. +- Per account, `PUT /dashboard/accounts/{account_id}/modules` rejects an assignment, and the account-layer `PUT` rejects a layer, whose effective set (`all` instances plus their account layers, which are a second call each, plus the listed ones) exceeds the budget on a hook where the account's current set does not already cost at least as much (section 2.2): a write that keeps or lowers the cost passes, so the operator API can bring back under the budget an account that a deploy raising a timeout pushed over it. These static checks cover new accounts and new assignments only. A later deploy that raises a `timeout_ms`, adds an `all` instance, or brings back an orphaned id can push an account that fit at `PUT` time over budget; nothing re-validates stored assignments then. The runtime budget is the enforcement: once it is spent, later modules count as timed out and their `on_error` applies. At startup the server lists every account whose stored assignment and account layers exceed the budget (log and `guardian_module_over_budget_accounts`) without refusing to start, so a routine deploy cannot become an outage, and operators fix those assignments through the operator API. - SDK request timeouts must exceed the budget; otherwise a slow approval arrives after the client has retried. `docs/CONFIGURATION.md` and both SDK docs state this. ### 4.4 Circuit breaker and health probe Without a breaker, a module that is down costs its full `timeout_ms` on every request until an operator acts, for fail-closed and fail-open instances alike. Each replica therefore keeps a breaker per instance: -- **Closed** (normal): calls go through. `GUARDIAN_MODULE_BREAKER_FAILURES` consecutive failures (default 5) open it. Timeouts, transport errors and malformed decisions count as failures; a deny is an answer, not a failure, and resets the count. +- **Closed** (normal): calls go through. `GUARDIAN_MODULE_BREAKER_FAILURES` consecutive failures (default 5) open it. Timeouts, transport errors and decisions with no known effect count as failures; a deny, even one with a malformed reason code, is an answer, not a failure, and resets the count. So does a request the module rejects as one it cannot judge (`ModuleError::InvalidRequest`, gRPC `INVALID_ARGUMENT`): the instance's `on_error` applies to that request, but it says nothing about whether the module is up, so one account's unjudgeable requests cannot stop the module for every account. A timeout does not count when earlier modules in the same invocation left the call less than its `timeout_ms`, and nothing a dry-run check does counts or resets anything, since a cosigner sends it without anyone's signature. - **Open**: `evaluate` is not called; the module is treated as failed for every account and its `on_error` applies at once, so a fail-closed module refuses with `GUARDIAN_MODULE_UNAVAILABLE` without waiting and a fail-open module is skipped. -- **Half-open**: a successful health probe moves an open breaker here. The next real evaluation is sent; success closes the breaker, failure opens it again. +- **Half-open**: a successful health probe moves an open breaker here. One real evaluation at a time is sent as the trial, and requests arriving meanwhile, and every dry-run check, are treated as while open; an answer closes the breaker, a failure opens it again, and a trial that never reports back (its request was dropped) is replaced at the next successful probe. + +The breaker is per instance, not per (instance, hook). Splitting it by hook was considered and not adopted: every hook is reachable by anyone holding an account, on their own account (registering it, proposing on it, pushing to it), so a separate breaker for `before_transaction_approved` would not keep a requester from driving failures into it. What contains a requester is that request-specific outcomes do not count: a request the module rejects as one it cannot judge, a dry run, a call cut short by the budget, and a request the Guardian cannot build or that exceeds the size cap (refused before any call, section 4.2). Per-hook state stays an option if a module shows different failure behaviour per hook. -The health probe is a `Describe` call every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` (default 5000) for every enabled instance, open breaker or not, under the instance's `timeout_ms`. It sets `guardian_module_up{module}`, so an outage raises an alarm before traffic finds it, and it also detects a module whose `protocol_version` changed under a running Guardian (treated as a failure). A module receives about one `Describe` per instance per replica every interval, so it answers `Describe` from memory, without calling a vendor or a database. Breaker state is per replica and in memory: replicas converge independently within a few requests, and nothing about it is stored. Until they do, a fail-open instance can be skipped on one replica and called on another; `failed_open` in the evaluation trace records each skip (section 2.2). `guardian_module_circuit_open{module}` is exported, and `GET /dashboard/modules` shows the answering replica's state. Notify delivery is unaffected; it has its own retry with backoff (section 3.3). In-process kinds go through the same breaker, so a kind that calls a vendor API behaves like a remote one. +The health probe is a `Describe` call every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` (default 5000) for every enabled instance, open breaker or not, under the instance's `timeout_ms`. It sets `guardian_module_up{module}`, so an outage raises an alarm before traffic finds it, and it feeds the breaker: a probe that gets no answer counts as a failed call, and a probe that finds the module answering with a protocol version, a required capability or a hook set this Guardian cannot work with (a module redeployed under a running Guardian) opens the breaker at once and keeps it open until a probe passes, since that module's decisions cannot be trusted either. A module receives about one `Describe` per instance per replica every interval, so it answers `Describe` from memory, without calling a vendor or a database. Breaker state is per replica and in memory: replicas converge independently within a few requests, and nothing about it is stored. Until they do, a fail-open instance can be skipped on one replica and called on another; `failed_open` in the evaluation trace records each skip (section 2.2). `guardian_module_circuit_open{module}` is exported, and `GET /dashboard/modules` shows the answering replica's state. Notify delivery is unaffected; it has its own retry with backoff (section 3.3). In-process kinds go through the same breaker, so a kind that calls a vendor API behaves like a remote one. --- @@ -1040,7 +997,7 @@ The health probe is a `Describe` call every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` 3. **Exit is never gated.** `SwitchGuardian` executes on chain without a Guardian acknowledgement, so no module can keep an account from leaving. A module may deny the best-effort push of the switch delta to the old Guardian; the release sweep then detects the switch from chain. 4. **Structure is reviewed, parameters are audited.** Only the catalog file, applied by a deploy, adds, removes or reconfigures module instances (kind, endpoint, authentication, TLS, hooks, scope, timeout, `on_error`), so no session can point the approval path or transaction data at a new destination. Params are operator-managed: operator sessions change global params (`policies:write_global`), account layers and per-account assignments, every change with a reason, an audit record and a history entry. Loosening a rule through params is an operator decision the audit trail records, not something the Guardian prevents; what it does prevent is a per-account change weakening an `all` rule, since an account layer only adds restrictions. `scope = all` instances cannot be removed from an account, only instances the catalog marks `operator_can_disable` can be disabled, and resync accepts dropped history explicitly. 5. **Disclosure.** Every external module receives the full transaction details of each account it applies to, including, for instances subscribed to `before_proposal_created` and for every instance a dry-run check reaches, transactions that are never executed, and the proposer's free-text `description` in `unverified_metadata`. This is a change to the trust boundary in `docs/CONCEPTS.md` and operators must treat module vendors as data processors. The operator and module author guides (section 7) say which request fields can carry personal data, ask vendors to document retention and processing location, and note that the Guardian's own logs hold the module's `message` for every denial. -6. **A verdict assumes the account's code.** Modules judge the transaction and the account views; the account's code decides whether the Guardian's signature is required at all. The Guardian does not verify that code (section 3.2), so an operator who relies on module verdicts as a custody control pins the code with a module, through `code_commitment` at registration and `new_code_commitment` on every transaction. `basic-policy` does this with `allowed_code_commitments` (section 3.1); `code_check = "all"` also covers accounts registered before the rule existed. Without such a rule, a code upgrade can remove the Guardian requirement from an account and no module runs for it again. +6. **A verdict assumes the account's code.** Modules judge the transaction and the account views; the account's code decides whether the Guardian's signature is required at all. The Guardian does not verify that code (section 3.2), so an operator who relies on module verdicts as a custody control pins the code with a module, through `code_commitment` at registration and `new_code_commitment` on every transaction. `code-policy` does this with `allowed` (section 3.1); `check = "all"` also covers accounts registered before the rule existed. Without such a rule, a code upgrade can remove the Guardian requirement from an account and no module runs for it again. ### 5.2 Transport authentication @@ -1048,10 +1005,10 @@ The health probe is a `Describe` call every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` - In the prod stage, `auth` is mandatory for remote kinds; a remote instance without it stops startup. - The Guardian sends a per-module bearer token (gRPC metadata `authorization`, HTTP `Authorization` header) read from the secrets backend, so the module can reject callers that are not this Guardian. Without it, anyone could probe the module or forge commit events that corrupt its counters. - The Guardian authenticates the module through TLS server authentication, against the system roots or the instance's `tls.ca_file`. -- mTLS is an optional per-instance setting (`tls.client_cert`, `tls.client_key`, both secret references) for operators who already run a CA. +- mTLS is an optional per-instance setting (`tls.client_cert_secret`, `tls.client_key_secret`, both secret names) for operators who already run a CA. - The bearer token and client key are held in secret types: redacted from logs and debug output, and zeroized when dropped. - No Guardian signing key is reused for module authentication. -- Replaying a captured `CommitEvent` cannot change a module's state: its nonce is at or below the module's watermark, so it is acknowledged without effect (section 3.3). Forging a new event requires the bearer token. Signing each request body with a timestamp (the Standard Webhooks pattern) was considered; with a shared secret it adds only that the secret itself is never sent, which mTLS already provides for operators who need it. +- With M2b, replaying a captured `CommitEvent` cannot change a module's state: its nonce is at or below the module's watermark, so it is acknowledged without effect (section 3.3). Forging a new event requires the bearer token. Signing each request body with a timestamp (the Standard Webhooks pattern) was considered; with a shared secret it adds only that the secret itself is never sent, which mTLS already provides for operators who need it. ### 5.3 Disclosure and probing @@ -1089,11 +1046,13 @@ The first enclave step allows in-process kinds only; the attested tier follows o **First implementation (milestone M2), in three steps.** Each step ships and can be operated on its own. M2a covers stateless gates (sanctions, allowlists, per-transaction caps), which most deployments need first; M2b adds the machinery that makes stateful limits exact; M2c opens the server to operator-built kinds. -**Dependency on PR #510.** PR #510 has merged (`1100f3a4`), so M2a can start: the pipeline is placed once, in the shared `acknowledge_delta`, rather than in `push_delta` and moved later. Recording the requester on execution reservations (section 3.2) is M2a work on top of #510, not a change requested of it. +**Dependency on PR #510.** PR #510 has merged (`1100f3a4`), so M2a can start: the pipeline is placed once, in the shared `acknowledge_delta`, rather than in `push_delta` and moved later. Carrying the authenticated requester to the ack (section 3.2) is M2a work on top of #510, not a change requested of it. -**Protocol version 1 is fixed at M2a.** The full `guardian.module.v1` proto above, including `Notify`, `NotifyGap`, `pending`, `accounting_time` and the watermark fields, is published with M2a, so modules written against M2a need no change when M2b ships. In M2a the Guardian sends an empty `pending`, never calls `Notify` or `NotifyGap`, does not offer the `notify` capability, and refuses at startup a catalog that subscribes an instance to `after_transaction_committed`, so a stateful module cannot start on it (section 3.5). +**Protocol version 1 is fixed at M2a.** The `guardian.module.v1` proto above is published with M2a and carries the stateless contract only. M2b adds `Notify`, `NotifyGap`, `pending`, the watermark fields and the `after_transaction_committed` hook as the `notify` capability within version 1 (section 3.5), additively, so modules written against M2a need no change when M2b ships. The M2a Guardian does not offer that capability and refuses at startup a catalog that subscribes an instance to `after_transaction_committed`, so a stateful module cannot start on it. -**Freeze criteria.** Version 1 freezes only once the prototype implements, with tests, the protocol surface added in revision 24 that is so far derived from reading code: the renumbered proto, registration before the claim (new account, unfinished claim, lost claim), `network_id`, `code_commitment` and `procedure_roots` with effective-override filtering (non-zero, exported, not the auth procedure), `reference_block` and the optional `expiration_block`, `new_code_commitment`, `submitter_session` and `proposer_session` stored with the proposal, `dry_run` with approval instances in the check, and the `allowed_code_commitments` rule with `code_check`. Extraction details are where the prototype found errors before (the fee note, single-key views), so these are measured against real accounts, not only fixtures. +**Freeze criteria.** Version 1 freezes only once the prototype implements, with tests, the protocol surface added in revision 24 that is so far derived from reading code: the renumbered proto, registration before the claim (new account, unfinished claim, lost claim), `network_id`, `code_commitment` and `procedure_roots` with effective-override filtering (non-zero, exported, not the auth procedure), `reference_block` and the optional `expiration_block`, `new_code_commitment`, `submitter_session`, `dry_run` with approval instances in the check, and the `allowed_code_commitments` rule with `code_check`. Extraction details are where the prototype found errors before (the fee note, single-key views), so these are measured against real accounts, not only fixtures. + +**Not frozen yet.** The freeze criteria were met on 2026-11-09 at `e4efd839` on the M2a branch `251-modules-m2a` and revision 28 declared version 1 frozen. A review of the implementation the next day found fields that did not carry what they said (`network_id`, `reference_block`, `expiration_block`), one that was never sent (`RegistrationSubject.initial_state`) and a legacy `Decision.allow` in a protocol with no predecessor, so revision 32 reopened it: nothing had been published or deployed, which is the only point at which a freeze costs anything to undo. Version 1 freezes with the first published `guardian-module-sdk` release; from then on `guardian.module.v1` changes only additively (section 3.5). The messages no M2a code produces or consumes (`Notify`, `NotifyGap`, `CommitEvent`, `Gap`, `PendingTransaction`) stay in the proto as the M2b design and may still change until M2b implements them. **M2a: stateless gates.** @@ -1106,12 +1065,12 @@ The first enclave step allows in-process kinds only; the attested tier follows o - Evaluation budget (`GUARDIAN_MODULE_EVALUATION_BUDGET_MS`) with the startup checks in section 4.3, circuit breaker and health probe (section 4.4), request size cap (section 3.4), and the module metrics. - `GUARDIAN_MODULE_DENIED` and `GUARDIAN_MODULE_UNAVAILABLE` in the server and both SDKs, on proposal creation as well as on the ack. - Policy discovery (section 2.7): the `disclosure`, `description`, `client_reason` and `dry_run` catalog fields, generic denials, `Decision.client_message`, the policy summary and dry-run check on the client API with their rate limit, and the SDK methods named in section 2.7 in both base clients and both multisig SDKs. The error contract and the protocol field must land before version 1 freezes; the two endpoints may follow in an M2a point release. -- Reference module `basic-policy` (recipient allowlist and denylist, asset allowlist, per-transaction amount cap, signer allowlist or denylist with `signer_check`, account code allowlist), shipped as a first-party in-process kind and, through the `serve` harness, as a standalone gRPC service in `examples/policy-module/`. -- Account view extraction with explicit errors for unsupported auth state, effective procedure overrides, code commitment and procedure roots; `network_id`, `reference_block` and `new_code_commitment` in the projection (section 3.1); `submitter_session`, and `proposer_session` stored with the proposal (section 3.2); the params size cap (section 2.2); the `ProposalContext` lookup, first-creator-wins proposal storage on both backends, and the requester recorded on execution reservations (section 3.2). -- Acceptance cases: a denial at proposal creation stores nothing and takes no slot; a proposal that passes creation and is denied at the ack; a transaction signed offline and pushed without a stored proposal is enforced at the ack; forged `unverified_metadata` does not change a decision; a failed account view extraction applies `on_error`. Creation denials are exercised through `guardian-client` (Rust and TypeScript) and both multisig SDKs. +- Reference policies `spending-limit`, `recipient-policy`, `signer-policy` and `code-policy` (per-transaction amount cap and asset allowlist; recipient allowlist or denylist; signer allowlist or denylist; account code allowlist), shipped as first-party in-process kinds and, through the `serve` harness, as a standalone gRPC service in `examples/policy-module/`. +- Account view extraction with explicit errors for unsupported auth state, effective procedure overrides, code commitment and procedure roots; `network_id`, `reference_block` and `new_code_commitment` in the projection (section 3.1); `submitter_session` (section 3.2); the params size cap (section 2.2); the `ProposalContext` lookup, first-creator-wins proposal storage on both backends (on `main`, `admit_delta_proposal` refuses an existing commitment on both), and the requester carried from the execution request to the ack (section 3.2). +- Acceptance cases: a denial at proposal creation stores nothing and takes no slot; a proposal that passes creation and is denied at the ack; a transaction signed offline and pushed without a stored proposal is enforced at the ack; forged `unverified_metadata` does not change a decision; a failed account view extraction is refused as unavailable whatever `on_error` says (section 4.2). Creation denials are exercised through `guardian-client` (Rust and TypeScript) and both multisig SDKs. - Docs: configuration, trust boundary in concepts, troubleshooting codes (including the denial log fields, section 2.2), the break-glass runbook (section 4.2), data-protection guidance for operators and vendors (invariant 5), and a module author guide for remote modules. -**M2b: stateful limits.** Unblocks the stateful policies of #182. +**M2b: stateful limits.** Unblocks the stateful policies of #182. **Deferred past the first release.** Implementing everything below showed it to be a delivery system of its own (outbox, per-pair cursors, a fenced notifier, retention, resync, subscription tracking across replicas): every commit path must keep writing its outbox in the same transaction, and two independent reviews of that implementation found six ways to lose counts silently. The first release therefore ships stateless gates only, and a catalog subscribing an instance to `after_transaction_committed` keeps refusing startup. Section 9 records the alternative to weigh before M2b is picked up again. - The `after_transaction_committed` hook, the `module_events` outbox on Postgres (candidate and optimistic commit paths), and the notifier on the leadership lease with per-account ordering and the delivery watermark. - `pending` in every `evaluate` request with the backlog cap, `accounting_time`, and `require_fresh_state_ms`. @@ -1120,10 +1079,10 @@ The first enclave step allows in-process kinds only; the attested tier follows o - The `notify` capability and its startup check (section 3.5), the `StatefulModule` watermark helper, and the counting and failover conformance cases in section 3.4. - Docs: stateful limits are exact only in candidate mode (section 3.4). -**M2c: operator-built kinds.** +**M2c: operator-built kinds.** Implemented on `251-modules-m2a` (revision 33). -- `ServerBuilder::from_env()` (environment wiring moved out of `main.rs`) and `ServerBuilder::with_module_kind`, with the semver commitment in section 2.5. -- `custom-guardian` template shipped with each release (manifest, `main.rs`, `Dockerfile`, release `Cargo.lock`), and the example custom build in `examples/custom-guardian/`. +- `ServerBuilder::from_env()` (environment wiring moved out of `main.rs`) and `ServerBuilder::with_module_kind`, with the semver commitment in section 2.5. `build` and `from_env` return `BuildError`, a `std::error::Error`, so a custom `main` can use `?`. +- `custom-guardian` template shipped with each release (manifest, `main.rs`, `Dockerfile`, release `Cargo.lock`) by the `Custom Guardian Template` workflow, and the example custom build in `examples/custom-guardian/`, from which the template is built. - Docs: the in-process path of the module author guide. **Future work:** @@ -1175,7 +1134,9 @@ The first enclave step allows in-process kinds only; the attested tier follows o ## 9. Open questions -None. Questions resolved in earlier revisions are kept below with their answers. +1. **How stateful limits are delivered (revision 34).** M2b as designed above keeps counters in the module, fed by commit notifications. An alternative covers most of the #238 policies with far less machinery: the Guardian lists in each request the account's own transactions signed within a bounded window (for example 24 hours or 7 days), read in the same snapshot as the candidate queue, and the module recomputes its limit from that list on every evaluation. It needs no outbox, cursors, notifier, retention or resync, keeps modules stateless, works on both backends, and is exact by the same queue-tail argument as section 3.4. It cannot express limits with no time bound or modules that must act when a transaction commits, and the request grows with the window. Decide between the two, or a combination, before M2b resumes. + +Questions resolved in earlier revisions are kept below with their answers. ### Questions resolved in revision 11 @@ -1206,6 +1167,16 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| +| 35 | 2026-11-17 | Red-team fixes. A P2IDE note names a reclaimer, chosen freely by its creator, that can consume it once its reclaim height is reached; `OutputNote.reclaimer` now carries it, and `recipient-policy` judges it like the target unless it is the paying account, closing a payment to a blocked account through an allowed target (section 3.2). A deny with a reason code outside the rule is now a deny reported as `policy_denied`, not a protocol error under `on_error`, which let a fail-open instance sign what its module refused (section 4.1). A registration by a key the account does not list is vouched for before `before_account_registered` runs (section 2.3). `HookRequest.account_id` is now always lowercase, as section 3.1 states. `seeded_params` stores the catalog value as written, so a module that normalizes it no longer reports drift. Operator writes accept an optional expected version (section 2.2). The stateful (M2b) parts of the protocol are removed from version 1 as first published (the `Notify` and `NotifyGap` RPCs, `CommitEvent`, `Gap`, `NotifyAck`, `TransactionSubject.pending`, the `after_transaction_committed` hook, and the `notify` trait methods); M2b adds them back as a capability (section 3). An instance whose params move out of the catalog file adopts the new catalog params instead of running with the empty placeholder (section 2.2). A `default` instance disabled when an account registers is still copied to it (section 2.3). A late answer no longer closes an open breaker (section 4.4). Protocol change: one optional field | +| 34 | 2026-11-12 | M2b deferred past the first release (section 7); the windowed-history alternative recorded as open question 1 (section 9). Fixed: an unfinished claim an operator had already configured (a layer, an emptied assignment) was judged by the `default` instances, which were then not copied, so they never ran for it; it is now judged as configured, by the same rule as the copy (section 2.3). No protocol change: the M2b messages stay in the proto and may still change until a stateful design is implemented | +| 33 | 2026-11-12 | M2c implemented (section 7): `ServerBuilder::from_env()` holds the environment wiring the official binary used to inline, so its `main.rs` and every custom build share it; `build` and `from_env` return `BuildError`, a `std::error::Error`. `examples/custom-guardian` replaces the server's `custom_module_server` example and is the source of the per-release template, which a release workflow builds, checks with a `--locked` Docker build and attaches as `custom-guardian-.tar.gz` (section 2.5). No protocol change | +| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Startup: a known instance whose module does not answer starts unavailable instead of stopping the server, and an instance the catalog declares enabled and not operator-disableable is enabled even when stored as disabled (section 2.2). `basic-policy`: per-field id lengths, and `deny_unknown_recipients` defaults to on once the denylist names anyone (section 3.1). The conformance suite checks stated outcomes and needs a request the module must deny. `basic-policy` is split into four kinds with short param names: `spending-limit` (`max_per_transaction`, `allowed_assets`), `recipient-policy` (`allowlist`, `denylist`, `deny_unknown`), `signer-policy` (`allowlist`, `denylist`, `check`) and `code-policy` (`allowed`, `check`), each supporting only the hooks where its rule can refuse (section 3.1). SDKs: a check and a creation send the same unsigned draft, and Rust checks custom proposals (section 2.7). Requests the Guardian cannot build or that exceed the size cap are refused whatever `on_error` says, so a requester cannot switch fail-open instances off (section 4.2); per-(instance, hook) breakers and an early execution check were considered and not adopted (section 4.4, Guardian execution). Module inputs: the views and the projection come from the decode that verifies and applies the delta, or, at registration, from one decode of each state, all inside the reconstruction task; the per-replica view cache is removed, and the ack reads the plan first so no inputs are built when no module applies (sections 3.2, 4.3). Per-account params versions: a write to one account's layers or assignment, including the default copy at registration, moves only that account's version and locks only its row, so it neither waits for other accounts nor invalidates the replicas' instance cache; each signed delta records `params_version` (instances) and `account_params_version`, and the params history pages by entry id (section 2.2). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | +| 31 | 2026-11-09 | failures of dry-run checks do not count toward the circuit breaker, since a cosigner sends them without anyone's signature (section 4.4); the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | +| 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | +| 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | +| 28 | 2026-11-09 | protocol version 1 frozen: the freeze criteria of section 7 met at `e4efd839` on `251-modules-m2a`, with tests; the proto copies say so. No design change | +| 27 | 2026-11-09 | `proposer_session` removed from `TransactionSubject`, `PendingTransaction` and `CommitEvent`, and `unverified_metadata` renumbered to 5 before the freeze: a session key cannot approve a proposal, so whether one created it adds nothing the threshold does not already require, and no catalog policy uses it; version 1 can add it later. Section 3.2 corrected for #580: `push_delta` and Guardian execution accept session credentials, so `submitter_session` can be true at the ack. Freeze criteria and the M2a list updated (section 7) | +| 26 | 2026-11-09 | `main` (mixed-scheme accounts, #565) merged into the prototype. `AccountView.signer_schemes` (signer commitment to `falcon` or `ecdsa`), decoded per approver from state, and `auth_scheme` redefined as the signers' common scheme or `mixed`, because "one scheme per account" no longer holds (section 3.2). The execution path's refusals named as `GUARDIAN_EXECUTION_MODULE_DENIED` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` failure codes (section 4.1). The execution requester is carried to the ack, not stored on the reservation, since pre-boundary attempts are never resumed (sections 3.2 and 7) | | 25 | 2026-11-03 | status moved from Open for comment to Accepted for implementation on merge of PR #544; RFC 0001 links point at its merged copy and section 7 records that PR #510 has merged; review-sought and code-baseline rows updated to match. No design change | | 24 | 2026-10-21 | three review rounds on PR #544, `main` merged in and citations re-pinned to `ca503704` and Miden 0.17.1. Protocol: registration rewritten for the account claim of #558 (section 2.3); `network_id`; `code_commitment`, `procedure_roots`, effective `procedure_thresholds` and `new_code_commitment`, with invariant 6 and the `basic-policy` code allowlist; `reference_block` and optional `expiration_block`; `submitter_session`; `request_id` defined; proto renumbered for version 1; `notify` capability (section 3.5); freeze criteria (section 7). `proposer_session` stored with the proposal; `dry_run`, with approval instances run by the policy check and `complete` derived from the catalog; `code_check`; reassignment enters `resync_required`. Semantics: `params_drift` against `seeded_params`; params size cap; paginated history; `default` copies take the evaluated params. Writing: contents, terms, registration out of the hook table, `basic-policy` table with reason codes, policy summary example, notify and resync sequence diagram, break-glass and denial-log notes | | 23 | 2026-10-19 | resync ordering (sections 3.3, 3.4, 4.2), found by a TLA+ model of the notify and `pending` design: a resync keeps the (module, account) pair refused until the module has acknowledged `NotifyGap`, and failed Gap calls are retried rather than skipped; the Gap obligation is stored with the delivery cursor, and no replica sends an event while it is open, because a replica that has lost the lease could otherwise deliver an event committed after the resync ahead of the Gap and the module would skip its reset; `resume_from_nonce` defined from the last skipped event; the false claim that a stale leader only has pre-resync events in flight corrected (Appendix B); `Retained` and client-abandoned rows stated to be outside `pending`, with the argument that a limit still holds; model-checked claims tagged **[RAN]**; resync conformance cases | diff --git a/docs/rfcs/README.md b/docs/rfcs/README.md index 2934fedf1..c7e471c3c 100644 --- a/docs/rfcs/README.md +++ b/docs/rfcs/README.md @@ -8,7 +8,7 @@ protocol partners, integrators, and anyone reading the repository publicly. | # | Title | Status | Feature | |---|---|---|---| | [0001](./0001-server-side-transaction-execution.md) | Guardian executes, proves and submits transactions | Accepted for implementation | [#254](https://github.com/OpenZeppelin/guardian/issues/254) | -| [0002](./0002-guardian-modules.md) | Guardian modules, a hook pipeline for pluggable policy | Accepted for implementation | [#251](https://github.com/OpenZeppelin/guardian/issues/251) | +| [0002](./0002-guardian-modules.md) | Guardian modules, a hook pipeline for pluggable policy | Accepted; M2a implemented, not merged | [#251](https://github.com/OpenZeppelin/guardian/issues/251) | ## What belongs here diff --git a/docs/runbooks/backup-restore.md b/docs/runbooks/backup-restore.md index aa4801baa..3fa742283 100644 --- a/docs/runbooks/backup-restore.md +++ b/docs/runbooks/backup-restore.md @@ -36,6 +36,20 @@ What it does **not** back up: encryption is enabled, a database backup without the key is ciphertext: keep an out-of-band copy of the key secret per [`secrets.md`](./secrets.md). +- **The policy module catalog and module secrets.** The catalog file + (`GUARDIAN_MODULES_CONFIG`) is deploy configuration, not database content: + keep it in the deploy repository, where the catalog hash recorded with each + signed delta finds the exact version. Module tokens and client keys live in + Secrets Manager under the names the catalog gives them and are not recreated + by Terraform. + +Policy module state is in the database, so the backups above cover it: which +instances are enabled, their global params, each account's layers and +assignments, and the params history (`module_instances`, +`module_account_params`, `module_params_history`, `module_state_version`, +`module_account_version`). +A filesystem build keeps the same state in `module_state.json` under +`GUARDIAN_MODULES_STATE`; back that directory up with the metadata directory. ## Verify backups (do this now, not during an incident) @@ -309,6 +323,16 @@ failing verification. A device holding the account re-onboards via other cosigner devices then sync from the guardian. Accounts with no post-restore-point activity are unaffected. +Policy module state rewinds with the rest. Operator writes made after the +restore point are gone: a disable or enable, a params change, an account's +layer or assignment. Compare `GET /dashboard/modules` and the params history +with the audit log of the lost window (the log fallback keeps the events the +database lost) and repeat the writes that should stand, with a reason that +references the restore. An account that re-registers after the restore is a +first registration again, so it receives the current `default` modules, not +the assignment it had. Start the restored server with the same catalog file +as before; a different one changes which instances are declared. + ## Logical backups (optional) For copies that live outside the AWS account (offline archives, cross-region diff --git a/docs/runbooks/policy-modules.md b/docs/runbooks/policy-modules.md new file mode 100644 index 000000000..323fc3f47 --- /dev/null +++ b/docs/runbooks/policy-modules.md @@ -0,0 +1,222 @@ +# Policy Modules Runbook + +What to do when a policy module stops transactions it should let through, and +how to prepare so that the way out is known before an outage. Background: the +[policy modules guide](../guides/policy-modules/README.md) and +[RFC 0002](../rfcs/0002-guardian-modules.md) section 4. + +> **Audience:** operators of a Guardian started with a module catalog +> (`GUARDIAN_MODULES_CONFIG`), with an operator key for the dashboard API, and +> deploy access for changes the API cannot make. + +A module can only refuse; it can never make the Guardian sign. The risk this +runbook covers is the opposite one: a fail-closed module that is down, slow or +misconfigured stops approvals for every account it applies to, and Guardian +executions fail with `GUARDIAN_EXECUTION_MODULE_*` until it is fixed. + +## Before an outage + +For every instance in the catalog, know which path stops it: + +| Catalog entry | Break-glass path | Time to effect | +|---|---|---| +| `operator_can_disable = true` | `POST /dashboard/modules/{id}/disable` with a reason | Next request, on every replica | +| `operator_can_disable = false`, `on_error = "allow"` | None needed for an outage: failures continue (recorded on the delta). A module that denies wrongly needs a params change or a deploy | Next request | +| `operator_can_disable = false`, `on_error = "deny"` | A deploy: change the catalog and restart | A rollout | + +- `on_error = "allow"` skips the instance only when the module itself fails + (timeout, error, invalid decision, open circuit), which the delta records in + `modules.failed_open` (`GET /dashboard/accounts/{account_id}/deltas/{nonce}`). + A request the Guardian cannot build (an account view it cannot read, a failed + read) or one over `GUARDIAN_MODULE_REQUEST_MAX_BYTES` is refused whatever + `on_error` says, since a requester can cause either on purpose; both are + counted in `guardian_module_request_refused_total{module, reason}`. +- Give the on-call operator `modules:disable`. It allows disabling instances + marked `operator_can_disable` and nothing else, so it is safe to hand out + more widely than `policies:write` ([permissions](../DASHBOARD.md#permission-vocabulary)). +- Mark `operator_can_disable = false` only for instances that must hold even + when they block everything (sanctions screening, for example), and agree in + advance that their outage is resolved by fixing the module or by a deploy. +- Watch `guardian_module_up`, `guardian_module_circuit_open`, + `guardian_module_fail_open_total` and the p99 of + `guardian_module_evaluate_duration_seconds` per `module` (see + [`spec/api.md`](../../spec/api.md) for the full list). On AWS the stack + alarms on two of them once `guardian_modules_config` is set: + `-module-circuit-open` (any circuit open for 10 minutes) and + `-module-fail-open` (any request approved without a module's + judgement, threshold `alarm_module_fail_open_threshold`). Elsewhere, alert on + `max(guardian_module_circuit_open) > 0` for 10 minutes and on any increase of + `guardian_module_fail_open_total`. + +Every API change requires a `reason` and is recorded in the instance's params +history (`GET /dashboard/modules/{id}/params/history`), with the operator and +time. + +The examples use the guide's `admin` helper +(`admin METHOD PATH [JSON]` against `/dashboard/PATH`, see the +[guide setup](../guides/policy-modules/README.md#4-the-operator-cli)); the same +routes are in [`DASHBOARD.md`](../DASHBOARD.md#policy-modules) and in +`@openzeppelin/guardian-operator-client`. + +## A module is down + +Symptoms: clients get `503 GUARDIAN_MODULE_UNAVAILABLE` with `meta.module` +(no module for an instance with `client_reason = "generic"`; the `warn` log names it); +`guardian_module_up{module}` is 0; `Policy module health probe failed` and +`Policy module failed; refusing` at `warn`; +`guardian_module_circuit_open{module}` is 1 once a replica has seen +`GUARDIAN_MODULE_BREAKER_FAILURES` (5) failures in a row (failed calls and +unanswered probes count, dry-run checks do not), or at once when a probe finds +the module incompatible with this Guardian, after which the +module is skipped without waiting for its timeout. + +1. Check the module itself (its process, endpoint, certificate, token). A + module that rejects the Guardian's token fails `Describe`, so it looks + down. +2. If it cannot be fixed quickly and the catalog allows it, disable it: + + ```sh + admin POST /modules/risk-vendor/disable '{"reason":"vendor outage INC-123"}' + ``` + + Requests stop calling it on every replica at once. Deltas signed meanwhile + name the catalog and the two params versions they were approved under in the + `modules` field of `GET /dashboard/accounts/{account_id}/deltas/{nonce}`, so + the gap is auditable. +3. When the module is healthy again, enable it. Enabling runs `Describe` and + `ValidateParams` first and returns `503 GUARDIAN_MODULE_UNAVAILABLE` + without changing anything if they fail: + + ```sh + admin POST /modules/risk-vendor/enable '{"reason":"vendor recovered INC-123"}' + ``` + +4. If the catalog does not allow disabling, change it and roll the replicas: + set `on_error = "allow"`, or `operator_can_disable = true` and then + disable through the API, or remove the instance. Editing `enabled` in the + catalog does nothing once the instance has started once: the stored flag + applies and `guardian_module_config_drift` reports the difference. The one + exception tightens policy: an instance the catalog declares enabled and + not `operator_can_disable` is switched on at startup even when it is + stored as disabled, with a params history entry by `catalog`, so making an + instance non-disableable in the catalog also ends an earlier disable. + Removing an instance leaves its account assignments in place, marked + `orphaned` and skipped, so adding it back restores them. Changing an + instance's `scope` does the same to the rows the new scope does not read + (layers once it is no longer `all`, assignment entries once it is): + startup logs how many, and `guardian_module_orphaned_assignments` counts + them. Changing the scope back restores them. + +The breaker closes by itself: a successful health probe +(`GUARDIAN_MODULE_PROBE_INTERVAL_MS`, 5 s) lets the next real call through, and +a successful call closes it. Breakers are per replica, so replicas can +disagree for a few seconds; `GET /dashboard/modules` reports the `circuit` of +the replica that answered. + +## A module refuses what it should allow + +Symptoms: `403 GUARDIAN_MODULE_DENIED` with a `reason_code` that should not +apply; the `info` log line `Policy module denied the request` names the +`module`, `layer`, `reason_code`, the module's `message`, and the +`params_version` and `account_params_version` it decided under. + +1. Find the change: `admin GET /modules/{id}/params/history` lists every + params write with its previous and new value, operator and reason. A + denial in the `account` layer comes from the account's own rule: see + `admin GET /accounts/{account_id}/modules`. +2. Put the previous params back, which the module validates before storing: + + ```sh + admin PUT /modules/caps/params '{"params":{...previous...},"reason":"revert bad cap INC-124"}' + ``` + + An account's layer is removed with + `admin DELETE /accounts/{account_id}/modules/{id}/params '{"reason":"..."}'`. +3. If the module's code is wrong rather than its params, disable the instance + as above, or for a remote module roll back its deployment; the Guardian + needs no restart. + +## Requests are slow or time out + +Symptoms: `timed out` failures, the p99 of +`guardian_module_evaluate_duration_seconds{module}` near the instance's +`timeout_ms`, client requests that take up to +`GUARDIAN_MODULE_EVALUATION_BUDGET_MS` (1 s) longer than usual. + +- One hook invocation spends at most the budget in module calls. Once it is + spent, the remaining modules count as timed out and their `on_error` + applies; these cuts do not count against the breaker. +- `guardian_module_over_budget_accounts` counts accounts whose modules could + exceed the budget (logged at startup with their worst hook). Remove + assignments or account layers from those accounts, or lower the + instances' `timeout_ms` with a deploy. The count, like + `guardian_module_orphaned_assignments`, is taken again every minute, so it + drops within a minute of the fix. +- Raising `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` needs a restart and must stay + below the execution reservation lease (the prod stage refuses to start + otherwise), and client request timeouts must exceed it. + +## The server does not start + +An enabled instance that cannot be created or fails its startup checks stops +startup: an unknown kind, a token the module rejects, a module that answers +with a protocol version or hooks the Guardian cannot use, a secret the secrets +backend cannot read, params the module refuses, or an unreachable module of an +instance that has never started on this Guardian. The log names the instance +(`module : ...`). + +A module that is merely down does not stop a restart once its instance has +started here before. The server logs `Enabled module did not answer its +startup checks` and starts with that instance unavailable: its circuit is +open, so its accounts get `GUARDIAN_MODULE_UNAVAILABLE` (or skip it with +`on_error = "allow"`, recorded as a fail-open skip), and every other account +is served. Each health probe then runs the full startup checks, and the +instance comes back on its own once they pass (`Policy module passed the +startup checks it could not be reached for`). If the module returns with +params it now refuses, the instance stays unavailable and the log says why: +write params it accepts through the operator API. + +- Fix the cause (start the module, fix the secret, see + [secrets](./secrets.md#policy-module-secrets)), or +- remove the instance from the catalog and restart; its stored params, + history and assignments are kept for when it comes back. + +A disabled instance that fails its checks only logs `Disabled module failed +its startup checks` and stays disabled. Each replica creates its instances when +it starts: if one replica could not create a disabled instance (a secret it +could not read at the time, say), enabling the instance through another replica +does not repair it there, and its calls on that replica fail and follow +`on_error`. `guardian_module_up` is 0 for the instance on that replica; restart +it after enabling. + +## Rolling back to a build without modules + +A server build from before policy modules does not know the module +permissions, so it refuses to load an operator allowlist that grants +`policies:write`, `policies:write_global` or `modules:disable`. Before +deploying such a build: + +1. Remove those permissions from the allowlist (the entries keep their other + permissions). +2. Unset `GUARDIAN_MODULES_CONFIG`. The older build ignores it, but leaving it + set means the next upgrade starts with the catalog again, which is what you + want only if you roll forward. + +The module tables stay in the database and are ignored by the older build; +rolling forward again picks them up, with the operator params, layers and +assignments as they were. On a prod-stage build with modules, starting without +the catalog while those tables hold state is refused unless +`GUARDIAN_MODULES_DISABLED=true` (see +[CONFIGURATION](../CONFIGURATION.md)). + +## After an incident + +- Re-enable what was disabled, with a reason that references the incident. +- Check `guardian_module_fail_open_total` for the window: deltas signed while + a fail-open module was failing carry `modules.failed_open` naming it on the + dashboard delta detail. Proposals created and accounts registered past a + failing fail-open module are in the audit log as `modules.failed_open` + events. +- If the outage showed that an instance should not stop approvals, change its + `on_error` or `operator_can_disable` in the catalog now, not during the + next one. diff --git a/docs/runbooks/secrets.md b/docs/runbooks/secrets.md index e2fd958a9..5bb08204b 100644 --- a/docs/runbooks/secrets.md +++ b/docs/runbooks/secrets.md @@ -19,6 +19,7 @@ this doc covers *how* to bootstrap, replace, and respond to compromise. | Operator public keys | Secrets Manager (Terraform-managed or pre-existing ARN) | Updated by editing Terraform var or rotating the secret value | ECS task runtime role, on each dashboard challenge **and each authenticated `/dashboard/*` request** (hot-reloaded — no restart needed) | | EVM allowed chains + RPC URLs | Secrets Manager (Terraform-managed) | Updated by editing `config/evm/chains.json` and redeploying | ECS task execution role; surfaced as env to the task | | Remote prover URL (optional, Guardian execution) | Secrets Manager: Terraform-managed `/server/tx-prover-url` from `guardian_tx_prover_url`, or a pre-existing ARN in `guardian_tx_prover_url_secret_arn`. An `http(s)` URL with a host and no userinfo, query or fragment (the server refuses those at startup), so it holds no credentials; a private prover is restricted at the network level | Managed secret: change `guardian_tx_prover_url` and redeploy. The task definition reads the secret at its pinned version, so the new version produces a new task definition revision and the deploy (including `deploy --skip-build`) rolls the tasks onto the new URL. Pre-existing ARN: the task reads `AWSCURRENT` when it starts, and rotating the value does not change the task definition, so run `aws ecs update-service --cluster --service --force-new-deployment` afterwards. The managed secret has a 7-day recovery window (`aws secretsmanager restore-secret`), and a plan that would delete it fails unless `guardian_execution_enabled = false` | ECS task execution role (plus `kms:Decrypt` on the key when a pre-existing secret uses a customer-managed KMS key); surfaced as `GUARDIAN_TX_PROVER_URL` to the task | +| Policy module credentials (optional) | `GUARDIAN_MODULE_SECRET_PROVIDER`: Secrets Manager (`aws`, the prod default) or owner-only files (`file`); names come from the module catalog | Created and rotated by the operator; read once at startup, so a change takes effect at the next restart | ECS task **runtime** role, at server startup | The ACK secret name is one value that travels through three places. They have **different variable names by design** — each layer has a distinct @@ -532,6 +533,42 @@ To rotate an RPC URL (e.g. switch provider): 1. Edit `chains.json`, redeploy. No special handling — the server treats chain config as a startup-time read. +## Policy module secrets + +A module catalog (`GUARDIAN_MODULES_CONFIG`) names three kinds of secrets: the +bearer token of a remote instance (`auth.token_secret`), its mTLS client +certificate and key (`tls.client_cert_secret`, `tls.client_key_secret`), and +`{ "$secret" = "" }` values in the params of an in-process instance. The +server reads them once, when it creates the instances, through the provider +`GUARDIAN_MODULE_SECRET_PROVIDER` selects; see +[CONFIGURATION.md](../CONFIGURATION.md) and the +[remote module guide](../guides/policy-modules/remote.md#credentials). + +- **AWS (`aws`).** A name is a Secrets Manager secret id holding a secret + string. The reference Terraform does not create these secrets: create each + one, then list its name in `guardian_module_secret_names`, which grants the + ECS task runtime role `secretsmanager:GetSecretValue` on it + ([deploy guide](../SERVER_AWS_DEPLOY.md#policy-modules)), before enabling + the instance. +- **Files (`file`).** A name is a relative path below + `GUARDIAN_MODULE_SECRET_DIR` (the catalog's directory when unset). The server + refuses a file readable by group or others, as it does for ACK key files; a + Kubernetes secret mount needs `defaultMode: 0400`. + +**Rotating a token.** Configure the module to accept both the old and the new +token for the instance, update the secret, restart the Guardian replicas, then +drop the old token from the module. A module served by the SDK harness holds one +token per instance, so restart it with the new token right after the Guardian. + +**Compromise.** A leaked module token lets its holder call the module as the +Guardian: probe decisions, or, once notify ships, forge commit events. Replace +the token as above and review the module's logs for calls that do not match the +Guardian's `request_id`s. A leaked `$secret` value is the third party's +credential (a vendor API key): revoke it with the vendor. + +A secret that cannot be read stops startup for an enabled instance and leaves a +disabled one disabled; the error names the secret, never its value. + ## Audit trail CloudTrail `GetSecretValue` events are scoped per-secret ARN. The @@ -545,6 +582,7 @@ relevant principals you should see hitting each secret: | Operator pubkeys | ECS task runtime role + operators updating the list | | EVM chains / RPCs | ECS task execution role only | | Prover URL | ECS task execution role only | +| Policy module credentials | ECS task runtime role (on cold start) + operators rotating them | Any other principal touching these secrets is suspicious. diff --git a/examples/README.md b/examples/README.md index fa1c10dc5..a4ce72d0f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -4,6 +4,8 @@ Small projects that showcase different ways to interact with Guardian: - [`demo/`](./demo/) – Terminal UI for hands-on experimentation (recommended starting point). - [`operator-smoke-web/`](./operator-smoke-web/) – Minimal browser UI for local Falcon operator login and account API calls through `@openzeppelin/guardian-operator-client`. +- [`policy-module/`](./policy-module/): the built-in policies as a standalone policy module served over gRPC (TLS, per-instance tokens, Dockerfile), for the remote module guide. +- [`compliance-module/`](./compliance-module/): a custom remote module for KYC on signers and sanctions or allowlist screening of recipients, reading its lists from a JSON file, for the [compliance guide](../docs/guides/policy-modules/compliance.md). - [`rust/`](./rust/) – Low-level Rust example with binaries for both local-node and mockchain flows. - [`smoke-web/`](./smoke-web/) – Browser smoke harness for multisig workflows and wallet integrations. diff --git a/examples/_shared/multisig-browser/src/multisigApi.ts b/examples/_shared/multisig-browser/src/multisigApi.ts index 0e4968304..e549553f3 100644 --- a/examples/_shared/multisig-browser/src/multisigApi.ts +++ b/examples/_shared/multisig-browser/src/multisigApi.ts @@ -428,6 +428,10 @@ function failedExecutionAdvice(error: ExecutionFailure): string { case 'GUARDIAN_EXECUTION_CANDIDATE_DISCARDED': case 'GUARDIAN_EXECUTION_EXPIRED': return 'The transaction was sent and did not land: create and sign a new proposal.'; + case 'GUARDIAN_EXECUTION_MODULE_DENIED': + return 'A GUARDIAN policy refused the transaction: it cannot be executed as it stands.'; + case 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE': + return 'A GUARDIAN policy module could not decide: execute it again shortly.'; default: { const unreachable: never = error; throw new Error(`Unknown execution failure: ${JSON.stringify(unreachable)}`); diff --git a/examples/compliance-module/Cargo.toml b/examples/compliance-module/Cargo.toml new file mode 100644 index 000000000..0090587f5 --- /dev/null +++ b/examples/compliance-module/Cargo.toml @@ -0,0 +1,23 @@ +[package] +name = "guardian-compliance-module" +version = "0.1.0" +edition = "2024" +publish = false +description = "A KYC and sanctions policy module for the Guardian, served over gRPC, reading its lists from a JSON file" + +[[bin]] +name = "compliance-module" +path = "src/main.rs" + +[lib] +path = "src/lib.rs" + +[dependencies] +guardian-module-sdk = { path = "../../crates/guardian-module-sdk" } +serde = { workspace = true, features = ["derive"] } +serde_json = { workspace = true } +tokio = { workspace = true, features = ["rt-multi-thread", "macros", "signal"] } +tonic = { workspace = true, features = ["tls-ring"] } + +[dev-dependencies] +guardian-module-sdk = { path = "../../crates/guardian-module-sdk", features = ["conformance"] } diff --git a/examples/compliance-module/README.md b/examples/compliance-module/README.md new file mode 100644 index 000000000..a869298fd --- /dev/null +++ b/examples/compliance-module/README.md @@ -0,0 +1,39 @@ +# Compliance module example + +A KYC and sanctions policy for the Guardian, served as its own process over +gRPC with [`guardian-module-sdk`](../../crates/guardian-module-sdk): + +- every signer of an account must be KYC-verified: at registration, and on + every transaction with `signers = "all"` (only the signers a transaction adds + with `signers = "added"`); +- a payment may not go to a sanctioned account (blocklist), or may go only to + a verified one (allowlist), checking each payment note's target and its + reclaimer. + +The lists come from a JSON file read at startup +([`lists.example.json`](./lists.example.json)) to keep the example +self-contained; a real module would read them from its own database, a +screening vendor or an on-chain registry, depending on its requirements (see +the guide's "Using your own data"). Each catalog instance's params choose which +checks apply. The walkthrough, catalog and production notes are +in the [compliance guide](../../docs/guides/policy-modules/compliance.md). + +```sh +mkdir -p .guardian +(umask 077; openssl rand -hex 32 > .guardian/compliance.token) +cp examples/compliance-module/lists.example.json .guardian/compliance-lists.json +cargo run -p guardian-compliance-module -- \ + --data .guardian/compliance-lists.json --listen 127.0.0.1:7445 \ + --instance compliance .guardian/compliance.token +``` + +Flags: `--data FILE` (required), `--listen ADDR` (default `127.0.0.1:7445`), +`--instance ID TOKEN_FILE` (repeatable, at least one), `--tls-cert PEM +--tls-key PEM [--client-ca PEM]`, and `--insecure` to allow plain text on a +non-loopback address. + +```sh +cargo test -p guardian-compliance-module +``` + +runs the conformance suite over every rule. diff --git a/examples/compliance-module/lists.example.json b/examples/compliance-module/lists.example.json new file mode 100644 index 000000000..cda916861 --- /dev/null +++ b/examples/compliance-module/lists.example.json @@ -0,0 +1,12 @@ +{ + "kyc_signers": [ + "0x0000000000000000000000000000000000000000000000000000000000000051", + "0x0000000000000000000000000000000000000000000000000000000000000052" + ], + "sanctioned_accounts": [ + "0x000000000000000000000000000bad" + ], + "verified_accounts": [ + "0x0000000000000000000000000000a1" + ] +} diff --git a/examples/compliance-module/src/lib.rs b/examples/compliance-module/src/lib.rs new file mode 100644 index 000000000..6c81cbc8e --- /dev/null +++ b/examples/compliance-module/src/lib.rs @@ -0,0 +1,363 @@ +//! A KYC and sanctions policy module for the Guardian. +//! +//! The lists come from a [`Lists`] source: here a JSON file read once at startup +//! ([`Lists::from_file`]). The params of each catalog instance choose which checks apply, so +//! one process can serve a strict instance for some accounts and a lenient one for others. +//! +//! - **Signers (KYC).** Every signer of the account must be KYC-verified: at registration +//! (`/configure`, hook `before_account_registered`) and, with `signers = "all"`, on every +//! transaction, so an account that adds an unverified signer, or whose signer loses its +//! verification, is refused. +//! - **Recipients.** A payment may not go to a sanctioned account (`recipients = "blocklist"`), +//! or may go only to a verified one (`recipients = "allowlist"`). The recipients of a +//! payment note are its P2ID target and, for a reclaimable P2IDE note, its reclaimer. A note +//! whose recipient the Guardian cannot read (a partial note, a custom script) is refused. + +use std::collections::BTreeSet; +use std::path::Path; +use std::sync::Arc; + +use guardian_module_sdk::proto::hook_request; +use guardian_module_sdk::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, + PROTOCOL_VERSION, ParamsVerdict, async_trait, +}; +use serde::Deserialize; + +/// The hooks this module judges: account registration and both transaction gates. +pub const HOOKS: [Hook; 3] = [ + Hook::BeforeAccountRegistered, + Hook::BeforeProposalCreated, + Hook::BeforeTransactionApproved, +]; + +/// Hex digits of a Miden account id and of a signer commitment, as the Guardian sends them. +const ACCOUNT_ID_DIGITS: usize = 30; +const COMMITMENT_DIGITS: usize = 64; + +/// Who is verified and who is sanctioned. Read from a JSON file here to keep the example +/// self-contained; a real deployment reads the same three lists from wherever its compliance +/// program keeps them: its own database, a screening vendor, or an on-chain registry (see the +/// guide, "Using your own data"). +#[derive(Debug, Default)] +pub struct Lists { + kyc_signers: BTreeSet, + sanctioned_accounts: BTreeSet, + verified_accounts: BTreeSet, +} + +/// The data file, as written: ids in `0x` hex, any case. +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct ListsFile { + #[serde(default)] + kyc_signers: Vec, + #[serde(default)] + sanctioned_accounts: Vec, + #[serde(default)] + verified_accounts: Vec, +} + +impl Lists { + /// Reads and checks the data file. A malformed id refuses the whole file: a list with an + /// id that can never match would silently not apply. + pub fn from_file(path: &Path) -> Result { + let text = std::fs::read_to_string(path) + .map_err(|e| format!("cannot read {}: {e}", path.display()))?; + Self::from_json(&text).map_err(|e| format!("{}: {e}", path.display())) + } + + pub fn from_json(text: &str) -> Result { + let file: ListsFile = serde_json::from_str(text).map_err(|e| e.to_string())?; + Ok(Self { + kyc_signers: ids("kyc_signers", COMMITMENT_DIGITS, &file.kyc_signers)?, + sanctioned_accounts: ids( + "sanctioned_accounts", + ACCOUNT_ID_DIGITS, + &file.sanctioned_accounts, + )?, + verified_accounts: ids( + "verified_accounts", + ACCOUNT_ID_DIGITS, + &file.verified_accounts, + )?, + }) + } + + /// The count of each list, for the startup log. + pub fn sizes(&self) -> (usize, usize, usize) { + ( + self.kyc_signers.len(), + self.sanctioned_accounts.len(), + self.verified_accounts.len(), + ) + } +} + +fn ids(field: &str, digits: usize, values: &[String]) -> Result, String> { + values + .iter() + .map(|value| { + let hex = value + .strip_prefix("0x") + .filter(|rest| rest.len() == digits && rest.bytes().all(|b| b.is_ascii_hexdigit())); + match hex { + Some(_) => Ok(value.to_ascii_lowercase()), + None => Err(format!( + "{field}: {value:?} is not 0x followed by {digits} hex digits" + )), + } + }) + .collect() +} + +/// Which signers a request checks. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum SignerCheck { + /// Every signer of the account, on every request. + #[default] + All, + /// Every signer at registration; afterwards only the signers a transaction adds. + Added, + Off, +} + +/// Which recipients a payment may go to. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum RecipientCheck { + /// Any account that is not sanctioned. + #[default] + Blocklist, + /// Only verified accounts. + Allowlist, + Off, +} + +/// An instance's params: which checks apply. The lists themselves are the module's data. +#[derive(Debug, Clone, Copy, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + #[serde(default)] + pub signers: SignerCheck, + #[serde(default)] + pub recipients: RecipientCheck, +} + +impl Params { + fn parse(bytes: &[u8]) -> Result { + if bytes.is_empty() { + return Ok(Self::default()); + } + serde_json::from_slice(bytes).map_err(|e| e.to_string()) + } +} + +/// A denial: a stable reason code for operators and clients, the detail for the log only, +/// and a client message that names the rule, never a list entry. +fn deny(reason_code: &str, logged: String, client_message: &str) -> Decision { + Decision::deny(reason_code, logged).with_client_message(client_message) +} + +pub struct Compliance { + lists: Arc, +} + +impl Compliance { + pub fn new(lists: Lists) -> Self { + Self { + lists: Arc::new(lists), + } + } + + fn unverified_signer<'a>( + &self, + signers: impl IntoIterator, + ) -> Option { + signers + .into_iter() + .find(|signer| { + !self + .lists + .kyc_signers + .contains(&signer.to_ascii_lowercase()) + }) + .map(|signer| { + deny( + "signer_not_verified", + format!("signer {signer} is not KYC-verified"), + "A signer of this account has not completed identity verification.", + ) + }) + } + + fn judge_registration( + &self, + params: Params, + request: &HookRequest, + ) -> Result { + if params.signers == SignerCheck::Off { + return Ok(Decision::allow()); + } + let after = account_after(request)?; + Ok(self + .unverified_signer(&after.signer_commitments) + .unwrap_or_else(Decision::allow)) + } + + fn judge_transaction( + &self, + params: Params, + request: &HookRequest, + ) -> Result { + if let Some(denial) = self.judge_signers(params, request)? { + return Ok(denial); + } + self.judge_recipients(params, request) + } + + fn judge_signers( + &self, + params: Params, + request: &HookRequest, + ) -> Result, ModuleError> { + Ok(match params.signers { + SignerCheck::Off => None, + SignerCheck::All => self.unverified_signer(&account_after(request)?.signer_commitments), + SignerCheck::Added => { + let after = account_after(request)?; + let before: BTreeSet<&String> = request + .before + .iter() + .flat_map(|view| &view.signer_commitments) + .collect(); + self.unverified_signer( + after + .signer_commitments + .iter() + .filter(|signer| !before.contains(signer)), + ) + } + }) + } + + fn judge_recipients( + &self, + params: Params, + request: &HookRequest, + ) -> Result { + if params.recipients == RecipientCheck::Off { + return Ok(Decision::allow()); + } + let Some(hook_request::Subject::Transaction(subject)) = &request.subject else { + return Err(ModuleError::InvalidRequest( + "request has no transaction".into(), + )); + }; + let transaction = subject.miden().ok_or_else(|| { + ModuleError::InvalidRequest("transaction has no Miden projection".into()) + })?; + let payer = request.account_id.to_ascii_lowercase(); + for note in transaction.output_notes.iter().filter(|note| !note.tx_fee) { + let target = note + .p2id_target + .as_deref() + .filter(|_| !note.partial) + .map(str::to_ascii_lowercase); + let Some(target) = target else { + return Ok(deny( + "recipient_unknown", + format!( + "note {} has no recipient this module can check", + note.note_id + ), + "A payment goes to a recipient that cannot be screened.", + )); + }; + let reclaimer = note + .reclaimer + .as_deref() + .map(str::to_ascii_lowercase) + .filter(|reclaimer| *reclaimer != payer); + for recipient in std::iter::once(target).chain(reclaimer) { + if let Some(denial) = self.refused_recipient(params.recipients, &recipient) { + return Ok(denial); + } + } + } + Ok(Decision::allow()) + } + + fn refused_recipient(&self, check: RecipientCheck, recipient: &str) -> Option { + match check { + RecipientCheck::Off => None, + RecipientCheck::Blocklist => { + self.lists.sanctioned_accounts.contains(recipient).then(|| { + deny( + "recipient_sanctioned", + format!("recipient {recipient} is on the sanctions list"), + "A payment goes to a recipient this Guardian cannot pay.", + ) + }) + } + RecipientCheck::Allowlist => { + (!self.lists.verified_accounts.contains(recipient)).then(|| { + deny( + "recipient_not_verified", + format!("recipient {recipient} is not a verified account"), + "A payment goes to a recipient that has not been verified.", + ) + }) + } + } + } +} + +/// The account as it will be if every module allows. Without it the module cannot judge the +/// signers, which is an error for the instance's `on_error` to decide, never an allow. +fn account_after(request: &HookRequest) -> Result<&guardian_module_sdk::AccountView, ModuleError> { + let after = request + .after + .as_ref() + .ok_or_else(|| ModuleError::InvalidRequest("request has no account view".into()))?; + if after.signer_commitments.is_empty() { + return Err(ModuleError::InvalidRequest( + "account view lists no signer".into(), + )); + } + Ok(after) +} + +#[async_trait] +impl Module for Compliance { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(ModuleInfo { + name: "compliance".into(), + version: env!("CARGO_PKG_VERSION").into(), + protocol_version: PROTOCOL_VERSION, + hooks: HOOKS.iter().map(|hook| *hook as i32).collect(), + ..Default::default() + }) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(match Params::parse(params) { + Ok(_) => ParamsVerdict::ok(), + Err(message) => ParamsVerdict::invalid(message), + }) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + let params = Params::parse(&request.params).map_err(ModuleError::InvalidRequest)?; + match &request.subject { + Some(hook_request::Subject::Registration(_)) => { + self.judge_registration(params, request) + } + Some(hook_request::Subject::Transaction(_)) => self.judge_transaction(params, request), + None => Err(ModuleError::InvalidRequest( + "request has no subject this module knows".into(), + )), + } + } +} diff --git a/examples/compliance-module/src/main.rs b/examples/compliance-module/src/main.rs new file mode 100644 index 000000000..7f6af4e7e --- /dev/null +++ b/examples/compliance-module/src/main.rs @@ -0,0 +1,164 @@ +use std::net::SocketAddr; +use std::path::PathBuf; + +use guardian_compliance_module::{Compliance, Lists}; +use guardian_module_sdk::serve::serve; +use tonic::transport::{Certificate, Identity, Server, ServerTlsConfig}; + +const USAGE: &str = "usage: compliance-module --data LISTS_JSON [--listen ADDR] --instance ID TOKEN_FILE [--instance ...] + [--tls-cert PEM --tls-key PEM [--client-ca PEM]] [--insecure]"; + +struct Args { + data: PathBuf, + listen: SocketAddr, + instances: Vec<(String, PathBuf)>, + tls_cert: Option, + tls_key: Option, + client_ca: Option, + insecure: bool, +} + +impl Args { + fn parse() -> Result { + let mut data = None; + let mut parsed = Self { + data: PathBuf::new(), + listen: SocketAddr::from(([127, 0, 0, 1], 7445)), + instances: Vec::new(), + tls_cert: None, + tls_key: None, + client_ca: None, + insecure: false, + }; + let mut args = std::env::args().skip(1); + let value = |args: &mut dyn Iterator, flag: &str| { + args.next().ok_or(format!("{flag} needs a value")) + }; + while let Some(arg) = args.next() { + match arg.as_str() { + "--data" => data = Some(PathBuf::from(value(&mut args, "--data")?)), + "--listen" => { + parsed.listen = value(&mut args, "--listen")? + .parse() + .map_err(|e| format!("--listen: {e}"))?; + } + "--instance" => { + let id = value(&mut args, "--instance")?; + let token_file = value(&mut args, "--instance")?; + if parsed.instances.iter().any(|(known, _)| *known == id) { + return Err(format!("--instance {id} is given twice")); + } + parsed.instances.push((id, token_file.into())); + } + "--tls-cert" => parsed.tls_cert = Some(value(&mut args, "--tls-cert")?.into()), + "--tls-key" => parsed.tls_key = Some(value(&mut args, "--tls-key")?.into()), + "--client-ca" => parsed.client_ca = Some(value(&mut args, "--client-ca")?.into()), + "--insecure" => parsed.insecure = true, + "--help" | "-h" => return Err(USAGE.into()), + other => return Err(format!("unknown argument {other}\n{USAGE}")), + } + } + parsed.data = data.ok_or(format!("--data is required\n{USAGE}"))?; + if parsed.instances.is_empty() { + return Err(format!("at least one --instance is required\n{USAGE}")); + } + if parsed.tls_cert.is_some() != parsed.tls_key.is_some() { + return Err("--tls-cert and --tls-key go together".into()); + } + if parsed.client_ca.is_some() && parsed.tls_cert.is_none() { + return Err("--client-ca needs --tls-cert and --tls-key".into()); + } + if parsed.tls_cert.is_none() && !parsed.listen.ip().is_loopback() && !parsed.insecure { + return Err(format!( + "plain text on {} is reachable from other hosts; add --tls-cert and --tls-key, or --insecure", + parsed.listen + )); + } + Ok(parsed) + } + + fn tls(&self) -> Result, String> { + let (Some(cert), Some(key)) = (&self.tls_cert, &self.tls_key) else { + return Ok(None); + }; + let read = |path: &PathBuf| { + std::fs::read(path).map_err(|e| format!("cannot read {}: {e}", path.display())) + }; + let mut tls = ServerTlsConfig::new().identity(Identity::from_pem(read(cert)?, read(key)?)); + if let Some(ca) = &self.client_ca { + tls = tls.client_ca_root(Certificate::from_pem(read(ca)?)); + } + Ok(Some(tls)) + } +} + +#[tokio::main] +async fn main() -> std::process::ExitCode { + match run().await { + Ok(()) => std::process::ExitCode::SUCCESS, + Err(error) => { + eprintln!("{error}"); + std::process::ExitCode::FAILURE + } + } +} + +async fn run() -> Result<(), Box> { + let args = Args::parse()?; + let lists = Lists::from_file(&args.data)?; + let (signers, sanctioned, verified) = lists.sizes(); + let mut module = serve(Compliance::new(lists)); + for (id, token_file) in &args.instances { + let token = std::fs::read_to_string(token_file) + .map_err(|e| format!("cannot read token file {}: {e}", token_file.display()))?; + if token.trim().is_empty() { + return Err(format!("token file {} is empty", token_file.display()).into()); + } + module = module.instance(id.clone(), token.trim()); + } + let mut server = Server::builder(); + let transport = match args.tls()? { + Some(tls) => { + server = server.tls_config(tls)?; + if args.client_ca.is_some() { + "mTLS" + } else { + "TLS" + } + } + None => "plain text", + }; + let ids: Vec<&str> = args.instances.iter().map(|(id, _)| id.as_str()).collect(); + println!( + "compliance listening on {} ({transport}), instances: {}; {} KYC signers, {} sanctioned and {} verified accounts from {}", + args.listen, + ids.join(", "), + signers, + sanctioned, + verified, + args.data.display() + ); + server + .add_service(module.into_service()) + .serve_with_shutdown(args.listen, shutdown()) + .await?; + Ok(()) +} + +async fn shutdown() { + let interrupt = tokio::signal::ctrl_c(); + #[cfg(unix)] + { + let mut terminate = + tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) + .expect("SIGTERM handler"); + tokio::select! { + _ = interrupt => {} + _ = terminate.recv() => {} + } + } + #[cfg(not(unix))] + { + let _ = interrupt.await; + } +} diff --git a/examples/compliance-module/tests/conformance.rs b/examples/compliance-module/tests/conformance.rs new file mode 100644 index 000000000..34fc5a6e1 --- /dev/null +++ b/examples/compliance-module/tests/conformance.rs @@ -0,0 +1,238 @@ +use guardian_compliance_module::{Compliance, Lists}; +use guardian_module_sdk::conformance::Suite; +use guardian_module_sdk::proto::{asset, hook_request}; +use guardian_module_sdk::{ + AccountStateProjection, AccountView, Asset, HookRequest, MidenAccountState, MidenTransaction, + OutputNote, RegistrationSubject, TransactionProjection, TransactionSubject, +}; +use serde_json::json; + +const VERIFIED_SIGNER: &str = "0x0000000000000000000000000000000000000000000000000000000000000051"; +const OTHER_VERIFIED_SIGNER: &str = + "0x0000000000000000000000000000000000000000000000000000000000000052"; +const UNVERIFIED_SIGNER: &str = + "0x00000000000000000000000000000000000000000000000000000000000000ff"; +const PAYER: &str = "0x0000000000000000000000000000f1"; +const SANCTIONED: &str = "0x000000000000000000000000000bad"; +const VERIFIED_ACCOUNT: &str = "0x0000000000000000000000000000a1"; +const UNKNOWN_ACCOUNT: &str = "0x0000000000000000000000000000c3"; + +fn lists() -> Lists { + Lists::from_json(&format!( + r#"{{ + "kyc_signers": ["{VERIFIED_SIGNER}", "{OTHER_VERIFIED_SIGNER}"], + "sanctioned_accounts": ["{SANCTIONED}"], + "verified_accounts": ["{VERIFIED_ACCOUNT}"] + }}"# + )) + .unwrap() +} + +fn view(signers: &[&str]) -> AccountView { + AccountView { + signer_commitments: signers.iter().map(|s| s.to_string()).collect(), + ..Default::default() + } +} + +fn registration(params: serde_json::Value, signers: &[&str]) -> HookRequest { + HookRequest { + account_id: PAYER.into(), + params: serde_json::to_vec(¶ms).unwrap(), + after: Some(view(signers)), + subject: Some(hook_request::Subject::Registration(RegistrationSubject { + initial_state: Some(AccountStateProjection::miden(MidenAccountState::default())), + })), + ..Default::default() + } +} + +fn payment_to(recipient: &str) -> OutputNote { + OutputNote { + note_id: format!("0xnote{recipient}"), + assets: vec![Asset { + faucet_id: "0x0000000000000000000000000000aa".into(), + value: Some(asset::Value::FungibleAmount("1".into())), + }], + p2id_target: Some(recipient.into()), + ..Default::default() + } +} + +fn transaction( + params: serde_json::Value, + before: &[&str], + after: &[&str], + notes: Vec, +) -> HookRequest { + HookRequest { + account_id: PAYER.into(), + params: serde_json::to_vec(¶ms).unwrap(), + before: Some(view(before)), + after: Some(view(after)), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + output_notes: notes, + ..Default::default() + })), + ..Default::default() + })), + ..Default::default() + } +} + +fn paying(params: serde_json::Value, notes: Vec) -> HookRequest { + transaction(params, &[VERIFIED_SIGNER], &[VERIFIED_SIGNER], notes) +} + +#[tokio::test] +async fn signers_must_be_kyc_verified() { + let added = json!({ "signers": "added" }); + Suite::new(Compliance::new(lists())) + .allows( + "registration with verified signers", + registration(json!({}), &[VERIFIED_SIGNER, OTHER_VERIFIED_SIGNER]), + ) + .denies_with( + "registration with an unverified signer", + registration(json!({}), &[VERIFIED_SIGNER, UNVERIFIED_SIGNER]), + "signer_not_verified", + ) + .denies_with( + "registration with an unverified signer, even when only added signers are checked later", + registration(added.clone(), &[UNVERIFIED_SIGNER]), + "signer_not_verified", + ) + .denies_with( + "a transaction adding an unverified signer", + transaction( + added.clone(), + &[VERIFIED_SIGNER], + &[VERIFIED_SIGNER, UNVERIFIED_SIGNER], + vec![], + ), + "signer_not_verified", + ) + .allows( + "a transaction of an account whose unverified signer predates the check, when only added signers are checked", + transaction(added, &[UNVERIFIED_SIGNER], &[UNVERIFIED_SIGNER], vec![]), + ) + .denies_with( + "any transaction of an account with an unverified signer, when every signer is checked", + transaction(json!({}), &[UNVERIFIED_SIGNER], &[UNVERIFIED_SIGNER], vec![]), + "signer_not_verified", + ) + .allows( + "signer checks off", + registration(json!({ "signers": "off" }), &[UNVERIFIED_SIGNER]), + ) + .fails( + "a registration without the account's signers", + registration(json!({}), &[]), + ) + .valid_params(json!({})) + .valid_params(json!({ "signers": "added", "recipients": "allowlist" })) + .invalid_params(json!({ "signers": "some" })) + .invalid_params(json!({ "sanctions": true })) + .run() + .await + .assert_conformant(); +} + +#[tokio::test] +async fn recipients_are_screened() { + let allowlist = json!({ "recipients": "allowlist" }); + let reclaimable = |reclaimer: &str| OutputNote { + reclaimer: Some(reclaimer.into()), + ..payment_to(VERIFIED_ACCOUNT) + }; + let fee = OutputNote { + tx_fee: true, + ..payment_to(SANCTIONED) + }; + let partial = OutputNote { + partial: true, + ..payment_to(VERIFIED_ACCOUNT) + }; + let custom_script = OutputNote { + p2id_target: None, + ..payment_to(VERIFIED_ACCOUNT) + }; + let mut without_projection = paying(json!({}), vec![payment_to(UNKNOWN_ACCOUNT)]); + without_projection.subject = Some(hook_request::Subject::Transaction( + TransactionSubject::default(), + )); + Suite::new(Compliance::new(lists())) + .allows( + "a payment to an account that is not sanctioned", + paying(json!({}), vec![payment_to(UNKNOWN_ACCOUNT)]), + ) + .denies_with( + "a payment to a sanctioned account", + paying(json!({}), vec![payment_to(SANCTIONED)]), + "recipient_sanctioned", + ) + .denies_with( + "a reclaimable note whose reclaimer is sanctioned", + paying(json!({}), vec![reclaimable(SANCTIONED)]), + "recipient_sanctioned", + ) + .allows( + "a reclaimable note the payer can take back, under the allowlist where the payer is not listed", + paying(allowlist.clone(), vec![reclaimable(PAYER)]), + ) + .allows( + "the fee note is not a payment", + paying(json!({}), vec![fee, payment_to(UNKNOWN_ACCOUNT)]), + ) + .denies_with( + "a note whose recipient cannot be read", + paying(json!({}), vec![partial]), + "recipient_unknown", + ) + .denies_with( + "a full note with a script the Guardian does not read a recipient from", + paying(json!({}), vec![custom_script]), + "recipient_unknown", + ) + .denies_with( + "an id in another case is the same account", + paying(json!({}), vec![payment_to(&SANCTIONED.to_uppercase().replacen("0X", "0x", 1))]), + "recipient_sanctioned", + ) + .fails("a transaction without its projection", without_projection) + .allows( + "a payment to a verified account under the allowlist", + paying(allowlist.clone(), vec![payment_to(VERIFIED_ACCOUNT)]), + ) + .denies_with( + "a payment to an account that is not verified under the allowlist", + paying(allowlist, vec![payment_to(UNKNOWN_ACCOUNT)]), + "recipient_not_verified", + ) + .allows( + "recipient checks off", + paying(json!({ "recipients": "off" }), vec![payment_to(SANCTIONED)]), + ) + .valid_params(json!({ "recipients": "blocklist" })) + .invalid_params(json!({ "recipients": "denylist" })) + .run() + .await + .assert_conformant(); +} + +#[test] +fn a_data_file_with_an_id_that_could_never_match_is_refused() { + assert!(Lists::from_json(r#"{ "kyc_signers": ["0x51"] }"#).is_err()); + assert!( + Lists::from_json(r#"{ "sanctioned_accounts": ["mtst1qrkd5x7qy0mw0yqzlvqlqd3w9cafjkw"] }"#) + .is_err() + ); + assert!(Lists::from_json(r#"{ "sanction_list": [] }"#).is_err()); + assert_eq!( + Lists::from_json(r#"{ "verified_accounts": ["0x0000000000000000000000000000A1"] }"#) + .unwrap() + .sizes(), + (0, 0, 1) + ); +} diff --git a/examples/custom-guardian/.dockerignore b/examples/custom-guardian/.dockerignore new file mode 100644 index 000000000..3ea08526b --- /dev/null +++ b/examples/custom-guardian/.dockerignore @@ -0,0 +1,2 @@ +target/ +.git/ diff --git a/examples/custom-guardian/Cargo.toml b/examples/custom-guardian/Cargo.toml new file mode 100644 index 000000000..af15f23e0 --- /dev/null +++ b/examples/custom-guardian/Cargo.toml @@ -0,0 +1,22 @@ +[package] +name = "custom-guardian" +version = "0.1.0" +edition = "2024" +publish = false +description = "A Guardian server build with the operator's own policy module kinds compiled in" + +[[bin]] +name = "custom-guardian" +path = "src/main.rs" + +[features] +postgres = ["guardian-server/postgres"] + +[dependencies] +guardian-server = { path = "../../crates/server" } +guardian-module-sdk = { path = "../../crates/guardian-module-sdk" } +async-trait = "0.1" +dotenvy = "0.15" +serde = { version = "1.0.228", features = ["derive"] } +serde_json = "1.0.145" +tokio = { version = "1.47.1", features = ["rt-multi-thread", "macros"] } diff --git a/examples/custom-guardian/Dockerfile b/examples/custom-guardian/Dockerfile new file mode 100644 index 000000000..6fd85c353 --- /dev/null +++ b/examples/custom-guardian/Dockerfile @@ -0,0 +1,44 @@ +# A custom Guardian build: the official server with your module kinds compiled in, on the +# official image's toolchain and base. Build it from the template of a release, in the +# template's directory: +# docker build -t my-guardian . +# The release's Cargo.lock pins every dependency; --locked refuses to build if it would change. +# The image has no ack-keygen: mint acknowledgement keys with the official image of the release. +ARG MIN_CA_CERTIFICATES_VERSION=20250419~deb12u2 + +FROM rust:1.98.1-bookworm AS builder +ARG MIN_CA_CERTIFICATES_VERSION + +RUN apt-get update && apt-get install -y \ + ca-certificates \ + "protobuf-compiler=3.21.12-*" \ + && dpkg --compare-versions "$(dpkg-query -W -f='${Version}' ca-certificates)" ge "$MIN_CA_CERTIFICATES_VERSION" \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /app +ENV SOURCE_DATE_EPOCH=0 +ENV RUSTFLAGS="--remap-path-prefix /app=. --remap-path-prefix $HOME=~" +ARG GUARDIAN_SERVER_FEATURES=postgres +# The commit in the server's version info. Unset, it is the Guardian release commit, read from +# the git dependency's checkout. +ARG GUARDIAN_GIT_SHA + +COPY . . + +RUN cargo build --release --locked --bin custom-guardian --features "$GUARDIAN_SERVER_FEATURES" + +FROM debian:bookworm-slim@sha256:7e490910eea2861b9664577a96b54ce68ea3e02ce7f51d89cb0103a6f9c386e0 +ARG MIN_CA_CERTIFICATES_VERSION + +RUN apt-get update && apt-get install -y \ + ca-certificates \ + libpq5 \ + && dpkg --compare-versions "$(dpkg-query -W -f='${Version}' ca-certificates)" ge "$MIN_CA_CERTIFICATES_VERSION" \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /app +COPY --from=builder /app/target/release/custom-guardian /app/server + +EXPOSE 3000 50051 + +CMD ["/app/server"] diff --git a/examples/custom-guardian/README.md b/examples/custom-guardian/README.md new file mode 100644 index 000000000..e37336376 --- /dev/null +++ b/examples/custom-guardian/README.md @@ -0,0 +1,92 @@ +# Custom Guardian build + +The official Guardian server with your own policy module kinds compiled in. +Everything the official `server` binary configures from the environment +(`ServerBuilder::from_env`) is unchanged; `main.rs` adds one +`with_module_kind` call per kind. The example registers `note-policy`, the +module from the [custom modules guide](../../docs/guides/policy-modules/custom.md). + +An in-process kind runs inside the process that holds the acknowledgement keys, +storage credentials and every account's state. Register only code you wrote or +audited, and prefer a [remote module](../../docs/guides/policy-modules/remote.md) +for anything else: it needs no custom build and can only refuse. + +## Start from a release + +Each Guardian release attaches `custom-guardian-.tar.gz`, this directory +turned into a standalone project: + +- `Cargo.toml` depends on `guardian-server` and `guardian-module-sdk` at the + release tag. +- `Cargo.lock` is the release's own, so every Miden and Plonky3 crate is the + version the release was tested with. A freshly resolved lockfile can pick + versions that build but break transaction execution, so always build with + `--locked`. +- `Dockerfile` builds on the official image's toolchain and base, from the + whole template directory, so a module crate you keep beside `src` (a path + dependency such as `modules/acme`) is part of the build. It has no + `ack-keygen`: mint acknowledgement keys with the official image of the same + release. +- `rust-toolchain.toml` pins the release's compiler. + +```sh +tar xzf custom-guardian-v0.19.0.tar.gz && cd custom-guardian +# add your crate to [dependencies], register its kind in src/main.rs +cargo build --release --locked --features postgres +docker build -t my-guardian . +``` + +Adding a crate makes `--locked` refuse the build until the lockfile has it. +Run `cargo update --workspace`, which adds the new crates and keeps every +pinned version, then build with `--locked` again; `git diff Cargo.lock` (or a +diff against the archive's copy) should show only your crates. A plain +`cargo update` moves the pinned Guardian dependencies too. + +A module crate published to crates.io depends on the crates.io +`guardian-module-sdk`. The template's `[patch.crates-io]` replaces it with the +release's copy, so its factory registers; the crate must accept the release's +SDK version. + +The server's version info names the Guardian release commit. Pass +`--build-arg GUARDIAN_GIT_SHA=` to stamp your own build's commit +instead. + +On each Guardian release, start again from that release's template, then +rebuild, sign and redeploy your image. The official image's provenance +attestation does not cover your build. + +## Register a kind + +```rust +ServerBuilder::from_env() + .await + .expect("Failed to configure server") + .with_module_kind("acme-sanctions", Arc::new(acme_sanctions::Factory)) + .build() + .await + .expect("Failed to build server") + .run() + .await; +``` + +The catalog (`GUARDIAN_MODULES_CONFIG`) then names it with +`kind = "acme-sanctions"`. `build` fails if the name is taken, including by a +built-in policy (`spending-limit`, `recipient-policy`, `signer-policy`, +`code-policy`) or `grpc`, and the server refuses to start with a catalog that +enables an instance of a kind it does not register. Builder methods called +after `from_env` replace what the environment set, but `from_env` has already +opened storage and the acknowledgement keys, and block watch follows the +environment's release sweep. + +## In this repository + +The example builds against the working tree: + +```sh +cargo run -p custom-guardian +cargo build --release -p custom-guardian --features postgres +``` + +`scripts/custom-guardian-template.sh` turns it into the release template; the +`Custom Guardian Template` workflow runs it on every release and attaches the +result. diff --git a/examples/custom-guardian/src/main.rs b/examples/custom-guardian/src/main.rs new file mode 100644 index 000000000..135e10fa8 --- /dev/null +++ b/examples/custom-guardian/src/main.rs @@ -0,0 +1,39 @@ +//! The Guardian server with policy module kinds compiled in: everything the official `server` +//! binary does ([`ServerBuilder::from_env`]), plus the `note-policy` kind, so a catalog entry +//! can name it with `kind = "note-policy"` and no endpoint. Register your own kinds the same +//! way. Walkthrough in `docs/guides/policy-modules/custom.md`. +//! +//! `GUARDIAN_EXAMPLE_HTTP_PORT` and `GUARDIAN_EXAMPLE_GRPC_PORT` (default 3000 and 50051) let it +//! run next to another server. + +#[path = "../../../crates/guardian-module-sdk/examples/note_policy/mod.rs"] +mod note_policy; + +use std::sync::Arc; + +use server::builder::ServerBuilder; +use server::builder::env::{DEFAULT_GRPC_PORT, DEFAULT_HTTP_PORT}; + +fn port(var: &str, default: u16) -> u16 { + std::env::var(var) + .ok() + .and_then(|value| value.parse().ok()) + .unwrap_or(default) +} + +#[tokio::main] +async fn main() { + dotenvy::dotenv().ok(); + + ServerBuilder::from_env() + .await + .unwrap_or_else(|error| panic!("Failed to configure server: {error}")) + .with_module_kind(note_policy::KIND, Arc::new(note_policy::NotePolicyFactory)) + .http(true, port("GUARDIAN_EXAMPLE_HTTP_PORT", DEFAULT_HTTP_PORT)) + .grpc(true, port("GUARDIAN_EXAMPLE_GRPC_PORT", DEFAULT_GRPC_PORT)) + .build() + .await + .unwrap_or_else(|error| panic!("Failed to build server: {error}")) + .run() + .await; +} diff --git a/examples/demo/src/actions/proposal_management.rs b/examples/demo/src/actions/proposal_management.rs index 62a4f8ee5..e34f38713 100644 --- a/examples/demo/src/actions/proposal_management.rs +++ b/examples/demo/src/actions/proposal_management.rs @@ -594,7 +594,7 @@ async fn action_execute_proposal( /// What the caller can do after a failed execution. Follows the failure code: whether the /// proposal is still stored does not say whether executing it again can succeed. -fn failed_execution_advice(code: ExecutionFailureCode) -> &'static str { +fn failed_execution_advice(code: &ExecutionFailureCode) -> &'static str { match code { ExecutionFailureCode::ChainBehind | ExecutionFailureCode::NodeUnavailable @@ -639,6 +639,12 @@ fn failed_execution_advice(code: ExecutionFailureCode) -> &'static str { | ExecutionFailureCode::Expired => { "The transaction was sent and did not land: create and sign a new proposal." } + ExecutionFailureCode::ModuleDenied(_) => { + "A GUARDIAN policy refused the transaction: it cannot be executed as it stands." + } + ExecutionFailureCode::ModuleUnavailable { .. } => { + "A GUARDIAN policy module could not decide: execute it again shortly." + } } } @@ -693,7 +699,7 @@ async fn execute_through_guardian( } ExecutionState::Failed => { if let Some(error) = &finished.error { - print_info(failed_execution_advice(error.code)); + print_info(failed_execution_advice(&error.code)); } Err("GUARDIAN could not execute the proposal".to_string()) } diff --git a/examples/operator-smoke-web/README.md b/examples/operator-smoke-web/README.md index 8064e9591..e14cb1d2e 100644 --- a/examples/operator-smoke-web/README.md +++ b/examples/operator-smoke-web/README.md @@ -2,12 +2,13 @@ Minimal browser UI for Guardian operator endpoints using a generated Falcon key. -This example does only four things: +This example does only these things: - generate and persist a Falcon key in the browser - show the derived public key and commitment - call `@openzeppelin/guardian-operator-client` - let you manually drive challenge, login, account list, account detail, and logout +- read and write policy module state (see [Policy modules panel](#policy-modules-panel)) ## Setup @@ -138,13 +139,11 @@ Then exercise each profile: Guardian with `cargo run -p guardian-server --features authz-test-probe` when smoke-testing US2; release builds return `404` for that path. -**Note on `policies:write`**: the v1 permission vocabulary includes -`policies:write` but no route requires it yet. Granting it on an -allowlist entry loads cleanly but has no behavioral effect — the -first consumer ships with #182. The grant is **not** inert against -downgrade though: rolling back to a server build that predates the -permission will fail to load the allowlist. Remove forward-defined -permissions before downgrading the server binary. +**Note on module permissions**: `policies:write`, `policies:write_global` +and `modules:disable` gate the policy module writes (see +[Policy modules panel](#policy-modules-panel)). Rolling back to a server +build that predates one of them fails to load the allowlist, so remove +them before downgrading the server binary. The browser UI's `Operator Public Keys JSON` field shows the legacy single-string form — to test profile B or C, paste a JSON array of @@ -152,6 +151,83 @@ mixed entries into the file directly and the next Guardian reload will pick them up (hot-reload is already supported by `002-operator-auth`). +## Policy modules panel + +The `Policy modules` panel drives the operator module endpoints (RFC 0002, +issue #251; not in a release yet). Endpoint semantics are in +[`docs/DASHBOARD.md`](../../docs/DASHBOARD.md#policy-modules) and the +walkthrough is the +[policy modules guide](../../docs/guides/policy-modules/README.md). The panel +covers: + +- **Catalog**: `Load catalog` lists every instance with its id, kind, scope, + hooks, enabled flag, circuit, enabled and params drift, plus the + `catalogHash`, `paramsVersion` and undeclared instances. Each card has + `Enable` and `Disable` (a `409 GUARDIAN_MODULE_NOT_DISABLEABLE` is expected + for an instance without `operator_can_disable`) and `Use in forms`, which + copies its id and current global params into the forms below. +- **Params history**: newest first for one module id. `Load older` pages with + `before` set to the last entry's `id`; it is disabled once a page returns + fewer entries than the limit. +- **Account modules**: `Load account modules` shows `accountParamsVersion` and + the entries in evaluation order for the `Account ID` from the Accounts panel. +- **Writes**: set an instance's global params, set or clear an account layer + on a `scope = all` instance, and replace the account's assignment with a + JSON array of `{ "moduleId": ..., "params": {...} }` (`Copy current + assignment` fills it from the loaded account modules). Params are checked + as JSON objects in the browser before anything is sent, and every write + sends the panel's `Reason`, which is required. + +Errors show in the Session panel's `Action error` box as +`HTTP [] `, so a missing permission reads as +`HTTP 403 [insufficient_operator_permission] ...`. + +### Starting Guardian with a catalog + +Use the guide's built-in catalog, +[`docs/guides/policy-modules/built-in.toml`](../../docs/guides/policy-modules/built-in.toml), +and its environment file, from the repository root (guide steps 2 and 3): + +```bash +mkdir -p .guardian +cp docs/guides/policy-modules/built-in.toml .guardian/ +cp docs/guides/policy-modules/.env.example docs/guides/policy-modules/.env +cp docs/guides/policy-modules/operators.example.json .guardian/operators.json +# Replace 0xREPLACE_WITH_FAUCET_ID in .guardian/built-in.toml (the server does not start until you do). + +set -a && . docs/guides/policy-modules/.env && set +a +cargo run -p guardian-server --bin server +``` + +The guide's `.env` points `GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE` at +`.guardian/operators.json`. Instead of the guide's `modules_admin keygen` +key, paste this UI's signer public key (the string inside `Operator Public +Keys JSON`) into the `public_key` field, keeping the structured entry so the +permissions apply: + +```json +[ + { + "public_key": "0x", + "permissions": ["dashboard:read", "policies:write", "policies:write_global", "modules:disable"] + } +] +``` + +| Panel action | Permission | +|---|---| +| Load catalog, params history, account modules | `dashboard:read` | +| Set or clear an account layer, replace assignment, enable | `policies:write` | +| Set global params | `policies:write_global` | +| Disable | `policies:write` or `modules:disable` | + +To see the `403` path, drop a permission from the entry and repeat the +write; the allowlist is reread without a restart. With `built-in.toml`, try +`Set account layer` on `blocklist` with `{"denylist": ["0x..."]}`, and +replace an account's assignment with +`[{"moduleId": "treasury-allowlist", "params": {"allowlist": ["0x..."]}}]`. +Each write then appears in `Params history` for that module. + ## Inspecting audit events Every probe denial or success writes one `admin_actions` event. The diff --git a/examples/operator-smoke-web/src/App.tsx b/examples/operator-smoke-web/src/App.tsx index 4de262ba0..5e2fff236 100644 --- a/examples/operator-smoke-web/src/App.tsx +++ b/examples/operator-smoke-web/src/App.tsx @@ -9,6 +9,13 @@ import { type DashboardDeltaDetail, type DashboardDeltaEntry, type DashboardGlobalDeltaEntry, + type AccountModules, + type ModuleAssignment, + type ModuleCatalog, + type ModuleCircuit, + type ModuleInstance, + type ModuleParams, + type ModuleParamsHistoryEntry, type OperatorChallenge, type VerifyOperatorResponse, } from '@openzeppelin/guardian-operator-client'; @@ -29,12 +36,12 @@ function normalizeError(error: unknown): string { // `GUARDIAN_ACCOUNT_PAUSED`, client surfaces `account_paused` // with `pausedAt` / `pausedReason`). if (data?.code === 'account_paused') { - return `[${data.code}] ${base} (pausedAt=${data.pausedAt ?? 'null'}, pausedReason=${data.pausedReason ?? 'null'})`; + return `HTTP ${error.status} [${data.code}] ${base} (pausedAt=${data.pausedAt ?? 'null'}, pausedReason=${data.pausedReason ?? 'null'})`; } if (data?.code) { - return `[${data.code}] ${base}`; + return `HTTP ${error.status} [${data.code}] ${base}`; } - return base; + return `HTTP ${error.status} ${base}`; } if (error instanceof Error) { @@ -190,6 +197,52 @@ function normalizeHex(value: string | null | undefined): string { return (value ?? '').trim().toLowerCase(); } +const MODULE_CIRCUIT_BADGE: Record = { + closed: 'success', + half_open: 'warning', + open: 'warning', +}; + +function parseJsonText(text: string, label: string): unknown { + try { + return JSON.parse(text); + } catch (error) { + const detail = error instanceof Error ? error.message : String(error); + throw new Error(`${label} is not valid JSON: ${detail}`); + } +} + +function requireJsonObject(value: unknown, label: string): ModuleParams { + if (typeof value !== 'object' || value === null || Array.isArray(value)) { + throw new Error(`${label} must be a JSON object`); + } + return value as ModuleParams; +} + +function parseParamsJson(text: string, label: string): ModuleParams { + return requireJsonObject(parseJsonText(text, label), label); +} + +function parseAssignmentJson(text: string): ModuleAssignment[] { + const value = parseJsonText(text, 'Assignment'); + if (!Array.isArray(value)) { + throw new Error('Assignment must be a JSON array of { "moduleId": ..., "params": {...} }'); + } + return value.map((entry, index) => { + const record = requireJsonObject(entry, `Assignment entry ${index}`); + const moduleId = record.moduleId; + if (typeof moduleId !== 'string' || moduleId.trim().length === 0) { + throw new Error(`Assignment entry ${index}: moduleId must be a non-empty string`); + } + const params = requireJsonObject(record.params, `Assignment entry ${index}: params`); + return { moduleId: moduleId.trim(), params }; + }); +} + +function formatOptionalParams(params: ModuleParams | null): string { + return params === null ? 'null' : formatJson(params); +} + export default function App() { const { session, sessionError, generate, clear, signWordHex } = useLocalFalconSigner(); const [guardianBaseUrl, setGuardianBaseUrl] = useState(DEFAULT_GUARDIAN_BASE_URL); @@ -228,6 +281,20 @@ export default function App() { null, ); + const [moduleCatalog, setModuleCatalog] = useState(null); + const [moduleReason, setModuleReason] = useState('smoke-test'); + const [historyModuleId, setHistoryModuleId] = useState(''); + const [historyLimit, setHistoryLimit] = useState('20'); + const [historyEntries, setHistoryEntries] = useState([]); + const [historyLoadedFor, setHistoryLoadedFor] = useState(null); + const [historyHasMore, setHistoryHasMore] = useState(false); + const [accountModules, setAccountModules] = useState(null); + const [globalParamsModuleId, setGlobalParamsModuleId] = useState(''); + const [globalParamsJson, setGlobalParamsJson] = useState('{}'); + const [layerModuleId, setLayerModuleId] = useState(''); + const [layerParamsJson, setLayerParamsJson] = useState('{}'); + const [assignmentJson, setAssignmentJson] = useState('[]'); + const client = useMemo( () => new GuardianOperatorHttpClient({ @@ -263,6 +330,7 @@ export default function App() { setAccounts([]); setAccount(null); resetPagination(); + resetModules(); return nextSession; }); } @@ -276,6 +344,7 @@ export default function App() { setAccounts([]); setAccount(null); resetPagination(); + resetModules(); return nextSession; }); } @@ -525,6 +594,179 @@ export default function App() { setPagedPageCount(0); } + function requireAccountId(): string { + const id = accountId.trim(); + if (!id) throw new Error('Account ID is required'); + return id; + } + + function requireModuleReason(): string { + const reason = moduleReason.trim(); + if (!reason) throw new Error('Reason is required'); + return reason; + } + + function requireModuleId(value: string): string { + const moduleId = value.trim(); + if (!moduleId) throw new Error('Module ID is required'); + return moduleId; + } + + function parseHistoryLimit(): number { + const parsed = Number.parseInt(historyLimit, 10); + if (!Number.isFinite(parsed) || parsed < 1 || parsed > 1000) { + throw new Error('History limit must be an integer from 1 to 1000'); + } + return parsed; + } + + function replaceCatalogInstance(instance: ModuleInstance) { + setModuleCatalog((current) => + current + ? { + ...current, + modules: current.modules.map((entry) => + entry.moduleId === instance.moduleId ? instance : entry, + ), + } + : current, + ); + } + + function selectModule(instance: ModuleInstance) { + setHistoryModuleId(instance.moduleId); + setGlobalParamsModuleId(instance.moduleId); + setGlobalParamsJson(formatJson(instance.params)); + if (instance.scope === 'all') { + setLayerModuleId(instance.moduleId); + } + } + + function resetModuleHistory() { + setHistoryEntries([]); + setHistoryLoadedFor(null); + setHistoryHasMore(false); + } + + function resetModules() { + setModuleCatalog(null); + setAccountModules(null); + resetModuleHistory(); + } + + async function listModules() { + await runAction('listModules', async () => { + const catalog = await client.listModules(); + setModuleCatalog(catalog); + return catalog; + }); + } + + async function enableModule(moduleId: string) { + await runAction(`enableModule(${moduleId})`, async () => { + const instance = await client.enableModule(moduleId, requireModuleReason()); + replaceCatalogInstance(instance); + return instance; + }); + } + + async function disableModule(moduleId: string) { + await runAction(`disableModule(${moduleId})`, async () => { + const instance = await client.disableModule(moduleId, requireModuleReason()); + replaceCatalogInstance(instance); + return instance; + }); + } + + async function loadModuleHistory() { + await runAction('getModuleParamsHistory', async () => { + const moduleId = requireModuleId(historyModuleId); + const limit = parseHistoryLimit(); + const page = await client.getModuleParamsHistory(moduleId, { limit }); + setHistoryEntries(page.entries); + setHistoryLoadedFor(moduleId); + setHistoryHasMore(page.entries.length === limit); + return page; + }); + } + + async function loadOlderModuleHistory() { + const last = historyEntries[historyEntries.length - 1]; + await runAction(`getModuleParamsHistory(before=${last?.id ?? 'none'})`, async () => { + if (!historyLoadedFor || !last) { + throw new Error('Load the newest history page first'); + } + const limit = parseHistoryLimit(); + const page = await client.getModuleParamsHistory(historyLoadedFor, { + before: last.id, + limit, + }); + setHistoryEntries((prev) => [...prev, ...page.entries]); + setHistoryHasMore(page.entries.length === limit); + return page; + }); + } + + async function getAccountModules() { + await runAction('getAccountModules', async () => { + const modules = await client.getAccountModules(requireAccountId()); + setAccountModules(modules); + return modules; + }); + } + + async function setModuleGlobalParams() { + await runAction('setModuleGlobalParams', async () => { + const moduleId = requireModuleId(globalParamsModuleId); + const params = parseParamsJson(globalParamsJson, 'Global params'); + const instance = await client.setModuleGlobalParams(moduleId, params, requireModuleReason()); + replaceCatalogInstance(instance); + return instance; + }); + } + + async function setAccountModuleLayer() { + await runAction('setAccountModuleLayer', async () => { + const id = requireAccountId(); + const moduleId = requireModuleId(layerModuleId); + const params = parseParamsJson(layerParamsJson, 'Account layer params'); + const modules = await client.setAccountModuleLayer(id, moduleId, params, requireModuleReason()); + setAccountModules(modules); + return modules; + }); + } + + async function removeAccountModuleLayer() { + await runAction('removeAccountModuleLayer', async () => { + const id = requireAccountId(); + const moduleId = requireModuleId(layerModuleId); + const modules = await client.removeAccountModuleLayer(id, moduleId, requireModuleReason()); + setAccountModules(modules); + return modules; + }); + } + + async function setAccountModuleAssignment() { + await runAction('setAccountModules', async () => { + const id = requireAccountId(); + const assignment = parseAssignmentJson(assignmentJson); + const modules = await client.setAccountModules(id, assignment, requireModuleReason()); + setAccountModules(modules); + return modules; + }); + } + + function copyAssignmentFromAccount() { + if (!accountModules) { + setUiError('Load account modules first'); + return; + } + const assignment: ModuleAssignment[] = accountModules.modules + .filter((entry) => entry.scope !== 'all') + .map((entry) => ({ moduleId: entry.moduleId, params: entry.params ?? {} })); + setAssignmentJson(formatJson(assignment)); + } + async function logout() { await runAction('logout', async () => { const response = await client.logout(); @@ -532,6 +774,7 @@ export default function App() { setAccounts([]); setAccount(null); resetPagination(); + resetModules(); setChallenge(null); return response; }); @@ -805,6 +1048,361 @@ export default function App() { )} +
+
+

Policy modules

+ + {moduleCatalog + ? `${moduleCatalog.modules.length} instances · paramsVersion ${moduleCatalog.paramsVersion}` + : 'not loaded'} + +
+ +

+ RFC 0002 / issue #251. Reads need dashboard:read. Account layers, + assignments and enable need policies:write; global params need{' '} + policies:write_global; disable takes policies:write or{' '} + modules:disable. Account calls use the Account ID from + the Accounts panel, and every write sends the reason below. +

+ + +
+ + +
+ +

Catalog

+ {moduleCatalog ? ( + <> +
+
+ Catalog hash + {moduleCatalog.catalogHash} +
+
+ paramsVersion + {moduleCatalog.paramsVersion} +
+
+ Undeclared instances + {moduleCatalog.undeclared.length} +
+
+

+ Enable, disable and global params writes update the card in place; reload the + catalog to see the new paramsVersion. +

+
+ {moduleCatalog.modules.map((instance) => ( +
+
+ {instance.moduleId} + + {instance.enabled ? 'enabled' : 'disabled'} + +
+
+
+ Kind + {instance.kind} +
+
+ Scope + {instance.scope} +
+
+ Hooks + {instance.hooks.join(', ')} +
+
+ Circuit + + + {instance.circuit} + + +
+
+ Enabled drift + + {instance.enabledDrift + ? `yes (catalog says ${instance.catalogEnabled ? 'enabled' : 'disabled'})` + : 'no'} + +
+
+ Params drift + {instance.paramsDrift ? 'yes' : 'no'} +
+
+ Operator can disable + {instance.operatorCanDisable ? 'yes' : 'no'} +
+
+ Build + {instance.build ?? startup checks failed} +
+
+
+ Global params +
{formatJson(instance.params)}
+
+
+ + + +
+
+ ))} +
+ {moduleCatalog.undeclared.length > 0 ? ( +
    + {moduleCatalog.undeclared.map((entry) => ( +
  • + undeclared {entry.moduleId} · stored{' '} + {entry.enabled ? 'enabled' : 'disabled'} · never evaluated +
  • + ))} +
+ ) : null} + + ) : ( +

Click Load catalog to list the module instances.

+ )} + +

Params history

+
+ + +
+
+ + + +
+

+ Module: {historyLoadedFor ?? 'none'}; entries loaded:{' '} + {historyEntries.length}; next before:{' '} + {historyHasMore ? historyEntries[historyEntries.length - 1]?.id : 'null'} +

+ {historyEntries.length > 0 ? ( +
+ {historyEntries.map((entry) => ( +
+
+ + #{entry.id} · {entry.accountId ? 'account' : 'global'} + + version {entry.version} +
+
+ {entry.accountId ? ( +
+ Account + {entry.accountId} +
+ ) : null} +
+ Operator + {entry.operator} +
+
+ Reason + {entry.reason} +
+
+ At + {entry.at} +
+
+
+ Previous and new params +
+
+ previous +
{formatOptionalParams(entry.previous)}
+
+
+ new +
{formatOptionalParams(entry.new)}
+
+
+
+
+ ))} +
+ ) : ( +

No history loaded.

+ )} + +

Account modules

+ {accountModules ? ( + <> +
+
+ Account + {accountModules.accountId} +
+
+ accountParamsVersion + {accountModules.accountParamsVersion} +
+
+ {accountModules.modules.length > 0 ? ( +
+ {accountModules.modules.map((entry, index) => ( +
+
+ + {index + 1}. {entry.moduleId} + + + {entry.orphaned ? 'orphaned' : entry.enabled ? 'enabled' : 'disabled'} + +
+
+
+ Scope + {entry.scope} +
+ {entry.scope === 'all' ? ( + <> +
+ Global params +
{formatOptionalParams(entry.globalParams)}
+
+
+ Account layer +
{formatOptionalParams(entry.accountLayer)}
+
+ + ) : ( +
+ Params +
{formatOptionalParams(entry.params)}
+
+ )} +
+
+ ))} +
+ ) : ( +

No modules apply to this account.

+ )} + + ) : ( +

+ Click Load account modules for the account ID above. +

+ )} + +

Writes

+
+
+ +