feat(cli): audit subcommand for station configuration sanity checks

[MRmarioruci]

Summary

• New orbit-cli audit --station <CANISTER_ID> subcommand: read-only sanity checks against an Orbit station's configuration.
• Three checks ship in this first release: an empty-approver-set Quorum trap, a validation/execution-method match on CallExternalCanister, and an EditAsset-weaker-than-Transfer configuration warning.
• Uses the same dfx canister call --output json pattern as registry/ and release/. No new runtime dependencies. Read-only by construction — only query methods are invoked.

Motivation

Several station-configuration shapes that look fine in the wallet UI can silently disable approval gates or create routing-redirect vectors:

• A Quorum / QuorumPercentage rule whose UserSpecifier resolves to zero active users auto-approves with no votes — the evaluator's min(min_approved, total_possible_approvers) clamp drives the threshold to 0.
• A CallExternalCanister permission or policy where validation_method == execution_method runs the side effect at submission time, before the approval policy has completed.
• An EditAsset policy gated more loosely than Transfer for the same asset lets an actor mutate asset.metadata["ledger_canister_id"] between an approved transfer's policy evaluation and its batch-job execution.

These all require manual UI walkthroughs to spot today. orbit-cli audit makes the check a one-command read-only sweep that can run on demand or in CI.

What changed

• New cli/src/audit/:
  • index.ts — Commander command (-s/--station, -n/--network, -i/--identity, -o/--output).
  • station.core.ts — paginated dfx canister call wrappers for list_request_policies, list_users, list_user_groups, list_assets, list_named_rules, list_permissions.
  • types.ts — hand-written TS subset of the station API; small enough that the didc bind toolchain dependency isn't worth pulling in for this MVP.
  • resolver.ts — resolveApprovers and minVotesForRule mirroring the relevant subset of find_matching_users and RequestApprovalSummary::evaluate from core/station/impl/src/models/request_policy_rule.rs; walks NamedRule chains with cycle detection.
  • report.ts — Finding type, severity-sorted text formatter, exit-code helper.
  • checks/*.ts — one file per check; each returns Finding[].
  • checks/*.spec.ts — unit tests, 19 cases across positive and negative paths.
  • README.md — usage, exit codes, check catalogue, extension notes, roadmap.
• cli/src/cli.ts — register the new subcommand alongside registry and release.
• cli/package.json — add vitest 1.6.1 as a dev dependency (matching the root pin) and a test script.
• pnpm-lock.yaml — updated for the vitest addition.

Exit codes: 0 clean / 1 warnings only / 2 any blockers. Convenient for CI gating.

--output <PATH> writes the report to a file (overwrite); the exit code is unchanged and a short confirmation is emitted to stderr so file-mode runs still give feedback without polluting the report.

Test plan

• pnpm --filter orbit-cli test — 19 vitest cases pass (3 spec files). Covers each check's positive and negative paths, combinator descent (AnyOf), NamedRule resolution, and cycle detection.
• pnpm --filter orbit-cli build — tsc clean.
• Prettier + ESLint clean on all new files.
• Manual smoke test against a mainnet station: created an empty user group, a NamedRule pointing at it, a Request Policy referencing the NamedRule, a CallExternalCanister permission with validation == execution, and a weak EditAsset policy — the audit reported 2 BLOCKERs + 1 WARNING with exit code 2. Cleanup returned the station to 0 findings, exit code 0.
• Reviewers may want to run it against their own local or mainnet stations.

Notes for reviewers

• The implementation deliberately mirrors the existing registry/ subcommand's structure (shell out via dfx canister call --output json, paginated list_*, hand-typed result shapes) so it slots into the codebase without introducing new patterns.
• The asset.edit-policy-weaker-than-transfer check compares station-wide rather than per-asset/per-account — that's a deliberate MVP shortcut documented in the README's roadmap. Per-asset scoping is a planned follow-up.
• No security-ticket / disclosure references appear in the code or commit history; the README explains each check in technical terms only.

[Copilot]

Pull request overview

Adds a new orbit-cli audit subcommand that performs read-only sanity checks against an Orbit Station configuration by fetching station state via dfx canister call --output json, running a small set of static checks, and emitting a severity-sorted report with CI-friendly exit codes.

Changes:

• Registers a new audit CLI subcommand and implements station query wrappers + report rendering.
• Introduces three initial configuration checks (quorum empty approver set, external call validation==execution, EditAsset weaker than Transfer), with unit tests and documentation.
• Adds vitest and a test script to the orbit-cli package.

Reviewed changes

Copilot reviewed 16 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Locks vitest addition for the CLI workspace.
cli/package.json	Adds vitest dev dependency and test script for orbit-cli.
cli/src/cli.ts	Registers the new audit subcommand.
cli/src/audit/index.ts	Implements the orbit-cli audit command wiring, fetching station state, running checks, and setting exit codes.
cli/src/audit/station.core.ts	Adds paginated dfx canister call wrappers for station list_* query methods.
cli/src/audit/types.ts	Hand-written TS types for the station API subset needed by the audit.
cli/src/audit/resolver.ts	Implements static resolver utilities (resolveApprovers, quorum walker, and min-votes estimator).
cli/src/audit/report.ts	Defines findings/report format, rendering, and exit-code logic.
cli/src/audit/checks/*	Implements the three initial checks plus test fixtures and Vitest specs.
cli/src/audit/README.md	Documents usage, exit codes, checks, and extension notes.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to c9a6c1d.

Security Overview

• 🔎 Scanned files: 24 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/5243341a-e7d7-47de-848a-f52264761c93?scanId=8b4a15a2-7bec-49bc-8f7d-bda0b76407cc&codeScanTypes=PrScan&tab=issues

Detected Code Changes

The diff is too large to display a summary of code changes.