skcomms 0.2.1__tar.gz → 0.2.3__tar.gz

{skcomms-0.2.1 → skcomms-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skcomms
-Version: 0.2.1
+Version: 0.2.3
 Summary: Sovereign communications for AI agents — multi-channel transport + FQID realm addressing
 Author-email: smilinTux <chefboyrdave2.1@gmail.com>
 License: GPL-3.0-or-later

{skcomms-0.2.1 → skcomms-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skcomms"
-version = "0.2.1"
+version = "0.2.3"
 description = "Sovereign communications for AI agents — multi-channel transport + FQID realm addressing"
 readme = "README.md"
 license = {text = "GPL-3.0-or-later"}

{skcomms-0.2.1 → skcomms-0.2.3}/src/skcomms/__init__.py

@@ -15,7 +15,7 @@ FQID / realm layer (pre-alpha stubs, implementations landing in coord tasks):
     from skcomms.cluster import ...
 """
 
-__version__ = "0.1.7"
+__version__ = "0.2.3"
 
 from .core import SKComms, SKComm
 from .crypto import EnvelopeCrypto, KeyStore

{skcomms-0.2.1 → skcomms-0.2.3}/src/skcomms/access/server.py

@@ -27,9 +27,11 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 import socket
 from dataclasses import dataclass
-from typing import Any, Optional
+from pathlib import Path
+from typing import Any, Optional, Union
 
 from .. import federation as fed
 from ..discovery import PeerStore
@@ -42,6 +44,49 @@ from .registry import AccessRegistry, DEFAULT_REGISTRY, RegisteredTool, Scope
 logger = logging.getLogger("skcomms.access.server")
 
 
+def _access_nonce_db_path() -> Path:
+    """Resolve the sk-access durable replay-cache path (NODE-LOCAL, never synced).
+
+    Precedence: ``SKCOMMS_ACCESS_NONCE_DB`` (explicit file path) wins, then
+    the ``SKCOMMS_NONCE_CACHE_DIR`` directory override, then the XDG state
+    default (``$XDG_STATE_HOME/skcomms/`` or ``~/.local/state/skcomms/``):
+    see :func:`skcomms.home.resolve_nonce_db`. It is a SEPARATE file from
+    the federation inbox cache (``nonce_cache.db``) so the two surfaces keep
+    independent replay history.
+
+    The store used to live at ``skcomms_home()/state/access_nonce_cache.db``,
+    inside the Syncthing-shared tree; a replay cache must never sync between
+    nodes, so it now defaults outside any synced dir. A healthy legacy DB is
+    migrated once; otherwise a fresh cache starts (safe: replay exposure is
+    bounded by the envelope freshness window).
+    """
+    override = (os.environ.get("SKCOMMS_ACCESS_NONCE_DB") or "").strip()
+    if override:
+        return Path(override).expanduser()
+    from ..home import resolve_nonce_db
+
+    return resolve_nonce_db("access_nonce_cache.db")
+
+
+def _default_nonce_cache() -> Union["fed.NonceCache", "fed.DurableNonceCache"]:
+    """Build the sk-access replay guard: durable by default (coord f465b407).
+
+    Mirrors :func:`skcomms.api._get_nonce_cache` semantics for the sk-access
+    surface: a SQLite-backed :class:`~skcomms.federation.DurableNonceCache`
+    so a daemon restart does not reopen a replay window on signed tool calls.
+    ``SKCOMMS_NONCE_CACHE=memory`` opts back into the legacy in-memory cache
+    (explicit, single-process/ephemeral use only).
+
+    Fail-closed: if the durable store cannot be opened this raises, so the
+    server refuses to start rather than silently accepting replays with no
+    persistence (systemd Restart=always keeps retrying).
+    """
+    mode = (os.environ.get("SKCOMMS_NONCE_CACHE") or "").strip().lower()
+    if mode == "memory":
+        return fed.NonceCache()
+    return fed.DurableNonceCache(_access_nonce_db_path())
+
+
 # ---------------------------------------------------------------------------
 # Errors
 # ---------------------------------------------------------------------------
@@ -104,6 +149,9 @@ class AccessServer:
         verifier: An :class:`~skcomms.signing.EnvelopeVerifier`. If omitted, one
             is created and seeded TOFU-style from the :class:`PeerStore`.
         peer_store: Peer store for TOFU key resolution (default: a fresh one).
+        nonce_cache: Replay guard override (tests / embedding). Default is the
+            durable per-node store from :func:`_default_nonce_cache`, so a
+            daemon restart does not reopen a replay window (coord f465b407).
     """
 
     def __init__(
@@ -113,15 +161,18 @@ class AccessServer:
         verifier: Optional[EnvelopeVerifier] = None,
         peer_store: Optional[PeerStore] = None,
         audit: Optional[AccessAuditLog] = None,
+        nonce_cache: Optional[
+            Union[fed.NonceCache, fed.DurableNonceCache]
+        ] = None,
     ) -> None:
         self.config = config or AccessConfig.load()
         self.registry = registry or DEFAULT_REGISTRY
         self._peer_store = peer_store if peer_store is not None else PeerStore()
         self.verifier = verifier or self._build_verifier()
-        # KNOWN GAP (follow-up coord f465b407): in-memory cache means a
-        # daemon restart reopens a replay window on the sk-access surface.
-        # Migrate to the durable per-node store (see api._get_nonce_cache).
-        self.nonce_cache = fed.NonceCache()
+        # Durable by default; fail-closed if the store cannot be opened.
+        self.nonce_cache = (
+            nonce_cache if nonce_cache is not None else _default_nonce_cache()
+        )
         self.audit = audit or AccessAuditLog(node=self.config.node_name)
         self._register_builtins()
 

{skcomms-0.2.1 → skcomms-0.2.3}/src/skcomms/api.py

@@ -27,9 +27,9 @@ from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel, Field
 from starlette.middleware.base import BaseHTTPMiddleware
 
+from . import skfed_directory
 from .capauth_validator import CapAuthValidator
 from .core import SKComms
-from . import skfed_directory
 from .discovery import PeerInfo, PeerStore
 from .heartbeat import HeartbeatConfig, HeartbeatPublisher
 from .models import (
@@ -224,6 +224,20 @@ async def lifespan(app: FastAPI):
         logger.exception("Failed to start depth-monitor loop")
         _depth_monitor_task = None
 
+    # Geo self-seed: opt-in (SKCOMMS_GEO_SEED_FLEET) upsert of the sovereign
+    # fleet nodes into the process-global geo store so the skmap pane
+    # (GET /api/v1/geo/units) shows units before a live CoT device connects.
+    # Fed through the real upsert_from_cot path; clearly labeled fleet:<node>
+    # seeds; superseded by real CoT once a feed is wired. See geo_seed.py.
+    try:
+        from .geo_seed import seed_fleet_if_enabled
+
+        seeded = seed_fleet_if_enabled()
+        if seeded:
+            logger.info("Geo store seeded with %d fleet unit(s): %s", len(seeded), seeded)
+    except Exception:
+        logger.exception("Failed to seed geo store")
+
     yield
 
     logger.info("Shutting down SKComms API server...")
@@ -642,6 +656,22 @@ async def health():
     return body
 
 
+@app.get("/.well-known/skworld-module.json", tags=["health"])
+async def skworld_module_manifest(request: Request):
+    """skcomms' SKWorld module manifest (public discovery metadata, no bearer).
+
+    skcomms is a UI-less backend transport service, so this manifest declares no
+    UI module: only the operator facet plus a service marker. The shell reads it
+    to discover skcomms and learn its health + operator contract before it has a
+    token. URLs are origin-relative to the request, so health resolves against
+    wherever the api actually answers. Served unauthenticated, like skchat's and
+    skcode's manifests.
+    """
+    from .skworld_manifest import skcomms_module_manifest
+
+    return skcomms_module_manifest(str(request.base_url))
+
+
 # ---------------------------------------------------------------------------
 # MCP tool relay — used by the consciousness-swipe browser extension.
 #
@@ -761,6 +791,58 @@ async def get_capabilities():
     return build_capabilities(get_skcomms())
 
 
+@app.get("/api/v1/geo/units", tags=["geo"])
+async def get_geo_units(include_stale: bool = False, format: str = "units"):
+    """Current situational picture: live unit / marker / waypoint positions.
+
+    The backend half of the Flutter ``skmap`` pane. Source of truth is the live
+    CoT store in the separate ``skcot`` service process, exposed read-only over
+    HTTP (``skcot.geo_http``, default ``http://127.0.0.1:8091/geo/units``, env
+    ``SKCOT_GEO_URL``). When that bridge is reachable AND has units, its REAL
+    telemetry is returned. Otherwise this falls back to the process-global local
+    store (see :mod:`skcomms.geo_store`, the opt-in fleet seed). Both paths are
+    fail-soft: an empty or unreachable bridge yields the correct shape, never a
+    500.
+
+    Args:
+        include_stale: Include fixes past their CoT stale time / TTL. Default
+            ``False`` (only fresh positions, what a live map wants).
+        format: ``"units"`` (default) → ``{"units": [...], "count": N}`` where
+            each item is a flat GeoUnit dict (``uid``, ``callsign``, ``lat``,
+            ``lon``, ``cot_type``, ``last_seen``, ...); ``"geojson"`` → a
+            GeoJSON ``FeatureCollection``. Both are accepted by the app's
+            ``GeoUnit.fromJson`` (which reads ``features`` then ``units``).
+
+    Returns:
+        A dict the ``skmap`` client renders directly.
+    """
+    from .geo_store import fetch_skcot_geo, geo_payload_has_units, get_geo_store
+
+    fmt = "geojson" if format == "geojson" else "units"
+
+    # Prefer the live skcot store (real CoT). Blocking fetch off the event loop.
+    remote = await asyncio.to_thread(
+        fetch_skcot_geo, include_stale=include_stale, fmt=fmt
+    )
+    if remote is not None and geo_payload_has_units(remote):
+        return remote
+
+    # Fall back to the local in-process store (fleet seed) when skcot is
+    # unreachable OR reports zero units. Fail-soft: the local store wraps the
+    # shared skcot GeoStore, so if the skcot package is somehow absent this
+    # still yields the correct empty shape rather than a 500.
+    try:
+        store = get_geo_store()
+        if fmt == "geojson":
+            return store.to_feature_collection(include_stale=include_stale)
+        units = store.units_json(include_stale=include_stale)
+        return {"units": units, "count": len(units)}
+    except Exception:  # noqa: BLE001 - the map endpoint must never 500
+        if fmt == "geojson":
+            return {"type": "FeatureCollection", "features": []}
+        return {"units": [], "count": 0}
+
+
 class AccessTokenRequest(BaseModel):
     """Request to mint a capauth token for a single sk-access tool call.
 
@@ -986,30 +1068,31 @@ _MAX_INBOX_BYTES = 256 * 1024
 
 
 def _nonce_db_path() -> Path:
-    """Resolve the durable nonce-cache SQLite path.
-
-    ``SKCOMMS_NONCE_DB`` (explicit file path) wins; otherwise the store lives
-    at ``skcomms_home()/state/nonce_cache.db``. The ``state/`` subtree is
-    per-node (Syncthing-ignored via .stignore): the replay cache must never
-    be shared between nodes through file sync (see SOP.md).
-
-    Because the default path sits inside the Syncthing-shared skcomms home,
-    this also heals a pre-existing ``.stignore`` that lacks the ``state/``
-    line (live fleets scaffolded before the durable cache existed). Without
-    that, a live WAL SQLite would sync between nodes: corruption risk plus
-    mixed per-node replay history. A failure to write ``.stignore`` raises,
-    and :func:`_get_nonce_cache` then fails closed.
+    """Resolve the durable nonce-cache SQLite path (NODE-LOCAL, never synced).
+
+    Precedence: ``SKCOMMS_NONCE_DB`` (explicit file path) wins, then the
+    ``SKCOMMS_NONCE_CACHE_DIR`` directory override, then the XDG state
+    default (``$XDG_STATE_HOME/skcomms/`` or ``~/.local/state/skcomms/``):
+    see :func:`skcomms.home.resolve_nonce_db`.
+
+    The store used to live at ``skcomms_home()/state/nonce_cache.db``; on
+    live fleets that home is inside a Syncthing-shared tree, and when the
+    Syncthing folder is rooted ABOVE the home the home's own ``.stignore``
+    ``state/`` line has no effect, so two nodes synced one live WAL SQLite
+    (conflict copies observed on .158/.41). A replay guard is strictly
+    per-node state and now defaults outside any synced tree. A healthy
+    legacy DB is migrated once; otherwise a fresh cache starts, which is
+    safe because the replay window is bounded by the envelope freshness
+    check (see SOP.md).
     """
     import os as _os
 
     override = (_os.environ.get("SKCOMMS_NONCE_DB") or "").strip()
     if override:
         return Path(override).expanduser()
-    from .home import ensure_state_ignored, skcomms_home
+    from .home import resolve_nonce_db
 
-    home = skcomms_home()
-    ensure_state_ignored(home)
-    return home / "state" / "nonce_cache.db"
+    return resolve_nonce_db("nonce_cache.db")
 
 
 def _get_nonce_cache():
@@ -1351,6 +1434,80 @@ async def post_inbox(request: Request):
     return {"ok": True, "id": env.id}
 
 
+# ---------------------------------------------------------------------------
+# Public P2P pairing over Tailscale Funnel (card 2ab5aa6c): PUBLIC, opt-in
+# ---------------------------------------------------------------------------
+#
+# Off-tailnet peers cannot reach the tailnet-only mesh, so this route lets a
+# peer POST their peer bundle to the node's Funnel-exposed pairing endpoint and
+# bootstrap a P2P pairing. It is the inbound half of ``skcomms.public_pairing``:
+# the request is routed straight into the EXISTING key exchange
+# (``import_peer_bundle``), which does all the crypto (armor validation +
+# fingerprint derivation). The public Funnel is only the bootstrap channel.
+#
+# Disabled by default: with no ``SKCOMMS_FUNNEL_URL`` configured the route 404s,
+# exactly as if it did not exist. When a ``SKCOMMS_FUNNEL_PAIR_TOKEN`` is set,
+# an inbound request must present a matching token or it is rejected 401.
+
+_MAX_PAIR_BYTES = 256 * 1024
+
+
+@app.post("/api/v1/pair/public", tags=["pairing"])
+async def post_public_pairing(request: Request):
+    """Accept an off-tailnet peer's public pairing request over the Funnel.
+
+    Reads a ``{"bundle": {...}, "token": "..."}`` body, routes it into the
+    existing key exchange, and returns this node's own bundle for mutual
+    bootstrap. 404 when public pairing is not configured (feature off).
+
+    Raises:
+        HTTPException: 404 (feature off), 401 (bad/missing token), 422
+            (missing/malformed bundle), 413 (too large).
+    """
+    from .key_exchange import KeyExchangeError
+    from .public_pairing import (
+        PublicPairingError,
+        PublicPairingRequest,
+        configured_token,
+        funnel_enabled,
+        handle_public_pairing_request,
+    )
+
+    # Disabled by default: no Funnel base configured -> the route does not exist.
+    if not funnel_enabled():
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="not found")
+
+    raw = await request.body()
+    if len(raw) > _MAX_PAIR_BYTES:
+        raise HTTPException(
+            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            detail=f"pairing request exceeds {_MAX_PAIR_BYTES} bytes",
+        )
+
+    import json as _json
+
+    try:
+        body = _json.loads(raw or b"{}")
+        req = PublicPairingRequest(**body)
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"unparseable pairing request: {exc}",
+        ) from exc
+
+    try:
+        result = handle_public_pairing_request(req, expected_token=configured_token())
+    except PublicPairingError as exc:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=str(exc)) from exc
+    except KeyExchangeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)
+        ) from exc
+
+    logger.info("public pairing accepted from %s", (result.get("paired") or {}).get("fqid"))
+    return {"ok": True, **result}
+
+
 # ---------------------------------------------------------------------------
 # Operator consent surface (skfed-consent-design gate 5) — LOCAL ONLY
 # ---------------------------------------------------------------------------
