United States

unitedstates is the facade for a security-first Rust ecosystem for lawful, typed access to U.S. public APIs and datasets. Shared logic is dependency-free, no_std, and independently publishable. Future source crates remain no_std; future networking is isolated in focused std crates and is never enabled by default.

The repository is at its 0.1.0 foundation. It contains only the two crates needed now: unitedstates-core and the unitedstates facade. It does not yet make real upstream requests, and no source integration has been introduced.

Install

The default facade exposes only unitedstates-core:

[dependencies]
unitedstates = "0.1.0"

Or depend directly on the foundation crate:

[dependencies]
unitedstates-core = "0.1.0"

Current Status

Workspace

No empty placeholder crate is published. A crate is created and published only when its implementation begins:

unitedstates-nlr targets the National Laboratory of the Rockies (NLR, formerly NREL) at the current developer.nlr.gov origin. The deprecated developer.nrel.gov origin is not an allowed credential target. Its 1.0 scope is deliberately bounded to JSON GET operations for Alternative Fuel Stations and monthly, lat/lon PVWatts v8. XML, CSV, GeoJSON document output, route POST, and PVWatts hourly/file_id modes are deferred rather than shaping the shared core. The built-in limiter and cache are process-local; the SDK does not claim deployment-wide quota coordination or a persistent authenticated cache.

The U.S. API capability matrix traces every shared pre-1.0 primitive to NLR or another selected source. It also records why openFDA, Census, Regulations.gov, SAM.gov, NWS, and NCEI do not share one universal government API-key abstraction. NASA scope uses active APOD and NeoWs operations, not archived Mars Rover or Earth APIs.

Every Rust crate introduced by this project is published to crates.io. Source and conformance crates use the shared core, policy, and codec crates they require, never the root facade, registry, executor, HTTP, or another source crate. unitedstates-registry owns generated source-specific authorization bindings; generic execution belongs to unitedstates-executor; the facade aligns features, wiring, and re-exports only.

Crate Versioning And Publication

The unitedstates facade always equals the repository tag and is published for every release. Subcrates use independent versions and are published only when their code, bugfixes, dependency requirements, or immutable package metadata change. Unchanged subcrates keep their last crates.io version.

At v1.0.0, every crate then present in the workspace converges to 1.0.0 and is published. The exact per-crate state is tracked in the crate version matrix and enforced by scripts/release_crates.py.

Rust Compatibility

Rust 1.97.1 is the pinned development and release toolchain. The public crates support every stable Rust release from 1.90.0 through 1.97.1.

The latest-stable pin and Cargo tool versions are checked by scripts/check_latest_tools.sh before a release.

Platform Direction

Pure library crates are designed from day one for Linux, Windows, macOS, FreeBSD, NetBSD, Android, and iOS. Platform-independent code does not assume Unix paths, sockets, clocks, or environment variables. A future Aesynx transport can be added behind the same transport contracts without changing source crates.

no_std support does not claim that TLS, DNS, or sockets are platform independent. Applications provide those facilities through an explicit transport implementation.

Security

The repository starts fail-closed:

• no third-party project dependencies;
• no default networking, TLS, credentials, filesystem, clock, or telemetry;
• no arbitrary host or generic proxy surface;
• no unsafe Rust;
• explicit response budgets;
• source integrations stay Foundation until their policy, fixtures, tests, upstream review, security review, and pentest gates pass;
• CodeQL uses GitHub default setup rather than an advanced workflow;
• generated and handwritten first-party code/configuration files over 500 lines fail the local gate.

Report vulnerabilities privately as described in the security policy.

Development

Run the normal local gate:

scripts/checks.sh

Run the networked freshness and release gate only when preparing a release:

scripts/release_0_1_gate.sh

No tag is created when implementation finishes. Every version stops for the maintainer's pentest. Findings, fixes, retests, and later GitHub CI fixes stay current in the same versioned repository report. Development commits are allowed. Once a version is complete and locally green, its AWAITING PENTEST state is committed and that exact HEAD is pentested. After a clean result or completed remediation and retest, the current version and PASS report are committed. GitHub failures reported by the maintainer are fixed, documented, and committed in another cycle. Tagging happens only after the maintainer reports that GitHub is green and explicitly requests the tag.

After that requested tag exists at HEAD, publish only the planned crates in dependency order:

scripts/release_crates.py --check
scripts/release_crates.py --version 0.1.0 --require-tag

Documentation

• Implementation plan
• Release plan
• U.S. API capability matrix
• Standards source policy
• Crate version matrix
• Initial architecture discussion
• Modularity policy
• Toolchain policy
• Threat model
• Security controls
• Supply-chain security
• Unsafe policy

License

Licensed under either the Apache License, Version 2.0 or the MIT license, at your option.