refactor(authority): encode unsigned non-zero runtime TTLs (#615)

## Why

The schema owns human-readable non-zero duration parsing, while
downstream Authority contracts consume exact positive whole-second
integers. This internal refactor makes both validated runtime TTL states
unsigned and non-zero without changing configuration or the existing
signed protobuf request contract.

## What changed

- Store private validated `max_ttl_seconds` and `bundle_ttl_seconds` as
`std::num::NonZeroU32`.
- Convert schema-validated `NonZeroDuration` values once through
`AuthorityConfigBuilder`: require whole seconds, retain the `i32::MAX`
maximum-token-TTL bound, and checked-narrow to standard non-zero
integers.
- Keep Authority service state, issuance clamping, and effective TTLs
unsigned and non-zero; call `.get()` only at Chrono, Cedar,
policy-bundle, library, or wire integer boundaries.
- Keep protobuf `requested_ttl_seconds: i32` unchanged. The issuance
adapter normalizes it once: `<= 0` selects the configured maximum; a
positive request becomes `NonZeroU32` and clamps against that unsigned
maximum.
- Cover negative, zero, positive, and over-maximum requests plus exact
claim and protobuf expiry behavior.

## Contract

No user, TOML, environment, or wire change is introduced. Compact
duration syntax, `"1h"` / `"30s"` defaults, canonical
`FIRMA_AUTHORITY_MAX_TTL` / `FIRMA_AUTHORITY_BUNDLE_TTL` precedence,
whole-second and range errors, and effective values remain unchanged.

Runtime uses `NonZeroU32` rather than a duration type because its
consumers are exact positive whole-second integer boundaries; schema
parsing remains owned by `NonZeroDuration`. The remaining signed
protobuf request and non-positive sentinel are intentionally deferred to
a separate follow-up.

## Atomic revisions

1.
[`32539c5c`](32539c5)
— accepted plan and plan-review dispositions.
2.
[`20f0e090`](20f0e09)
— encode maximum-token-TTL runtime/config/service/issuance state as
`NonZeroU32`.
3.
[`ae6c1c31`](ae6c1c3)
— encode bundle-TTL runtime/config/consumer state as `NonZeroU32`.
4.
[`ad1c34eb`](ad1c34e)
— record the independent implementation review.
5.
[`8a6e26aa`](8a6e26a)
— record the atomic-commit re-review.
6.
[`d01d9c11`](d01d9c1)
— mechanically remove the plan artifact.

## Plan and independent review

- Accepted plan and plan-review dispositions: [`32539c5c:
authority-non-zero-runtime-ttl-plan.md`](https://github.com/Firma-AI/openfirma/blob/32539c5cedb0fe31f08a6d8ca1f8db468df2d15f/docs/architecture/authority-non-zero-runtime-ttl-plan.md).
- Independent implementation review:
[`ad1c34eb`](https://github.com/Firma-AI/openfirma/blob/ad1c34eb09bfbb2f2e3cd59832e1510427e3827e/docs/architecture/authority-non-zero-runtime-ttl-plan.md#post-implementation-adversarial-review).
- Atomic-commit re-review:
[`8a6e26aa`](https://github.com/Firma-AI/openfirma/blob/8a6e26aaa4078c3fc4db1f39d008cd1ff5e569a8/docs/architecture/authority-non-zero-runtime-ttl-plan.md).
- Immediate mechanical plan removal:
[`d01d9c11`](d01d9c1).
No plan Markdown remains at the tip or in the PR diff.

Author: LukeMathWalker

crates/firma-authority/src/config.rs

@@ -1,4 +1,5 @@
 use firma_config_schema::authority as schema;
+use std::num::{NonZeroU32, NonZeroU64};
 use std::path::{Path, PathBuf};
 
 /// Authority configuration loaded from TOML file and/or environment variables.
@@ -36,12 +37,12 @@ pub struct AuthorityConfig {
     pub(crate) schema_path: Option<PathBuf>,
     /// Path to the revocation file (one token ID per line).
     pub(crate) revocation_file: PathBuf,
-    /// Maximum token TTL in seconds (default: 3600).
-    pub(crate) max_ttl_seconds: i32,
+    /// Strictly positive maximum token TTL in whole seconds.
+    max_ttl_seconds: NonZeroU32,
     /// Path to the Ed25519 signing key file (64-byte raw or PEM).
     pub(crate) key_file: PathBuf,
-    /// Policy bundle TTL advertised to sidecars in seconds (default: 30).
-    pub(crate) bundle_ttl_seconds: u32,
+    /// Strictly positive policy bundle TTL advertised to sidecars in whole seconds.
+    bundle_ttl_seconds: NonZeroU32,
     /// Authority TLS configuration.
     pub(crate) tls: AuthorityTlsConfig,
 }
@@ -74,9 +75,9 @@ impl AuthorityConfig {
         &self.revocation_file
     }
 
-    /// Maximum token TTL in seconds.
+    /// Strictly positive maximum token TTL in whole seconds.
     #[must_use]
-    pub fn max_ttl_seconds(&self) -> i32 {
+    pub const fn max_ttl_seconds(&self) -> NonZeroU32 {
         self.max_ttl_seconds
     }
 
@@ -86,9 +87,9 @@ impl AuthorityConfig {
         &self.key_file
     }
 
-    /// Policy bundle TTL advertised to sidecars in seconds.
+    /// Strictly positive policy bundle TTL advertised to sidecars in whole seconds.
     #[must_use]
-    pub fn bundle_ttl_seconds(&self) -> u32 {
+    pub const fn bundle_ttl_seconds(&self) -> NonZeroU32 {
         self.bundle_ttl_seconds
     }
 
@@ -179,12 +180,26 @@ impl AuthorityConfig {
                 field: "authority.bundle_ttl",
             });
         }
-        let max_ttl_seconds = i32::try_from(max_ttl.as_secs()).map_err(|_| {
+        let max_ttl_seconds =
+            NonZeroU64::new(max_ttl.as_secs()).ok_or(AuthorityConfigError::DurationOutOfRange {
+                field: "authority.max_ttl",
+            })?;
+        if max_ttl_seconds.get() > u64::from(i32::MAX.unsigned_abs()) {
+            return Err(AuthorityConfigError::DurationOutOfRange {
+                field: "authority.max_ttl",
+            });
+        }
+        let max_ttl_seconds = NonZeroU32::try_from(max_ttl_seconds).map_err(|_| {
             AuthorityConfigError::DurationOutOfRange {
                 field: "authority.max_ttl",
             }
         })?;
-        let bundle_ttl_seconds = u32::try_from(bundle_ttl.as_secs()).map_err(|_| {
+        let bundle_ttl_seconds = NonZeroU64::new(bundle_ttl.as_secs()).ok_or(
+            AuthorityConfigError::DurationOutOfRange {
+                field: "authority.bundle_ttl",
+            },
+        )?;
+        let bundle_ttl_seconds = NonZeroU32::try_from(bundle_ttl_seconds).map_err(|_| {
             AuthorityConfigError::DurationOutOfRange {
                 field: "authority.bundle_ttl",
             }
@@ -216,18 +231,15 @@ impl AuthorityConfig {
     ///
     /// # Errors
     ///
-    /// Returns [`ConfigError::DurationNotPositive`] if either runtime TTL
-    /// cannot be represented as a non-zero schema duration.
+    /// This conversion is infallible for builder-produced runtime state. The
+    /// result remains fallible for API compatibility with existing callers.
     pub fn to_schema(&self) -> Result<schema::AuthorityConfig, ConfigError> {
-        let max_ttl_seconds =
-            u64::try_from(self.max_ttl_seconds).map_err(|_| ConfigError::DurationNotPositive {
-                field: "authority.max_ttl",
-            })?;
-        let max_ttl = non_zero_duration_from_seconds("authority.max_ttl", max_ttl_seconds)?;
-        let bundle_ttl = non_zero_duration_from_seconds(
-            "authority.bundle_ttl",
-            u64::from(self.bundle_ttl_seconds),
-        )?;
+        let max_ttl = firma_config_schema::utils::NonZeroDuration::from(NonZeroU64::from(
+            self.max_ttl_seconds,
+        ));
+        let bundle_ttl = firma_config_schema::utils::NonZeroDuration::from(NonZeroU64::from(
+            self.bundle_ttl_seconds,
+        ));
 
         Ok(schema::AuthorityConfig {
             listen_addr: self.listen_addr.clone(),
@@ -247,14 +259,6 @@ impl AuthorityConfig {
     }
 }
 
-fn non_zero_duration_from_seconds(
-    field: &'static str,
-    seconds: u64,
-) -> Result<firma_config_schema::utils::NonZeroDuration, ConfigError> {
-    firma_config_schema::utils::NonZeroDuration::new(std::time::Duration::from_secs(seconds))
-        .map_err(|_| ConfigError::DurationNotPositive { field })
-}
-
 /// Assembles a validated [`AuthorityConfig`].
 ///
 /// The builder retains the schema representation while applying path rebasing
@@ -589,8 +593,8 @@ mod tests {
     fn default_config_has_sensible_values() -> anyhow::Result<()> {
         let config = AuthorityConfigBuilder::default().build()?;
         assert_eq!(config.listen_addr, "[::1]:50051");
-        assert_eq!(config.max_ttl_seconds, 3600);
-        assert_eq!(config.bundle_ttl_seconds, 30);
+        assert_eq!(config.max_ttl_seconds.get(), 3600);
+        assert_eq!(config.bundle_ttl_seconds.get(), 30);
 
         Ok(())
     }
@@ -678,7 +682,7 @@ mod tests {
         )
         .unwrap();
         let c = AuthorityConfig::load_resolved(&p, tmp.path()).unwrap();
-        assert_eq!(c.max_ttl_seconds, 1800);
+        assert_eq!(c.max_ttl_seconds.get(), 1800);
         assert_eq!(c.policy_dir, tmp.path().join("policies"));
         assert_eq!(c.tls.cert, Some(tmp.path().join("authority.crt")));
         assert_eq!(c.tls.key, Some(tmp.path().join("authority.key")));
@@ -696,9 +700,9 @@ max_ttl = "30m"
             .build()
             .unwrap_or_else(|e| panic!("{e}"));
         assert_eq!(config.listen_addr, "0.0.0.0:9090");
-        assert_eq!(config.max_ttl_seconds, 1800);
+        assert_eq!(config.max_ttl_seconds.get(), 1800);
         // Defaults for unspecified fields
-        assert_eq!(config.bundle_ttl_seconds, 30);
+        assert_eq!(config.bundle_ttl_seconds.get(), 30);
     }
 
     #[test]

crates/firma-authority/src/issuance.rs

@@ -6,6 +6,7 @@
 //! transport (`tonic`) or process-IO dependency so it is straightforward
 //! to call from a CLI in-process and to unit-test.
 
+use std::num::NonZeroU32;
 use std::sync::Arc;
 
 use chrono::{DateTime, Duration, Utc};
@@ -57,7 +58,7 @@ pub enum IssuanceError {
 pub async fn issue_capability(
     policy_store: &CedarPolicyStore,
     signer: &Arc<PasetoV4Signer>,
-    max_ttl_seconds: i32,
+    max_ttl_seconds: NonZeroU32,
     req: &IssuanceRequest<'_>,
 ) -> Result<IssuanceResult, IssuanceError> {
     let snapshot = policy_store.snapshot().await;
@@ -79,7 +80,7 @@ pub async fn issue_capability(
 
     let ttl = clamp_ttl(req.requested_ttl_seconds, max_ttl_seconds);
     let now: DateTime<Utc> = Utc::now();
-    let expiry = now + Duration::seconds(i64::from(ttl));
+    let expiry = now + Duration::seconds(i64::from(ttl.get()));
     let token_id = TokenId::generate();
     let bundle_version = policy_store.bundle().version;
     let agent_id = req.agent_id.to_string();
@@ -111,6 +112,11 @@ mod tests {
     use pasetors::keys::{AsymmetricKeyPair, Generate};
     use pasetors::version4::V4;
 
+    fn max_ttl(seconds: u32) -> NonZeroU32 {
+        assert!(seconds > 0);
+        NonZeroU32::new(seconds).unwrap_or(NonZeroU32::MIN)
+    }
+
     fn fixture_policy_store() -> Arc<CedarPolicyStore> {
         let dir = tempfile::tempdir().unwrap().keep();
         std::fs::write(
@@ -141,12 +147,44 @@ mod tests {
             resource_scope: "wttr.in*",
             requested_ttl_seconds: 300,
         };
-        let out = issue_capability(&store, &signer, 600, &req).await.unwrap();
+        let out = issue_capability(&store, &signer, max_ttl(600), &req)
+            .await
+            .unwrap();
         assert!(!out.raw_token.is_empty());
         assert_eq!(out.claims.action_set, actions);
         assert_eq!(out.claims.resource_scope, "wttr.in*");
     }
 
+    #[tokio::test]
+    async fn signed_request_ttl_preserves_exact_expiry_semantics() {
+        let store = fixture_policy_store();
+        let kp = AsymmetricKeyPair::<V4>::generate().unwrap();
+        let signer = Arc::new(PasetoV4Signer::try_new(kp.secret.as_bytes()).unwrap());
+        let agent: AgentId = "agt_01j0000000e008000000000001".parse().unwrap();
+        let session: SessionId = "sess_1".parse().unwrap();
+        let actions = vec!["communication.external.send".to_string()];
+
+        for (requested_ttl_seconds, expected_ttl_seconds) in
+            [(-1, 600), (0, 600), (300, 300), (900, 600)]
+        {
+            let req = IssuanceRequest {
+                agent_id: &agent,
+                session_id: &session,
+                requested_actions: &actions,
+                resource_scope: "wttr.in*",
+                requested_ttl_seconds,
+            };
+            let out = issue_capability(&store, &signer, max_ttl(600), &req)
+                .await
+                .unwrap();
+
+            assert_eq!(
+                (out.claims.expiry - out.claims.issued_at).num_seconds(),
+                expected_ttl_seconds
+            );
+        }
+    }
+
     /// Policy store that permits exactly one action class; all others
     /// default-deny so the grant narrows to the authorized subset.
     fn store_permitting(action: &str) -> Arc<CedarPolicyStore> {
@@ -183,7 +221,9 @@ mod tests {
             resource_scope: "*",
             requested_ttl_seconds: 300,
         };
-        let out = issue_capability(&store, &signer, 600, &req).await.unwrap();
+        let out = issue_capability(&store, &signer, max_ttl(600), &req)
+            .await
+            .unwrap();
         assert_eq!(out.claims.action_set, vec!["code.read".to_string()]);
     }
 
@@ -202,7 +242,7 @@ mod tests {
             resource_scope: "*",
             requested_ttl_seconds: 300,
         };
-        let err = issue_capability(&store, &signer, 600, &req)
+        let err = issue_capability(&store, &signer, max_ttl(600), &req)
             .await
             .unwrap_err();
         match err {
@@ -238,7 +278,7 @@ mod tests {
             resource_scope: "wttr.in*",
             requested_ttl_seconds: 300,
         };
-        let err = issue_capability(&store, &signer, 600, &req)
+        let err = issue_capability(&store, &signer, max_ttl(600), &req)
             .await
             .unwrap_err();
         match err {

crates/firma-authority/src/server.rs

@@ -136,25 +136,25 @@ fn load_authority_service(config: &AuthorityConfig) -> Result<AuthorityServiceIm
     let policy_store = CedarPolicyStore::load(
         &config.policy_dir,
         config.schema_path.clone(),
-        config.bundle_ttl_seconds,
+        config.bundle_ttl_seconds().get(),
     )?;
 
     tracing::info!(issuance_policy_dir = %config.issuance_policy_dir.display(), "loading issuance policy store");
     let issuance_policy_store = CedarPolicyStore::load(
         &config.issuance_policy_dir,
         config.schema_path.clone(),
-        config.bundle_ttl_seconds,
+        config.bundle_ttl_seconds().get(),
     )?;
 
-    let token_ttl = chrono::Duration::seconds(i64::from(config.max_ttl_seconds));
+    let token_ttl = chrono::Duration::seconds(i64::from(config.max_ttl_seconds().get()));
     let revocation_store = RevocationStore::try_new(&config.revocation_file, token_ttl)?;
 
     AuthorityServiceImpl::try_new(
         issuance_policy_store,
         policy_store,
         revocation_store,
         signer,
-        config.max_ttl_seconds,
+        config.max_ttl_seconds(),
     )
 }
 

crates/firma-authority/src/service.rs

@@ -1,4 +1,5 @@
 use std::collections::BTreeSet;
+use std::num::NonZeroU32;
 use std::pin::Pin;
 use std::sync::Arc;
 
@@ -37,7 +38,7 @@ pub struct AuthorityServiceImpl {
     /// and read in-memory revocation state via `Deref<Target = RevocationStore>`.
     revocation_watcher: RevocationStoreWatcher,
     signer: Arc<PasetoV4Signer>,
-    max_ttl_seconds: i32,
+    max_ttl_seconds: NonZeroU32,
 }
 
 impl AuthorityServiceImpl {
@@ -49,7 +50,7 @@ impl AuthorityServiceImpl {
         policy_store: CedarPolicyStore,
         revocation_store: RevocationStore,
         signer: Arc<PasetoV4Signer>,
-        max_ttl_seconds: i32,
+        max_ttl_seconds: NonZeroU32,
     ) -> anyhow::Result<Self> {
         let issuance_policy_watcher = issuance_policy_store.watch()?;
         let policy_watcher = policy_store.watch()?;
@@ -597,19 +598,22 @@ pub(crate) fn compute_context_hash(
     hex::encode(hasher.finalize())
 }
 
-/// FR-4: Clamp requested TTL to the configured maximum.
-pub(crate) fn clamp_ttl(requested: i32, max: i32) -> i32 {
-    if requested <= 0 {
-        max
-    } else {
-        requested.min(max)
-    }
+/// FR-4: Normalize a signed protocol request and clamp it to the configured maximum.
+pub(crate) fn clamp_ttl(requested: i32, max: NonZeroU32) -> NonZeroU32 {
+    u32::try_from(requested)
+        .ok()
+        .and_then(NonZeroU32::new)
+        .map_or(max, |requested| requested.min(max))
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    fn max_ttl() -> NonZeroU32 {
+        NonZeroU32::new(3600).unwrap_or(NonZeroU32::MIN)
+    }
+
     fn agent(id: &str) -> AgentId {
         id.parse().unwrap()
     }
@@ -624,22 +628,22 @@ mod tests {
 
     #[test]
     fn clamp_ttl_within_max() {
-        assert_eq!(clamp_ttl(600, 3600), 600);
+        assert_eq!(clamp_ttl(600, max_ttl()).get(), 600);
     }
 
     #[test]
     fn clamp_ttl_exceeds_max() {
-        assert_eq!(clamp_ttl(7200, 3600), 3600);
+        assert_eq!(clamp_ttl(7200, max_ttl()).get(), 3600);
     }
 
     #[test]
     fn clamp_ttl_zero_uses_max() {
-        assert_eq!(clamp_ttl(0, 3600), 3600);
+        assert_eq!(clamp_ttl(0, max_ttl()).get(), 3600);
     }
 
     #[test]
     fn clamp_ttl_negative_uses_max() {
-        assert_eq!(clamp_ttl(-1, 3600), 3600);
+        assert_eq!(clamp_ttl(-1, max_ttl()).get(), 3600);
     }
 
     fn permit_all() -> PolicySet {