feat: signed CRL, trust token revocation, async fingerprinting, DID rate limiting

Add pull-based signed CRL endpoint (GET /crl, /.well-known/airlock-crl) with
Ed25519 signatures, monotonic crl_number, ETag caching, and tiered freshness
degradation (NORMAL → DEGRADED → EMERGENCY → FAIL_CLOSED). Separate CRL
signing key support via crl_signing_key_hex config.

Trust token decode now checks revocation status — revoked/suspended DIDs are
rejected at introspect time even if the JWT is unexpired. Default TTL reduced
from 600s to 120s to shrink the revocation gap window.

FingerprintStore converted from threading.Lock to asyncio.Lock for non-blocking
concurrent request handling. Sync wrappers preserved for backward compatibility.

DID-based rate limiting extracted into DIDRateLimiter class with DID format
validation, structured 429 error responses, and Retry-After headers.

IETF BCP 72 Security Considerations document (1,400+ lines) covering threat
model, identity attacks, trust scoring, PoW, semantic challenges, privacy,
network attacks, token security, revocation, federation, and operational
security.

601 tests, 0 failures.

Signed-off-by: Shivdeep Singh <shivdeepsachdeva@gmail.com>

Author: shivdeep1

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to the Airlock Protocol are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-04-05
+
+### Fixed
+- **PoW Challenge Replay** (CRITICAL): `verify_pow()` now validates challenges against a server-side store with one-time use enforcement and expiry checks
+- **RFC 8785 Canonical JSON** (CRITICAL): Removed `default=str` from `canonicalize()` — explicit type conversion ensures cross-language signature verification (Go, Rust, JS)
+
+### Changed
+- **Revocation model**: `revoke()` is now permanent and irreversible for key compromise scenarios; added `suspend()`/`reinstate()` for reversible holds
+- **Attestation signing**: `AirlockAttestation.airlock_signature` is now populated with a real Ed25519 signature, enabling cryptographic verification by relying parties
+- Added `RevocationReason` enum with 7 reason codes
+- New admin endpoints: `POST /admin/suspend/{did}`, `POST /admin/reinstate/{did}`
+
+### Removed
+- `unrevoke()` method — replaced by `suspend()`/`reinstate()`
+- `DELETE /admin/revoke/{did}` endpoint
+
+### Security
+- 4 security audit documents added to `docs/security/`
+
 ## [0.2.0] - 2026-04-05
 
 ### Added

airlock/config.py

@@ -47,7 +47,7 @@ class AirlockConfig(BaseSettings):
 
     # HS256 trust token issued only on VERIFIED (set secret in production).
     trust_token_secret: str = ""
-    trust_token_ttl_seconds: int = Field(default=600, ge=60, le=86_400)
+    trust_token_ttl_seconds: int = Field(default=120, ge=60, le=86_400)
 
     # Comma-separated issuer DIDs; empty = any issuer (dev). Non-empty = VC issuer must match.
     vc_issuer_allowlist: str = ""
@@ -153,6 +153,16 @@ class AirlockConfig(BaseSettings):
     fingerprint_exact_duplicate_action: str = "fail"
     fingerprint_near_duplicate_action: str = "flag"
 
+    # -----------------------------------------------------------------------
+    # CRL (Certificate Revocation List)
+    # -----------------------------------------------------------------------
+    crl_update_interval_seconds: int = Field(default=60, ge=30, le=600)
+    crl_max_cache_age_seconds: int = Field(default=300, ge=60, le=3600)
+    crl_emergency_cache_age_seconds: int = Field(default=3600, ge=300, le=86400)
+    # Separate CRL signing key (hex-encoded 32-byte Ed25519 seed).
+    # Falls back to gateway_seed_hex if empty.
+    crl_signing_key_hex: str = ""
+
     # Event bus drain timeout during shutdown (seconds).
     event_bus_drain_timeout_seconds: float = Field(default=30.0, ge=1.0, le=600.0)
 

airlock/crypto/signing.py