@@ -2515,25 +2672,50 @@ async def get_webrtc_peers(room: Optional[str] = None):
 # Consciousness / Soul Snapshot endpoints
 # ---------------------------------------------------------------------------
 
-try:
-    from skcapstone.snapshots import (
-        ConversationMessage as _ConversationMessage,
-    )
-    from skcapstone.snapshots import (
-        OOFState as _OOFState,
-    )
-    from skcapstone.snapshots import (
-        PersonalityTraits as _PersonalityTraits,
-    )
-    from skcapstone.snapshots import (
-        SnapshotIndex,
-        SnapshotStore,
-        SoulSnapshot,
-    )
+# skcapstone.snapshots is an OPTIONAL higher-layer subapp surface.  skcomms is
+# the L0 core and must import without it, so the import is resolved LAZILY on
+# first use (see ``_load_snapshots``) rather than at module load.  These names
+# stay ``None`` until then; ``from __future__ import annotations`` (top of file)
+# keeps the string annotations below valid while they are unbound.
+SnapshotStore = None  # type: ignore[assignment]
+SnapshotIndex = None  # type: ignore[assignment]
+SoulSnapshot = None  # type: ignore[assignment]
+_OOFState = None  # type: ignore[assignment]
+_PersonalityTraits = None  # type: ignore[assignment]
+_ConversationMessage = None  # type: ignore[assignment]
+
+#: Tri-state: ``None`` = not yet probed, ``True``/``False`` = resolved.
+_SNAPSHOTS_AVAILABLE: Optional[bool] = None
+
+
+def _load_snapshots() -> bool:
+    """Resolve ``skcapstone.snapshots`` lazily on first use, caching the result.
+
+    The consciousness/snapshot endpoints legitimately bridge to skcapstone, but
+    deferring the import to first use means merely importing ``skcomms.api``
+    never pulls skcapstone into ``sys.modules``.  Returns whether the snapshot
+    types are available; callers 501 when they are not.
+    """
+    global _SNAPSHOTS_AVAILABLE
+    global SnapshotStore, SnapshotIndex, SoulSnapshot
+    global _OOFState, _PersonalityTraits, _ConversationMessage
+    if _SNAPSHOTS_AVAILABLE is None:
+        try:
+            # ``global`` above routes each of these bindings to the module name.
+            from skcapstone.snapshots import ConversationMessage as _ConversationMessage
+            from skcapstone.snapshots import OOFState as _OOFState
+            from skcapstone.snapshots import PersonalityTraits as _PersonalityTraits
+            from skcapstone.snapshots import (
+                SnapshotIndex,
+                SnapshotStore,
+                SoulSnapshot,
+            )
+
+            _SNAPSHOTS_AVAILABLE = True
+        except Exception:  # ImportError, or a broken partial install
+            _SNAPSHOTS_AVAILABLE = False
+    return _SNAPSHOTS_AVAILABLE
 
-    _SNAPSHOTS_AVAILABLE = True
-except ImportError:
-    _SNAPSHOTS_AVAILABLE = False
 
 _snapshot_store: Optional[SnapshotStore] = None
 
@@ -2548,7 +2730,7 @@ def _get_store() -> "SnapshotStore":
         HTTPException: If skcapstone is not installed.
     """
     global _snapshot_store
-    if not _SNAPSHOTS_AVAILABLE:
+    if not _load_snapshots():
         raise HTTPException(
             status_code=status.HTTP_501_NOT_IMPLEMENTED,
             detail="skcapstone package not installed — cannot manage snapshots",

{skcomms-0.2.1 → skcomms-0.2.3}/src/skcomms/capabilities.py

@@ -128,6 +128,7 @@ _TRANSPORT_PROBES: dict[str, int] = {
 _MODULE_HINTS: list[str] = [
     "chats",
     "spaces",
+    "skcode",
     "activity",
     "profile",
     "skmap",

{skcomms-0.2.1 → skcomms-0.2.3}/src/skcomms/capauth_validator.py

@@ -15,8 +15,8 @@ The detached PGP signature covers the UTF-8 string::
 A ±300-second window is accepted to tolerate clock skew while preventing
 replay attacks. The signer's public key is resolved from:
 
-1. ``~/.skcapstone/skcomms/keys/<FINGERPRINT>.asc`` — SKComms per-agent keystore
-2. ``gpg --export --armor <FINGERPRINT>`` — system GPG keyring
+1. ``~/.skcapstone/skcomms/keys/<FINGERPRINT>.asc`` - SKComms per-agent keystore
+2. ``gpg --export --armor <FINGERPRINT>`` - system GPG keyring
 
 **Remote validation** is available by setting ``capauth_url`` to a
 CapAuth API base URL. Remote is tried first; on unreachable server the
@@ -77,7 +77,7 @@ def _find_pubkey_by_fingerprint(
         for path in glob.glob(pattern, recursive=True):
             try:
                 key, _ = pgpy.PGPKey.from_file(path)
-            except Exception:  # noqa: BLE001 — skip unreadable/non-key files
+            except Exception:  # noqa: BLE001 - skip unreadable/non-key files
                 continue
             if str(key.fingerprint).replace(" ", "").upper() == want:
                 return str(key)
@@ -88,6 +88,78 @@ logger = logging.getLogger("skcomms.capauth_validator")
 # PGP fingerprint: 40 hex characters
 _FINGERPRINT_RE = re.compile(r"^[0-9A-Fa-f]{40}$")
 
+
+def _reject_reason_if_key_unusable(pub_key, signer_keyids) -> Optional[str]:
+    """Return a reason string if the signing key is revoked or expired, else None.
+
+    SECURITY: pgpy's own ``PGPKey.verify()`` performs NEITHER revocation NOR
+    expiry checks (its source literally warns "Revocation checks are not yet
+    implemented"), so a signature made by a revoked or expired key verifies as
+    valid. That let a revoked/expired CapAuth signing key keep authenticating on
+    the WebRTC signaling / SDP auth path (card 6abe9bef).
+
+    This routes the usability decision through capauth's single source of truth,
+    ``capauth.crypto.pgpy_backend._assert_key_usable`` (the same helper the
+    capauth backend uses, card a93b0528). When that helper cannot be imported we
+    fall back to an inline check that mirrors it, so skcomms stays fail-closed
+    and never authenticates a revoked/expired signing key even if capauth's
+    internal layout changes.
+
+    Args:
+        pub_key: Parsed pgpy public key (primary, with subkeys).
+        signer_keyids: Set of 16-hex key IDs that produced the signature being
+            verified. Scopes subkey checks to the actual signer.
+
+    Returns:
+        A human-readable reason string when the key must be rejected, or None
+        when the key is usable.
+    """
+    try:
+        from capauth.crypto.pgpy_backend import _assert_key_usable
+        from capauth.exceptions import KeyExpiredError, KeyRevokedError
+    except Exception:  # noqa: BLE001 - capauth helper unavailable, use fallback
+        _assert_key_usable = None
+
+    if _assert_key_usable is not None:
+        try:
+            _assert_key_usable(pub_key, signer_keyids)
+            return None
+        except (KeyRevokedError, KeyExpiredError) as exc:
+            return str(exc)
+        except Exception as exc:  # noqa: BLE001 - unexpected: fail closed
+            return f"key usability check errored: {exc}"
+
+    # Inline fallback mirroring capauth.crypto.pgpy_backend._assert_key_usable.
+    try:
+        fingerprint = str(pub_key.fingerprint).replace(" ", "")
+        for _rev in pub_key.revocation_signatures:
+            return f"key {fingerprint} carries a revocation signature"
+        if pub_key.is_expired:
+            return f"key {fingerprint} is expired"
+        for keyid, subkey in pub_key.subkeys.items():
+            if signer_keyids and keyid not in signer_keyids:
+                continue
+            for _rev in subkey.revocation_signatures:
+                return f"signing subkey {keyid} of key {fingerprint} carries a revocation signature"
+            if signer_keyids and keyid in signer_keyids and subkey.is_expired:
+                return f"signing subkey {keyid} of key {fingerprint} is expired"
+    except Exception as exc:  # noqa: BLE001 - cannot determine usability: fail closed
+        return f"could not verify key usability: {exc}"
+    return None
+
+
+def _signer_keyids(sig) -> set:
+    """Best-effort set of 16-hex signer key IDs from a pgpy signature object.
+
+    Returns an empty set when the signer cannot be read; an empty set makes the
+    revocation/expiry check apply to the primary key and every subkey (the
+    broadest, safest scope).
+    """
+    try:
+        return {sig.signer}
+    except Exception:  # noqa: BLE001
+        return set()
+
 # Replay-prevention window: tokens older than this (or future-dated beyond
 # this) are rejected.
 _TOKEN_WINDOW_SECS = 300  # ±5 minutes
@@ -152,7 +224,7 @@ class CapAuthValidator:
         """
         if not token:
             if self._require_auth:
-                logger.warning("WebRTC signaling: no auth token — rejecting connection")
+                logger.warning("WebRTC signaling: no auth token - rejecting connection")
                 return None
             return "anonymous"
 
@@ -233,13 +305,13 @@ class CapAuthValidator:
         # Require exactly 3 parts for signed tokens.                          #
         # ------------------------------------------------------------------ #
         # SECURITY (fail-closed): a token that *looks* signed (>1 part) but is
-        # missing its signature CANNOT be verified. Deny it in every mode —
-        # even permissive — so a peer can never be upgraded to a claimed
+        # missing its signature CANNOT be verified. Deny it in every mode -
+        # even permissive - so a peer can never be upgraded to a claimed
         # identity it did not prove. The only permissive convenience is the
         # explicit single-part dev token handled above.
         if len(parts) != 3:
             logger.warning(
-                "CapAuth local: expected fingerprint.timestamp.sig, got %d parts — rejecting",
+                "CapAuth local: expected fingerprint.timestamp.sig, got %d parts - rejecting",
                 len(parts),
             )
             return None
@@ -279,14 +351,24 @@ class CapAuthValidator:
             pub_key = self._load_public_key(fingerprint)
             if pub_key is None:
                 # SECURITY (fail-closed): without the signer's public key we
-                # cannot verify the signature. Deny in every mode — never trust
+                # cannot verify the signature. Deny in every mode - never trust
                 # the self-asserted fingerprint just because we lack its key.
                 logger.warning(
-                    "CapAuth local: public key not found for %s — rejecting (cannot verify)",
+                    "CapAuth local: public key not found for %s - rejecting (cannot verify)",
                     fingerprint,
                 )
                 return None
 
+            # SECURITY (fail-closed): reject revoked/expired signing keys before
+            # trusting the signature. pgpy.verify() ignores revocation/expiry, so
+            # route this decision through capauth's usability check (card 6abe9bef).
+            reason = _reject_reason_if_key_unusable(pub_key, _signer_keyids(sig))
+            if reason:
+                logger.warning(
+                    "CapAuth local: signing key rejected for %s: %s", fingerprint, reason
+                )
+                return None
+
             # The message that was signed: "capauth:<FINGERPRINT>:<TIMESTAMP>"
             signed_text = f"capauth:{fingerprint}:{timestamp_str}"
             result = pub_key.verify(signed_text, sig)
@@ -299,7 +381,7 @@ class CapAuthValidator:
 
         except ImportError:
             logger.warning(
-                "pgpy not installed — cannot verify CapAuth signature; rejecting. "
+                "pgpy not installed - cannot verify CapAuth signature; rejecting. "
                 "Install skcomms[crypto] for full CapAuth PGP verification."
             )
             # SECURITY (fail-closed): without pgpy we cannot verify the
@@ -312,7 +394,7 @@ class CapAuthValidator:
             # SECURITY (fail-closed): any error mid-verification is a denial,
             # never a fall-through to the claimed identity.
             logger.error(
-                "CapAuth local: PGP verification error for %s: %s — rejecting",
+                "CapAuth local: PGP verification error for %s: %s - rejecting",
                 fingerprint,
                 exc,
             )
@@ -323,8 +405,8 @@ class CapAuthValidator:
 
         Search order:
 
-        1. ``~/.skcapstone/skcomms/keys/<FINGERPRINT>.asc`` — SKComms per-agent keystore
-        2. ``gpg --export --armor <FINGERPRINT>`` — system GPG keyring
+        1. ``~/.skcapstone/skcomms/keys/<FINGERPRINT>.asc`` - SKComms per-agent keystore
+        2. ``gpg --export --armor <FINGERPRINT>`` - system GPG keyring
 
         Args:
             fingerprint: 40-char uppercase hex PGP fingerprint.
@@ -349,7 +431,7 @@ class CapAuthValidator:
         # 2. Per-agent CapAuth identity dirs + skcomms peers store, matched by
         #    fingerprint. Reconciles the WebRTC verify path with the mailbox/TOFU
         #    layer (2026-06-11) so a *local* agent's signed SDP (e.g. opus↔lumina)
-        #    verifies — those keys live under capauth/identity, not ~/.skcapstone/skcomms/keys.
+        #    verifies - those keys live under capauth/identity, not ~/.skcapstone/skcomms/keys.
         armor = _find_pubkey_by_fingerprint(fingerprint)
         if armor:
             try:
@@ -434,6 +516,16 @@ class CapAuthValidator:
                 logger.warning("verify_detached: public key not found for %s", fingerprint)
                 return False
 
+            # SECURITY (fail-closed): reject revoked/expired signing keys before
+            # trusting the signature. pgpy.verify() ignores revocation/expiry, so
+            # route this decision through capauth's usability check (card 6abe9bef).
+            reason = _reject_reason_if_key_unusable(pub_key, _signer_keyids(pgp_sig))
+            if reason:
+                logger.warning(
+                    "verify_detached: signing key rejected for %s: %s", fingerprint, reason
+                )
+                return False
+
             result = pub_key.verify(signed_payload, pgp_sig)
             if not bool(result):
                 logger.warning("verify_detached: PGP signature INVALID for %s", fingerprint)
@@ -444,7 +536,7 @@ class CapAuthValidator:
 
         except ImportError:
             logger.warning(
-                "pgpy not installed — cannot verify SDP signature. "
+                "pgpy not installed - cannot verify SDP signature. "
                 "Install skcomms[crypto] for full CapAuth PGP verification."
             )
             return False