Skip to content

Commit 70895b3

Browse files
wpfleger96Duncancea-block
authored
feat(buzz-auth): add production NIP-FI federated assertion runtime (#7109)
Depends on #6994 (merged). Stack: PR 2 #6994 (merged) → this PR (#7109) → PR 4 #7148 → PR 5 ## What Production assertion runtime for NIP-FI Phase A: JWKS caching layer, SSRF-hardened HTTP fetcher, startup validation gate, NIP-11 discovery serialization, federated assertion verifier with sealed key-source authority, and supporting invariant tests. ## Changes ### `crates/buzz-auth/src/nip_fi/jwks/` `ProductionJwksSource<F>` implements the sealed `IssuerKeySource` trait: - `HttpJwksFetcher`: reqwest-backed fetch with SSRF protection — URI validation (HTTPS, no credentials, no fragment, no host matched by the shared enumerated deny policy), per-fetch DNS resolution rejecting any resolved address matched by the shared enumerated deny policy, address pinning to prevent DNS rebinding TOCTOU, redirect denial, incremental body streaming capped at 512 KiB before any parse - IPv6 host extraction via typed `Url::host()` accessor (strips brackets before SSRF check and provides the correct bare input form for reqwest `resolve()` pinning; the bracketed form from `host_str()` fails `IpAddr::parse` and does not match the URL authority key) - Complete-operation deadline via `tokio::time::timeout` covering DNS resolution through body streaming - Bounded periodic refresh with configurable interval and hard snapshot deadline - Cancellation-safe RAII refresh permit: dropped on future cancellation so the next caller can re-fetch - Content-digest-gated generation counter: identical re-fetches preserve generation; key rotations advance it - Injectable clock (`now_fn: Arc<dyn Fn() -> DateTime<Utc> + Send + Sync>`): production uses `Arc::new(Utc::now)`; all four deadline creation and expiry checks use `(self.now_fn)()`, enabling controlled-time testing without wall-clock sleep `JwksSourceContract`: a closed value type that is the single source of truth for the three deployment fields whose change alters which keys the runtime trusts and how long it trusts them: - `jwks_uri` — selects the authenticated key source; validated at construction (HTTPS, no credentials/fragment, no bare private-IP host); stored as the `Url`-normalized form so that equivalent spellings (uppercase host, explicit default port `:443`, dot-segment paths like `/.well-known/./jwks.json`) converge to the same `AssertionPolicyId` - `refresh_interval_seconds` — defines bounded refresh behavior; positive, ≤ 1 year, strictly < `key_snapshot_hard_deadline_seconds` - `key_snapshot_hard_deadline_seconds` — defines the source's accepted time rule; every `VerifiedAssertion.revalidation_dependencies` deadline derives from this `JwksSourceContract` is a required `IssuerPolicy` input and is included in `derive_assertion_policy_id` after a domain separator. `IssuerJwksConfig` embeds the contract instead of independently restating these fields — startup validation rejects any contract mismatch (`NipFiStartupError::JwksContractMismatch`). ### `crates/buzz-auth/src/nip_fi/verifier.rs` - `FederatedAssertionVerifier<S>`: provider-neutral verifier over a closed multi-issuer registry and sealed `IssuerKeySource` - `Arc<S>: IssuerKeySource` forwarding impl (blanket seal for `Arc<S>` in the sealed module) — one `Arc<ProductionJwksSource>` can be shared across multiple verifiers; all observe JWKS refreshes through the shared cache without rebuilding the verifier - `AssertionKeySet`: crate-private constructor seals issuer binding — no external crate can relabel issuer B's JWKS as issuer A - Sealed `IssuerKeySource` trait closes the authority-construction seam at both ends ### `crates/buzz-core/src/network.rs` Renamed `is_private_ip` to `is_not_global_unicast` (compat alias retained) and restored the complete IANA deny/exception table from this branch's own history (`272dacadb`). The predicate is an enumerated deny/explicit exception policy: addresses covered by a named deny rule are rejected; addresses not covered by any explicit deny rule (e.g. `fe00::1`) pass through. Deny rules are derived from the IANA Special-Purpose Address Space registries (last updated 2025-10-09), with globally-reachable exceptions carved out explicitly (e.g. PCP/TURN anycast inside 2001::/23). Blocked IPv4 classes: loopback (127/8), private RFC 1918 (10/8, 172.16/12, 192.168/16), link-local (169.254/16), unspecified (0/8), broadcast, CGNAT/RFC 6598 (100.64/10), benchmarking/RFC 2544 (198.18/15), IETF Protocol Assignments (192.0.0.0/24, globally reachable exceptions: 192.0.0.9 PCP anycast RFC 7723 and 192.0.0.10 TURN anycast RFC 8155), documentation/RFC 5737 (192.0.2/24, 198.51.100/24, 203.0.113/24), deprecated 6to4 relay anycast (192.88.99.0/24, RFC 7526, global=None → conservative deny), multicast/RFC 5771 (224/4), reserved class-E (240/4). Blocked IPv6 classes: loopback (::1), unspecified (::), ULA (fc00::/7), link-local (fe80::/10), deprecated site-local (fec0::/10, RFC 3879), multicast (ff00::/8), IETF Protocol Assignments envelope (2001::/23, globally reachable exceptions: 2001:1::1–::3 PCP/TURN/DNS-SD anycast, 2001:3::/32 AMT RFC 7450, 2001:4:112::/48 AS112-v6 RFC 7535, 2001:20::/28 ORCHIDv2 RFC 7343, 2001:30::/28 DETs RFC 9374), documentation (2001:db8::/32 RFC 3849, 3fff::/20 RFC 9637), 6to4 (2002::/16, RFC 3056), Discard-Only (100::/64, RFC 6666), Dummy IPv6 Prefix (100:0:0:1::/64, RFC 9780), SRv6 SIDs (5f00::/16, RFC 9252), NAT64 local-use (64:ff9b:1::/48, RFC 8215). IPv4 embedded in mapped, compatible, NAT64 well-known (64:ff9b::/96), and SIIT IPv4-translated (::ffff:0:0:0/96) forms is checked recursively. All three callers (JWKS boundary, webhook SSRF, link-preview SSRF) inherit the complete predicate through the inline `is_private_ip` compatibility alias. ### Invariant coverage **Canonical URI convergence.** `jwks_contract_uri_canonicalization_convergence_and_divergence` asserts that uppercase host, explicit `:443`, and dot-segment path (`/.well-known/./jwks.json`) each produce the same `AssertionPolicyId` as the canonical form; a genuinely different host or path diverges. Mutation: storing raw input bytes instead of `parsed.to_string()` turns the three convergence assertions red. **Resolved-target and pin-input seam.** `resolved_target_and_pin_key_seam_public_ipv6_and_fec0_rejection` carries a public `2606:4700::1` URI through all three stages of `fetch_jwks_inner`: `extract_url_host_and_port` yields the bare host (no brackets), `resolve_and_check_ssrf` takes the IP-literal fast path and returns the accepted `IpAddr`, and the extracted host string equals the URL authority form (verifying the correct bare input to reqwest's `resolve()` pin call). `fec0::1` traverses the same extraction and SSRF stages and is rejected as `InvalidUri`. Network-free: both addresses are IP literals with no DNS lookup. Mutation: restoring `host_str()` brackets the address, `IpAddr::parse` fails, the SSRF fast path is unreachable, and all three assertions flip red. **Controlled original-deadline rotation.** `shared_arc_source_verifier_rejects_expired_a1_accepts_a2` uses an `AtomicI64`-backed injectable clock to advance past A1's original absolute deadline without wall-clock sleep. A1's deadline is computed at T0 and never mutated. The clock advances to T0 + HARD_DEADLINE_SECS + 1; `get_snapshot` fires a re-fetch and installs A2. One unchanged `FederatedAssertionVerifier` then rejects A1-signed tokens (deadline enforced by the `key_set` read path) and accepts A2-signed tokens, proves A2's generation is strictly greater, and confirms A2's deadline is later than A1's original. Mutation oracle: replace the shared `Arc` with an independently constructed source built from the same configs and sharing the same controlled clock, warmed with a separate A1 fetch before advancement. Post-advancement, `key_set()` on the verifier's independent source filters the expired A1 snapshot (`filter(|c| now < c.hard_deadline)`) and returns no keys — the verifier never re-fetches and never observes A2. A1-reject stays green (the independent cache is also expired, so no A1 keys are served), but A2-accept flips red, because the verifier never observes A2. A2 acceptance is the reliable shared-source oracle. **Complete SSRF classifier boundary.** JWKS-boundary tests cover every newly restored class through `validate_jwks_uri` (URI-validation path): `192.0.0.1` (IETF Protocol Assignments interior), `192.0.0.9`/`.10` (PCP/TURN anycast global exceptions), `192.88.99.1` (deprecated 6to4 anycast), `2001:2::1` (2001::/23 interior), `2001:1::1` (2001::/23 global exception), `100::1` (Discard-Only), `3fff::1` (documentation), and `5f00::1` (SRv6 SIDs). URI validation and resolved-target enforcement share the same `is_not_global_unicast` predicate, so these URI-path tests exercise the complete classifier table. All pass mutation: removing any deny branch makes the rejection assertion red; removing any exception branch makes the acceptance assertion red. The resolved-target enforcement path is covered separately by `resolved_target_and_pin_key_seam_public_ipv6_and_fec0_rejection` for `::1` (loopback), public `2606:4700::1`, and `fec0::1`. --------- Signed-off-by: Will Pfleger <[email protected]> Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz> Co-authored-by: Cea Stapleton Cordasco <[email protected]>
1 parent ac4aa94 commit 70895b3

15 files changed

Lines changed: 3365 additions & 308 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,7 @@ pub const ALL_KINDS: &[u32] // 80 entries (KIND_AUTH excluded — never stored)
361361
|----------|---------|
362362
| `filters_match(filters, event)` | OR across filters, AND within each filter. Includes NIP-01 prefix matching on event IDs. |
363363
| `verify_event(event)` | Schnorr signature + SHA-256 ID check. CPU-bound — callers use `spawn_blocking`. |
364-
| `is_private_ip(ip)` | SSRF protection: IPv4 unspecified/loopback/private/link-local/CGNAT/benchmarking/broadcast + IPv6 loopback/ULA/link-local/multicast/documentation + IPv4-mapped IPv6. |
364+
| `is_not_global_unicast(ip)` | SSRF protection: enumerated-deny policy — blocks a specific set of non-public address classes and accepts everything else (including addresses not covered by an explicit deny rule, e.g. `fe00::1`). Blocked IPv4 classes: loopback, private (RFC 1918), link-local, CGNAT (RFC 6598), benchmarking (RFC 2544), IETF Protocol Assignments (192.0.0.0/24, exceptions: 192.0.0.9 PCP anycast, 192.0.0.10 TURN anycast), documentation (RFC 5737: 192.0.2/24, 198.51.100/24, 203.0.113/24), deprecated 6to4 relay anycast (192.88.99.0/24, RFC 7526), multicast (RFC 5771, 224/4), reserved/class-E (240/4). Blocked IPv6 classes: loopback, unspecified, ULA (fc00::/7), link-local (fe80::/10), deprecated site-local (fec0::/10, RFC 3879), multicast (ff00::/8), IETF Protocol Assignments envelope (2001::/23, global exceptions: 2001:1::1–::3 anycast, 2001:3::/32 AMT, 2001:4:112::/48 AS112-v6, 2001:20::/28 ORCHIDv2, 2001:30::/28 DETs), documentation (2001:db8::/32, 3fff::/20), 6to4 (2002::/16), Discard-Only (100::/64), Dummy prefix (100:0:0:1::/64), SRv6 SIDs (5f00::/16), NAT64 local-use (64:ff9b:1::/48). IPv4 embedded in mapped, compatible, NAT64 well-known (64:ff9b::/96), and SIIT IPv4-translated (::ffff:0:0:0/96) forms checked recursively. Compat alias: `is_private_ip`. |
365365

366366
**Does NOT:** store events, make network calls, spawn tasks, or depend on any async runtime.
367367

@@ -746,12 +746,10 @@ Every security-sensitive operation uses an explicit, verified pattern. No implic
746746
747747
### SSRF Protection
748748
749-
`is_private_ip()` in `buzz-core` covers:
750-
- IPv4: unspecified (0.0.0.0/8), loopback (127.0.0.0/8), private (10/8, 172.16/12, 192.168/16), link-local (169.254/16), CGNAT (100.64/10), benchmarking (198.18/15), broadcast (255.255.255.255)
751-
- IPv6: loopback (::1), ULA (fc00::/7), link-local (fe80::/10), multicast (ff00::/8), documentation (2001:db8::/32)
752-
- IPv4-mapped IPv6 (::ffff:0:0/96) — recursively checks the embedded IPv4 address
749+
`is_not_global_unicast(ip)` (compat alias `is_private_ip`) in `buzz-core` is an enumerated-deny policy: it blocks a specific set of non-public address classes and accepts everything else, including addresses not covered by an explicit deny rule (e.g. `fe00::1`). Blocked IPv4 classes: loopback (127.0.0.0/8), private RFC 1918 (10/8, 172.16/12, 192.168/16), link-local (169.254/16), unspecified (0/8), broadcast, CGNAT/RFC 6598 (100.64/10), benchmarking/RFC 2544 (198.18/15), IETF Protocol Assignments (192.0.0.0/24, globally reachable exceptions: 192.0.0.9 PCP anycast RFC 7723 and 192.0.0.10 TURN anycast RFC 8155), documentation/RFC 5737 (192.0.2/24, 198.51.100/24, 203.0.113/24), deprecated 6to4 relay anycast (192.88.99.0/24, RFC 7526, global=None/blank → conservative deny), multicast/RFC 5771 (224/4), and reserved class-E (240/4). Blocked IPv6 classes: loopback (::1), unspecified (::), ULA (fc00::/7), link-local (fe80::/10), deprecated site-local (fec0::/10, RFC 3879), multicast (ff00::/8), IETF Protocol Assignments envelope (2001::/23, global exceptions: 2001:1::1–::3 PCP/TURN/DNS-SD anycast, 2001:3::/32 AMT RFC 7450, 2001:4:112::/48 AS112-v6 RFC 7535, 2001:20::/28 ORCHIDv2 RFC 7343, 2001:30::/28 DETs RFC 9374), documentation (2001:db8::/32 RFC 3849, 3fff::/20 RFC 9637), 6to4 (2002::/16, RFC 3056), Discard-Only (100::/64, RFC 6666), Dummy IPv6 Prefix (100:0:0:1::/64, RFC 9780), SRv6 SIDs (5f00::/16, RFC 9252), and NAT64 local-use (64:ff9b:1::/48, RFC 8215). IPv4 embedded in IPv4-mapped, IPv4-compatible, and NAT64 well-known (64:ff9b::/96, RFC 6052) forms is checked recursively against the IPv4 table; SIIT IPv4-translated (::ffff:0:0:0/96) follows the same path.
753750
754-
Applied in: `buzz-workflow` (CallWebhook action), `buzz-core` (shared utility).
751+
Applied in: `buzz-auth` (JWKS boundary), `buzz-workflow` (CallWebhook action),
752+
desktop `link_preview` (SSRF check).
755753
756754
### Audit Integrity
757755

‎Cargo.lock‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ chrono = { version = "0.4", features = ["serde"] }
104104
jsonwebtoken = { version = "10.4.0", default-features = false, features = ["aws_lc_rs"] }
105105

106106
# HTTP client (webhook delivery)
107-
reqwest = { version = "0.13", features = ["json", "rustls"], default-features = false }
107+
reqwest = { version = "0.13", features = ["json", "rustls", "stream"], default-features = false }
108108

109109
# Cryptography
110110
sha2 = "0.11"

‎crates/buzz-auth/Cargo.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,16 @@ dev = []
1414
[dev-dependencies]
1515
# `use_pem` enables EncodingKey::from_ec_pem for minting ES256 test assertions.
1616
jsonwebtoken = { version = "10.4.0", default-features = false, features = ["aws_lc_rs", "use_pem"] }
17+
tokio = { workspace = true, features = ["test-util"] }
1718

1819
[dependencies]
1920
buzz-core = { workspace = true }
2021
base64 = { workspace = true }
2122
chrono = { workspace = true }
2223
jsonwebtoken = { workspace = true }
2324
nostr = { workspace = true }
25+
futures-util = { workspace = true }
26+
reqwest = { workspace = true }
2427
serde = { workspace = true }
2528
serde_json = { workspace = true }
2629
tokio = { workspace = true }

‎crates/buzz-auth/src/lib.rs‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,14 @@ pub use rate_limit::{
4646
pub use scope::{parse_scopes, Scope};
4747

4848
pub use nip_fi::{
49-
AssertionKeySet, AssertionPolicyId, CanonicalCapabilities, ClientSubjectPosture,
50-
ConfidentialAssertion, DenialClass, FederatedAssertionVerifier, FederatedIdentity,
51-
FreshnessClass, IssuerKeySource, IssuerPolicy, IssuerPolicyError, IssuerRegistry,
52-
RevalidationDependencies, SubjectClass, SubjectClassContract, TokenClass, TransportContractId,
53-
VerifiedAssertion, VerifierError, CLIENT_ATTACHED_HEADER, NOSTR_PUBKEY_CLAIM,
54-
OAUTH_CLIENT_ID_CLAIM,
49+
validate_nip_fi_config, AssertionKeySet, AssertionPolicyId, CanonicalCapabilities,
50+
ClientSubjectPosture, ConfidentialAssertion, DenialClass, FederatedAssertionVerifier,
51+
FederatedIdentity, FederatedIdentityDiscovery, FreshnessClass, HttpJwksFetcher,
52+
IssuerJwksConfig, IssuerKeySource, IssuerPolicy, IssuerPolicyError, IssuerRegistry,
53+
JwksFetchError, JwksFetcher, JwksSourceContract, NipFiMode, NipFiStartupError,
54+
ProductionJwksSource, RevalidationDependencies, SubjectClass, SubjectClassContract, TokenClass,
55+
TransportContractId, VerifiedAssertion, VerifierError, CLIENT_ATTACHED_HEADER,
56+
NOSTR_PUBKEY_CLAIM, OAUTH_CLIENT_ID_CLAIM,
5557
};
5658

5759
#[cfg(any(test, feature = "test-utils"))]

‎crates/buzz-auth/src/nip_fi/config.rs‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ use sha2::{Digest, Sha256};
2727
use std::collections::BTreeMap;
2828
use std::fmt;
2929

30+
use super::jwks::JwksSourceContract;
31+
3032
/// Maximum accepted length of an `iss` or `aud` string.
3133
const MAX_URI_LEN: usize = 2_048;
3234
/// Maximum accepted length of a claim name.
@@ -349,6 +351,11 @@ pub struct IssuerPolicy {
349351
skew_seconds: u64,
350352
maximum_assertion_age_seconds: u64,
351353
maximum_status_age_seconds: Option<u64>,
354+
/// The authenticated key-source contract: validated JWKS URI, refresh
355+
/// interval, and hard deadline. Included in `derive_assertion_policy_id`
356+
/// so that a change to the endpoint, refresh schedule, or hard-deadline
357+
/// rule changes the policy ID and invalidates all prepared evidence.
358+
jwks_source_contract: JwksSourceContract,
352359
id: AssertionPolicyId,
353360
}
354361

@@ -382,6 +389,10 @@ pub enum IssuerPolicyError {
382389
/// so subject classification could not be total and mutually exclusive.
383390
#[error("subject class contract is not exclusive")]
384391
NonExclusiveSubjectClass,
392+
/// The [`JwksSourceContract`] was not valid — invalid URI, zero or
393+
/// out-of-range timing, or `refresh_interval >= hard_deadline`.
394+
#[error("invalid JWKS source contract")]
395+
InvalidJwksSourceContract,
385396
}
386397

387398
impl IssuerPolicy {
@@ -397,6 +408,7 @@ impl IssuerPolicy {
397408
skew_seconds: u64,
398409
maximum_assertion_age_seconds: u64,
399410
maximum_status_age_seconds: Option<u64>,
411+
jwks_source_contract: JwksSourceContract,
400412
) -> Result<Self, IssuerPolicyError> {
401413
// Identity-bearing strings are validated for bounds but never mutated:
402414
// exact `iss`/`aud`/`sub` bytes select policies and form the identity
@@ -459,6 +471,7 @@ impl IssuerPolicy {
459471
skew_seconds,
460472
maximum_assertion_age_seconds,
461473
maximum_status_age_seconds,
474+
&jwks_source_contract,
462475
);
463476

464477
Ok(Self {
@@ -471,6 +484,7 @@ impl IssuerPolicy {
471484
skew_seconds,
472485
maximum_assertion_age_seconds,
473486
maximum_status_age_seconds,
487+
jwks_source_contract,
474488
id,
475489
})
476490
}
@@ -524,6 +538,11 @@ impl IssuerPolicy {
524538
pub const fn id(&self) -> AssertionPolicyId {
525539
self.id
526540
}
541+
542+
/// The authenticated key-source contract for this policy's JWKS endpoint.
543+
pub fn jwks_source_contract(&self) -> &JwksSourceContract {
544+
&self.jwks_source_contract
545+
}
527546
}
528547

529548
/// A closed set of issuer policies keyed by exact `iss`. Selection preserves
@@ -560,6 +579,12 @@ impl IssuerRegistry {
560579
pub fn is_empty(&self) -> bool {
561580
self.policies.is_empty()
562581
}
582+
583+
/// Iteration order is deliberately unspecified; callers must not depend on
584+
/// registration order.
585+
pub fn all_policies(&self) -> impl Iterator<Item = &IssuerPolicy> {
586+
self.policies.values()
587+
}
563588
}
564589

565590
/// Sort and deduplicate a set-valued list of strings into its canonical form.
@@ -625,6 +650,7 @@ fn derive_assertion_policy_id(
625650
skew_seconds: u64,
626651
maximum_assertion_age_seconds: u64,
627652
maximum_status_age_seconds: Option<u64>,
653+
jwks_source_contract: &JwksSourceContract,
628654
) -> AssertionPolicyId {
629655
let mut hasher = Sha256::new();
630656
hasher.update(b"buzz:nip-fi:assertion-policy:v1\0");
@@ -680,6 +706,23 @@ fn derive_assertion_policy_id(
680706
hasher.update(skew_seconds.to_be_bytes());
681707
hasher.update(maximum_assertion_age_seconds.to_be_bytes());
682708
hasher.update(maximum_status_age_seconds.unwrap_or(0).to_be_bytes());
709+
// Authenticated key-source contract (NIP-FI.md, "Policy identity and
710+
// snapshots"): URI selects the authenticated source; interval defines
711+
// bounded refresh; hard deadline defines the accepted time rule. These are
712+
// contract, not mutable state — key rotation (JWKS content change) leaves
713+
// all three unchanged and must not move the ID.
714+
hasher.update(b"jwks-source-contract\0");
715+
hash_field(&mut hasher, jwks_source_contract.jwks_uri().as_bytes());
716+
hasher.update(
717+
jwks_source_contract
718+
.refresh_interval_seconds()
719+
.to_be_bytes(),
720+
);
721+
hasher.update(
722+
jwks_source_contract
723+
.key_snapshot_hard_deadline_seconds()
724+
.to_be_bytes(),
725+
);
683726
AssertionPolicyId(hasher.finalize().into())
684727
}
685728

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
//! NIP-11 federated-identity discovery output.
2+
//!
3+
//! [`FederatedIdentityDiscovery`] serializes to the `federated_identity`
4+
//! object required by the NIP-FI.md "Discovery" section of the NIP-11 relay
5+
//! information document.
6+
//!
7+
//! ## Privacy invariants
8+
//!
9+
//! The discovery object MUST NOT contain: enrollment mode, TOFU posture,
10+
//! issuer URLs, audiences, claim names, tenant IDs, or deployment-local
11+
//! identifiers. For a fixed set of claimed profiles the complete output is
12+
//! byte-identical across every enrollment policy and lifecycle state.
13+
//! [FI-TRACE-DISCOVERY-PRIVATE]
14+
//!
15+
//! ## Offline-jwt residual bound
16+
//!
17+
//! `maximum_residual_upstream_revocation_seconds` is `null` for `offline-jwt`
18+
//! deployments. An offline-jwt deployment MUST NOT advertise a finite value
19+
//! here (NIP-FI.md:259-266).
20+
21+
use serde::{Deserialize, Serialize};
22+
23+
/// The `assertion_freshness` sub-object in the `federated_identity` discovery
24+
/// document. Describes the claimed freshness posture without exposing any
25+
/// issuer or deployment-private state.
26+
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
27+
pub struct AssertionFreshnessDiscovery {
28+
/// The wire string identifying the freshness class.
29+
pub class: FreshnessClassDiscovery,
30+
/// `null` for `offline-jwt`; advertising a finite bound here requires a
31+
/// live status witness that is not yet implemented.
32+
pub maximum_residual_upstream_revocation_seconds: Option<u64>,
33+
}
34+
35+
/// The freshness class as a stable NIP-FI wire string.
36+
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
37+
#[serde(rename_all = "kebab-case")]
38+
pub enum FreshnessClassDiscovery {
39+
/// No revocation bound is claimed; JWKS snapshot validation only.
40+
OfflineJwt,
41+
}
42+
43+
/// The `federated_identity` NIP-11 discovery object. Fields never expose
44+
/// enrollment mode, issuer, audience, or private state.
45+
/// [FI-TRACE-DISCOVERY-PRIVATE]
46+
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
47+
pub struct FederatedIdentityDiscovery {
48+
/// Fixed value `"client-attached"` for the core NIP-FI transport mode.
49+
pub core: String,
50+
/// The freshness contract claimed by this deployment.
51+
pub assertion_freshness: AssertionFreshnessDiscovery,
52+
}
53+
54+
impl FederatedIdentityDiscovery {
55+
/// The only supported posture: claims no residual revocation bound, which
56+
/// is the honest description of JWKS-only assertion verification.
57+
pub fn offline_jwt() -> Self {
58+
Self {
59+
core: "client-attached".to_owned(),
60+
assertion_freshness: AssertionFreshnessDiscovery {
61+
class: FreshnessClassDiscovery::OfflineJwt,
62+
maximum_residual_upstream_revocation_seconds: None,
63+
},
64+
}
65+
}
66+
}

0 commit comments

Comments
 (0)