@@ -24,7 +24,7 @@ def _prepare_for_json(obj: Any) -> Any:
     """Recursively convert Python objects to JSON-safe, cross-language types.
 
     Ensures deterministic serialization that produces identical output in
-    Python, Go, Rust, and JavaScript implementations (C-09 interop fix).
+    Python, Go, Rust, and JavaScript implementations.
 
     Conversion rules:
     - datetime     -> ISO 8601 with timezone (naive datetimes treated as UTC)
@@ -93,7 +93,7 @@ def canonicalize(data: dict[str, Any]) -> bytes:
     All values are first normalized via ``_prepare_for_json`` so that
     datetimes, enums, UUIDs, bytes, etc. are converted to language-agnostic
     representations *before* JSON encoding.  This guarantees identical
-    canonical bytes across Python, Go, Rust, and JavaScript (C-09 fix).
+    canonical bytes across Python, Go, Rust, and JavaScript.
 
     Strips known signature/token fields so we sign the unsigned form.
     """

airlock/gateway/app.py

@@ -17,12 +17,13 @@
 from airlock.engine.event_bus import EventBus
 from airlock.engine.orchestrator import VerificationOrchestrator
 from airlock.engine.state import SessionManager
+from airlock.gateway.crl import CRLGenerator
 from airlock.gateway.identity import gateway_keypair_from_config
 from airlock.gateway.logging_config import configure_airlock_logging
 from airlock.gateway.metrics import HttpRequestMetrics
 from airlock.gateway.observability import add_observability_middleware
 from airlock.gateway.policy import parse_did_allowlist
-from airlock.gateway.rate_limit import InMemorySlidingWindow, RedisSlidingWindow
+from airlock.gateway.rate_limit import DIDRateLimiter, InMemorySlidingWindow, RedisSlidingWindow
 from airlock.gateway.replay import InMemoryReplayGuard, RedisReplayGuard
 from airlock.gateway.revocation import RedisRevocationStore, RevocationStore
 from airlock.gateway.startup_validate import AirlockStartupError, validate_startup_config
@@ -89,24 +90,24 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
                 max_events=cfg.rate_limit_per_ip_per_minute,
                 window_seconds=60.0,
             )
