Tests as specification
Mint tests define observable behavior. Read the owning source before changing a test.
A unit test is not complete acceptance. A change that crosses a process, network, custody, or publication boundary needs the matching live gate.
Behavior families
Section titled “Behavior families”| Family | Exact tests | What the tests specify | Required gate |
|---|---|---|---|
| Alias and placeholder grammar | mint-core alias tests: parses_valid_alias, rejects_malformed_placeholder, prose_mentioning_mint_prefix_is_not_a_placeholder. Source tests | Valid aliases round-trip. Prose does not create a credential slot. Malformed or oversized tokens fail. | Focused core test, then workspace tests. |
| Policy matching and call guards | mint-core policy tests: allows_matching_rule, denies_unmatched_actor_by_default, explicit_deny_rule_wins_even_if_later, policy_path_prefix_collision_sibling_falls_through_to_next_rule. Call-guard tests: allows_calls_under_cap, denies_calls_over_cap_without_incrementing, fixed_window_resets_at_the_exact_clock_boundary, adding_a_window_to_an_exhausted_lifetime_cap_clears_it_on_reload. Deployed-policy test: deployed_legacy_call_limit_inventory_matches_the_migration_receipt. Policy tests · Guard tests · Deployed-policy tests | First-match policy, deny-by-default, alias binding, path boundaries, and windowed availability limits remain mechanical. A reload that adds a window to an exhausted windowless cap clears it without a restart, and every deployed legacy call limit must declare a window — a process-lifetime cap is an outage timer, not a cost control. | Focused test and full workspace tests. |
| Declaration and schema safety | parses_v2_declarations_and_exact_native_oauth_store, rejects_duplicate_or_malformed_environment_declarations, exact_oauth_matching_rejects_each_identity_coordinate, deployed_inventory_matches_the_v2_runtime_schema. Tests | Versioned declarations reject unknown, duplicate, malformed, or secret-bearing data. Native OAuth exceptions match every declared identity coordinate. | Focused test, policy check, and workspace tests. |
| Credential custody and capabilities | stores_only_a_digest_and_authenticates_the_one_time_token, rejects_expired_and_wrong_audience_capabilities, atomic_save_round_trips_without_plaintext. Tests · CLI tests | Tokens are issued once and stored as digests. Expiration, audience, file permissions, and revocation are enforced. | Workspace tests, secret scan, and macOS probe when custody behavior changes. |
| Adoption and cutover evidence | derives_posture_from_evidence_instead_of_accepting_a_declared_status, rejects_secret_references_and_non_receipt_evidence, exact_name_inventory_passes_without_inspecting_values, name_state_stage_fails_when_a_migrated_name_remains. Adoption tests · Cutover tests | Status comes from evidence. Cutover compares names and metadata. Values never enter reports or receipts. | Focused tests, CLI adoption tests, and live adoption workflow. |
| Audit ledger and recovery | append_produces_a_chained_record_committing_to_the_prior_hash, mutation_of_a_record_field_fails_closed, concurrent_appends_from_multiple_threads_produce_one_gap_free_verified_chain, reconcile_on_a_migrated_ledger_appends_a_chained_terminal. Ledger tests | The ledger is append-only and hash chained. Torn writes, tampering, unresolved effects, and unsafe reconciliation fail closed. | Workspace tests, broker audit-gate tests, and the live probe. |
| Broker authentication and admission | authenticator tests reject_missing_header and rejects_unknown_token. External tests: shared_secret_auth_from_a_non_loopback_peer_is_refused, deny_by_default_returns_403_with_zero_upstream_calls_and_is_audited. Auth tests · Boundary tests · Proxy test | Authentication, policy, and placeholder checks happen before secret resolution or upstream contact. | Workspace tests, zero-leak gate, and live broker probe. |
| Request substitution and response scrubbing | exfil tests: exfil_cross_alias_injection_is_rejected, body_placeholders_are_resolved_and_scrubbed_from_response, repeated_body_placeholders_cannot_amplify_past_request_limit, reflected_resolved_secret_is_scrubbed_from_all_response_surfaces. Response tests: scrubs_encoded_resolved_secret_forms_and_sensitive_location_query_values, never_relay_denies_an_encoded_resolved_secret. Inert-placeholder tests: json_body_prose_mention_of_foreign_alias_forwards_verbatim, json_body_mixed_permitted_and_unpermitted_placeholders_resolves_only_permitted, header_unpermitted_alias_still_denies. Exfil tests · Scrub tests · Inert tests | Cross-alias requests, amplification, encoded values, reflected values, sensitive fields, and never-relay rules preserve non-disclosure. An unpermitted placeholder mention in a body or query forwards as inert text instead of denying the call; the same mention in a header still denies. | Workspace tests, zero-leak gate, and live probe. |
| Streaming and compression safety | stream tests: prefix_secret_split_across_chunks_is_redacted, streaming_sse_redacts_resolved_secret_split_across_upstream_chunks, streaming_oversized_unterminated_frame_fails, gzip_bomb_is_rejected. Source tests · HTTP tests | Chunk boundaries do not bypass scrubbing. Unsupported, oversized, or unsafe encodings are not relayed. | Workspace tests and zero-leak gate. |
| Audit gate, cancellation, and breaker behavior | restart_with_an_unresolved_prepared_effect_keeps_readiness_red, client_disconnect_after_prepare_does_not_abandon_the_effect, connect_failure_opens_the_breaker, body_read_failure_is_sanitized_indeterminate_and_opens_the_breaker. Audit tests · Cancellation · Breaker | Prepared effects reach one terminal state. Disconnects do not abandon effects. Indeterminate upstream failures open the correct breaker. | Workspace tests, live probe, and shutdown verification when lifecycle code changes. |
| Declaration reload and typed actions | a_reload_swaps_authentication_and_policy_together_for_every_new_request, success_path_scrapes_interacts_stops_and_returns_only_bounded_output, unknown_input_field_is_rejected_structurally, tool_rule_does_not_authorize_the_generic_egress_proxy_route. Reload tests · Typed-effect tests | Reload swaps policy and authentication atomically. Typed actions validate input and cleanup. Tool rules do not widen proxy authority. | Workspace tests and live broker checks. |
| CLI, release, and local cutover | policy_check_accepts_a_valid_file, doctor_reports_green_on_a_valid_deployment_and_a_resolvable_self_test_alias, unsupported_policy_is_rejected_before_restart_or_pointer_mutation, complete_forward_flow_commits_and_show_reads_committed. CLI tests · Release tests · Cutover tests | Operator commands use the runtime parsers. Preflight runs before mutation. Cutover transitions are durable and monotonic. | Workspace tests, cargo audit, macOS probe, and release verification. |
| MCP read-only surface | mcp_tool_surface_is_read_only_by_name, every_tool_schema_is_valid_json_and_tools_list_does_not_panic, initialize_reports_server_name_mint. MCP tests | MCP lists and inspects declarations. It never resolves or returns secret bytes. | Workspace tests and a stdin JSON-RPC smoke test. |
| End-to-end zero-leak proof | brokered_call_swaps_the_real_secret_in_without_leaking_it_anywhere_observable, plus the exfil and response-scrub suites. Leak test | A placeholder can produce a credentialed effect without exposing the credential to the caller, audit, or broker output. | scripts/zero-leak-check.sh and scripts/mint-probe.sh. |
Required CI gates
Section titled “Required CI gates”The required gates are complementary. Do not replace one with another.
| Gate | Command | Boundary covered |
|---|---|---|
| Formatting | cargo fmt --all -- --check | Rust formatting. |
| Lint | cargo clippy --workspace --all-targets -- -D warnings | Warnings and suspicious code. |
| Workspace tests | cargo test --workspace | Rust unit and integration behavior. |
| Hermetic leak gate | ./scripts/zero-leak-check.sh | Fresh sentinel, leak and exfil suites, remote-probe verifier, and shell syntax. |
| Secret scan | gitleaks detect --source . --redact --no-banner and the no-git working-tree scan | Tracked history and working-tree content. |
| Supply chain | cargo audit | RustSec advisories in Cargo.lock. |
| macOS probe | ./scripts/mint-probe.sh | Real keychain, broker, upstream, denial, audit, and zero-leak path. |
| Public site verification | SITE_URL=https://mint.mistystep.io PUBLIC_SOURCE_URL=https://github.com/misty-step/mint npm run verify:public in site | Script fixtures, Astro diagnostics, public-origin validation, canonical and sitemap build, executable-code typography, freshness, and links. |
| Public site deployment | .github/workflows/pages.yml | The same public-site verification must pass before the workflow uploads site/dist and deploys it through GitHub Pages. |
The CI declaration is the authority for required gates. The deployment workflow owns publication and requests Pages enablement before upload. Read the pinned CI workflow and Pages workflow.
How to choose a test
Section titled “How to choose a test”- Identify the deepest module that owns the invariant.
- Read its focused unit or integration test.
- Add the smallest test that would fail for the bug.
- Run the focused test.
- Run every boundary gate named by the behavior family.
A green focused test proves only its contract. It does not prove deployment, custody, publication, or zero leakage.
Documentation provenance
Section titled “Documentation provenance”This page's generatedAtSha is the sole committed freshness baseline for its covered source set. The freshness checker compares covered paths changed from generatedAtSha through HEAD, plus staged, unstaged, and untracked paths; editing this page does not bypass a covered source change. Refresh generatedAtSha and review source links after source changes.
Source map
Section titled “Source map”The core behavior anchors are config scanning, declaration schemas, and release activation. The broker anchors are exfiltration, scrubbing, audit recovery, and inert-placeholder handling.
The secret-scan gate follows the narrow live fixture policy and commit-pinned historical exceptions.
The public-site gate is anchored by its package scripts, current Astro build configuration, freshness checker, freshness fixture, public-origin checker, public-origin fixture, and executable-code typography checker.