swift-cidr-admission 0.2.0

swift-cidr-admission 0.2.0

0.2.0 adds the local, auditable policy-file path used by the offline
cidrmerge pipeline. It preserves deny-first admission decisions and the
legacy CIDR-only JSON wire format while extending source rules to addresses,
networks, and inclusive ranges.

Public API

• AdmissionRule represents .address(AnyIPAddress),
  .network(AnyIPNetwork), or .range(AnyIPAddressRange) and provides exact
  containment.
• IPAdmissionPolicyFileConfiguration assigns independent local allow and deny
  files, an explicit IPAdmissionChecksumPolicy, and a default action.
• IPAdmissionPolicy.init(fileConfiguration:) synchronously validates any
  required or present checksum and returns a policy only after both roles parse
  and compile successfully.
• IPAdmissionPolicyRuleTextError and IPAdmissionPolicyFileLoadError provide
  typed, role-aware diagnostics for URL, file, checksum, UTF-8, line-ending,
  and rule failures.
• allows(_:) uses private family-partitioned exact-coverage indexes, while
  decision(for:) preserves source order and reports the first matching
  AdmissionRule.

Intentional source changes

This pre-1.0 release changes two public source shapes:

• IPAdmissionPolicy.allow and .deny are [AdmissionRule] instead of
  [AnyIPNetwork].
• AdmissionDecisionReason.matched(ruleSet:network:) is now
  .matched(ruleSet:rule:).

The network-only IPAdmissionPolicy(allow:deny:defaultAction:) initializer
remains available, and the legacy JSON document remains CIDR-only with the same
defaultAction, allow, and deny keys. Consumers that are not ready to
migrate should retain .upToNextMinor(from: "0.1.0"), which excludes 0.2.0.

The package now requires swift-cidr 0.5.x and adds Swift Crypto 4.x for
detached SHA-256 validation. Consumers pinned to older swift-cidr releases
must update their dependency requirements as part of this migration.

Local policy files and integrity

RouteObjects IP List Text v1 accepts one UTF-8 CIDR network, same-family
inclusive lower...upper range, or bare address per non-comment line. It
supports LF or CRLF, an optional leading BOM, blank lines, and # comments;
malformed input fails the complete load without rewriting the source file.

Each configured path is opened once, checked as a regular file, and read from
that pinned nonblocking descriptor. When a checksum is required or present,
Admission matches its digest against the exact deployed bytes before parsing
the same buffer. Both roles are compiled in temporary state and no policy is
returned unless both succeed.

.required requires an exact detached <list-path>.sha256 file;
.verifyIfPresent permits a missing checksum but rejects any present malformed,
filename-mismatched, or digest-mismatched checksum. A matching SHA-256 digest
shows agreement with the supplied checksum and can detect accidental corruption
or uncoordinated edits when that checksum arrives through a trusted channel. It
does not authenticate the producer, detect coordinated replacement, or bind an
allow/deny deployment generation.

cidrmerge pipeline

Run cidrmerge 0.2.0 once per policy role:

cidrmerge --input-format searchbot --raw --representation ranges \
  --checksum --output allow.txt saved-crawler-prefixes.json

cidrmerge --input-format text --raw --representation ranges \
  --checksum --output deny.txt blocked-prefixes.txt

Load allow.txt and deny.txt with checksum policy .required. Range and CIDR
outputs preserve identical exact coverage; cidrmerge remains role-neutral and
offline, while admission owns allow/deny roles, the default action, checksum
validation, and runtime decisions.

Cross-package acceptance covered all four allow/deny range/CIDR pairings, 31
fixed boundaries, 22,304 deterministic agreement probes, first-source-rule
diagnostics, required-checksum failures, and fail-atomic two-role construction.

Compatibility and validation

• Swift tools version: 6.1
• Declared platforms: macOS 15 and iOS 18
• Dependencies: swift-cidr 0.5.x and Swift Crypto 4.x
• Validation: root unit/integration tests, public-only cidrmerge consumer tests,
  the SwiftNIO example build, benchmark-target build, hosted Linux CI, and
  manually dispatched macOS/iOS CI

This is a Swift library source release. It intentionally has no prebuilt binary
assets.

Trust boundary and deferred work

The 0.2 release delivers the two-list operations shape, auditable
representation-aware input, detached checksum validation, and
all-or-nothing local policy construction (maturity levels 1 through 4).
Producer authenticity and runtime audit metrics/logging (levels 5 and 6) are
deferred. Fetching, deployment
orchestration, signatures/provenance, hot reload, and audit metrics are not part
of this release.