-            rate_limit_handshake_did: RedisSlidingWindow | InMemorySlidingWindow = (
-                RedisSlidingWindow(
-                    redis_client,
-                    max_events=cfg.rate_limit_handshake_per_did_per_minute,
-                    window_seconds=60.0,
-                )
+            _did_backend: RedisSlidingWindow | InMemorySlidingWindow = RedisSlidingWindow(
+                redis_client,
+                max_events=cfg.rate_limit_handshake_per_did_per_minute,
+                window_seconds=60.0,
             )
         else:
             nonce_guard = InMemoryReplayGuard(ttl_seconds=cfg.nonce_replay_ttl_seconds)
             rate_limit_ip = InMemorySlidingWindow(
                 max_events=cfg.rate_limit_per_ip_per_minute,
                 window_seconds=60.0,
             )
-            rate_limit_handshake_did = InMemorySlidingWindow(
+            _did_backend = InMemorySlidingWindow(
                 max_events=cfg.rate_limit_handshake_per_did_per_minute,
                 window_seconds=60.0,
             )
 
+        did_rate_limiter = DIDRateLimiter(_did_backend)
+
         vc_allowed = parse_did_allowlist(cfg.vc_issuer_allowlist)
         rate_limit_register_hour: RedisSlidingWindow | InMemorySlidingWindow | None = None
         if cfg.register_max_per_ip_per_hour > 0:
@@ -129,6 +130,26 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         else:
             revocation_store = RevocationStore()
 
+        # ---- CRL generator ----
+        crl_signing_seed = (cfg.crl_signing_key_hex or "").strip()
+        if len(crl_signing_seed) == 64:
+            try:
+                from nacl.signing import SigningKey as _NaClSigningKey
+
+                crl_signing_key = _NaClSigningKey(bytes.fromhex(crl_signing_seed))
+            except (ValueError, Exception):
+                crl_signing_key = airlock_kp.signing_key
+        else:
+            crl_signing_key = airlock_kp.signing_key
+
+        crl_generator = CRLGenerator(
+            revocation_store=revocation_store,
+            signing_key=crl_signing_key,
+            issuer_did=airlock_kp.did,
+            update_interval_seconds=cfg.crl_update_interval_seconds,
+            max_cache_age_seconds=cfg.crl_max_cache_age_seconds,
+        )
+
         audit_trail = AuditTrail()
 
         _tok = (cfg.trust_token_secret or "").strip()
@@ -157,11 +178,12 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         app.state.agent_registry = agent_registry
         app.state.heartbeat_store = heartbeat_store
         app.state.revocation_store = revocation_store
+        app.state.crl_generator = crl_generator
         app.state.audit_trail = audit_trail
         app.state.airlock_kp = airlock_kp
         app.state.nonce_guard = nonce_guard
         app.state.rate_limit_ip = rate_limit_ip
-        app.state.rate_limit_handshake_did = rate_limit_handshake_did
+        app.state.did_rate_limiter = did_rate_limiter
         app.state.rate_limit_register_hour = rate_limit_register_hour
         app.state.http_metrics = HttpRequestMetrics()
         app.state.pow_challenges: dict[str, Any] = {}

airlock/gateway/crl.py

@@ -0,0 +1,134 @@
+"""CRL (Certificate Revocation List) generator for the Airlock gateway.
+
+Builds a signed CRL from the current revocation state, caches it until
+the next update interval, and tracks a monotonically increasing crl_number.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+from airlock.crypto.signing import sign_message
+from airlock.schemas.crl import CRLEntry, SignedCRL
+
+if TYPE_CHECKING:
+    from nacl.signing import SigningKey
+
+    from airlock.gateway.revocation import RedisRevocationStore, RevocationStore
+
+logger = logging.getLogger(__name__)
+
+
+class CRLGenerator:
+    """Generates and caches signed CRLs from the current revocation state.
+
+    Parameters
+    ----------
+    revocation_store:
+        The revocation store to read current revoked/suspended DIDs from.
+    signing_key:
+        Ed25519 signing key used to sign the CRL.
+    issuer_did:
+        DID of the gateway that issues the CRL.
+    update_interval_seconds:
+        Seconds between CRL regenerations (controls ``next_update``).
+    max_cache_age_seconds:
+        Value published in the CRL's ``max_cache_age_seconds`` field.
+    """
+
+    def __init__(
+        self,
+        revocation_store: RevocationStore | RedisRevocationStore,
+        signing_key: SigningKey,
+        issuer_did: str,
+        update_interval_seconds: int = 60,
+        max_cache_age_seconds: int = 300,
+    ) -> None:
+        self._store = revocation_store
+        self._signing_key = signing_key
+        self._issuer_did = issuer_did
+        self._update_interval = update_interval_seconds
+        self._max_cache_age = max_cache_age_seconds
+        self._crl_number: int = 0
+        self._cached_crl: SignedCRL | None = None
+
+    @property
+    def crl_number(self) -> int:
+        """Current CRL sequence number."""
+        return self._crl_number
+
+    def _is_cache_fresh(self) -> bool:
+        """Return True if the cached CRL has not passed its next_update time."""
+        if self._cached_crl is None:
+            return False
+        now = datetime.now(UTC)
+        return now < self._cached_crl.next_update
+
+    async def generate(self) -> SignedCRL:
+        """Build a new SignedCRL from the current revocation state.
+
+        Increments crl_number, builds entries from all revoked and suspended
+        DIDs, signs the CRL, and updates the cache.
+        """
+        self._crl_number += 1
+        now = datetime.now(UTC)
+        next_update = now + timedelta(seconds=self._update_interval)
+
+        entries: list[CRLEntry] = []
+
+        # Add permanently revoked DIDs
+        revoked_reasons = self._store.get_revoked_with_reasons()
+        for did, reason in sorted(revoked_reasons.items()):
+            entries.append(
+                CRLEntry(
+                    did=did,
+                    status="revoked",
+                    reason=reason.value,
+                    revoked_at=now,
+                )
+            )
+
+        # Add suspended DIDs
+        suspended_dids = await self._store.list_suspended()
+        for did in suspended_dids:
+            entries.append(
+                CRLEntry(
+                    did=did,
+                    status="suspended",
+                    reason="investigation",
+                    revoked_at=now,
+                )
+            )
+
+        crl = SignedCRL(
+            version=1,
+            crl_number=self._crl_number,
+            issuer_did=self._issuer_did,
+            this_update=now,
+            next_update=next_update,
+            max_cache_age_seconds=self._max_cache_age,
+            entries=entries,
+            signature=None,
+        )
+
+        # Sign the CRL (signature field is excluded by canonicalize)
+        crl_dict = crl.model_dump(mode="json")
+        signature = sign_message(crl_dict, self._signing_key)
+        crl = crl.model_copy(update={"signature": signature})
+
+        self._cached_crl = crl
+        logger.info(
+            "CRL #%d generated: %d entries, next_update=%s",
+            self._crl_number,
+            len(entries),
+            next_update.isoformat(),
+        )
+        return crl
+
+    async def get_or_generate(self) -> SignedCRL:
+        """Return the cached CRL if fresh, otherwise regenerate."""
+        if self._is_cache_fresh():
+            return self._cached_crl  # type: ignore[return-value]
+        return await self.generate()

airlock/gateway/crl_freshness.py

@@ -0,0 +1,88 @@
+"""Tiered CRL freshness assessment for fail-open/fail-closed degradation.
+
+Determines how stale a CRL is and what operational mode the gateway should
+use when making trust decisions.
+
+Modes (in order of increasing severity):
+  NORMAL       -- CRL is fresh (age < update interval)
+  DEGRADED     -- CRL is stale but within max_cache_age (warn on attestations)
+  EMERGENCY    -- CRL is very stale (only allow high-trust agents)
+  FAIL_CLOSED  -- CRL is unacceptably stale (reject all verifications)
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from airlock.config import AirlockConfig
+    from airlock.schemas.crl import SignedCRL
+
+logger = logging.getLogger(__name__)
+
+
+class CRLFreshnessMode(StrEnum):
+    """Operational mode based on CRL staleness."""
+
+    NORMAL = "normal"
+    DEGRADED = "degraded"
+    EMERGENCY = "emergency"
+    FAIL_CLOSED = "fail_closed"
+
+
+def assess_crl_freshness(crl: SignedCRL, config: AirlockConfig) -> CRLFreshnessMode:
+    """Determine CRL freshness mode based on age thresholds.
+
+    Parameters
+    ----------
+    crl:
+        The CRL to assess.
+    config:
+        Gateway configuration containing threshold values.
+
+    Returns
+    -------
+    CRLFreshnessMode
+        The operational mode the gateway should use.
+
+    Thresholds
+    ----------
+    - NORMAL:      crl_age < crl_update_interval_seconds
+    - DEGRADED:    crl_age < crl_max_cache_age_seconds
+    - EMERGENCY:   crl_age < crl_emergency_cache_age_seconds
+    - FAIL_CLOSED: crl_age >= crl_emergency_cache_age_seconds
+    """
+    now = datetime.now(UTC)
+    crl_age_seconds = (now - crl.this_update).total_seconds()
+
+    if crl_age_seconds < config.crl_update_interval_seconds:
+        return CRLFreshnessMode.NORMAL
+
+    if crl_age_seconds < config.crl_max_cache_age_seconds:
+        logger.warning(
+            "CRL #%d is stale (age=%.0fs, threshold=%ds) — DEGRADED mode",
+            crl.crl_number,
+            crl_age_seconds,
+            config.crl_update_interval_seconds,
+        )
+        return CRLFreshnessMode.DEGRADED
+
+    if crl_age_seconds < config.crl_emergency_cache_age_seconds:
+        logger.warning(
+            "CRL #%d is very stale (age=%.0fs, threshold=%ds) — EMERGENCY mode",
+            crl.crl_number,
+            crl_age_seconds,
+            config.crl_max_cache_age_seconds,
+        )
+        return CRLFreshnessMode.EMERGENCY
+
+    logger.error(
+        "CRL #%d exceeds emergency threshold (age=%.0fs, limit=%ds) — FAIL_CLOSED",
+        crl.crl_number,
+        crl_age_seconds,
+        config.crl_emergency_cache_age_seconds,
+    )
+    return CRLFreshnessMode.FAIL_CLOSED