Skip to content

refactor: split security-critical god files and make audit emission structural #304

Description

@jeremi

Found during the 2026-07-07 architecture audit.

Context

Module boundaries are absent exactly where the complexity and the churn live:

  • registry-notary-server/src/api.rs 16,299 lines (top fix-churn file of 2026: 37 fix commits), standalone.rs 11,383 (mixes authenticators, audit pipeline, three HTTP connector families, signing key registry, an inline ~430-line PKCS#11 module at :3348, eSignet runtime, middleware, router assembly), runtime.rs 10,097
  • registry-notary-core/src/config.rs 13,130; registry-notary-source-adapter-sidecar/src/sidecar.rs 7,738
  • registry-manifest-core/src/lib.rs 7,398; registryctl/src/lib.rs 6,508; registry-relay/src/config/validate.rs 5,031
  • Tests mirror it: registry-notary-server/tests/standalone_http.rs 14,831 lines

Consequences already materialized: parallel branches added the same helper twice to validate.rs and textual auto-merge kept both, breaking main (8ad5705, PRs #269/#273). Security-critical code in these files cannot be reviewed unit-by-unit.

Related structural fix: audit emission is opt-in per handler, which produced a recurring fix class (six emission fixes on 2026-06-21: 0c1f8a2, fdbbd13, 814703b, 77ca585, 5abfd89, b6a8ab3; again 2026-07-02: 235e3ca). The api.rs split is the natural moment to fix the class, not just instances.

Scope

  • Mechanical, behavior-neutral module splits of the files above (target: no source file beyond ~3k lines in the listed crates).
  • While splitting api.rs: centralize audit emission at the middleware/router layer and add a route-coverage contract test asserting every route emits audit events with a declared purpose/scope.
  • Split the mega test files along the same seams.

Sequencing

Do this while in-flight branches are few; the splits invalidate open branches. Before 1.0 or the window closes.

Acceptance

  • Splits are behavior-neutral (workspace tests green before/after, no public API change).
  • Audit route-coverage contract test wired into CI.

Security note

If this work surfaces a suspected vulnerability, report it per SECURITY.md; do not post details on this issue.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:notaryRegistry Notary ownership.area:relayRegistry Relay ownership.criticality:p2Priority/criticality P2.rustRust implementation work.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions