local IdP

Author: rcholic

README.md

@@ -150,6 +150,53 @@ predicate-authority revoke intent --host 127.0.0.1 --port 8787 --hash <intent_ha
 predicate-authorityd --host 127.0.0.1 --port 8787 --mode local_only --policy-file examples/authorityd/policy.json
 ```
 
+### Identity mode options (`predicate-authorityd`)
+
+- `--identity-mode local`: deterministic local bridge (default).
+- `--identity-mode local-idp`: local IdP-style signed token mode for dev/air-gapped workflows.
+- `--identity-mode oidc`: enterprise OIDC bridge mode.
+- `--identity-mode entra`: Microsoft Entra bridge mode.
+
+Example (`local-idp`):
+
+```bash
+export LOCAL_IDP_SIGNING_KEY="replace-with-strong-secret"
+predicate-authorityd \
+  --host 127.0.0.1 \
+  --port 8787 \
+  --mode local_only \
+  --policy-file examples/authorityd/policy.json \
+  --identity-mode local-idp \
+  --local-idp-issuer "http://localhost/predicate-local-idp" \
+  --local-idp-audience "api://predicate-authority"
+```
+
+### How to run with control-plane shipping (out-of-the-box)
+
+```bash
+export CONTROL_PLANE_URL="http://127.0.0.1:8080"
+export CONTROL_PLANE_TENANT_ID="dev-tenant"
+export CONTROL_PLANE_PROJECT_ID="dev-project"
+export CONTROL_PLANE_AUTH_TOKEN="<bearer-token>"
+
+PYTHONPATH=. predicate-authorityd \
+  --host 127.0.0.1 \
+  --port 8787 \
+  --mode local_only \
+  --policy-file examples/authorityd/policy.json \
+  --control-plane-enabled \
+  --control-plane-fail-open
+```
+
+The `/status` endpoint now includes:
+
+- `control_plane_emitter_attached`
+- `control_plane_audit_push_success_count`
+- `control_plane_audit_push_failure_count`
+- `control_plane_usage_push_success_count`
+- `control_plane_usage_push_failure_count`
+- `control_plane_last_push_error`
+
 ## Security: Local Kill-Switch Path
 
 `predicate-authority` supports fail-closed checks, local proof emission, and sidecar-managed revocation/token lifecycle for long-running agents.

docs/authorityd-operations.md

@@ -0,0 +1,128 @@
+# `predicate-authorityd` Operations Guide
+
+This guide shows how to run the local sidecar daemon, provide a policy file, and verify health/status endpoints.
+
+## 1) Sample `policy.json`
+
+Create `examples/authorityd/policy.json`:
+
+```json
+{
+  "rules": [
+    {
+      "name": "allow-orders-http-post",
+      "effect": "allow",
+      "principals": ["agent:orders-*"],
+      "actions": ["http.post"],
+      "resources": ["https://api.vendor.com/orders"],
+      "required_labels": []
+    },
+    {
+      "name": "deny-admin-delete",
+      "effect": "deny",
+      "principals": ["agent:*"],
+      "actions": ["http.delete"],
+      "resources": ["https://api.vendor.com/admin/*"],
+      "required_labels": []
+    }
+  ]
+}
+```
+
+## 2) Start the daemon
+
+Run from repo root:
+
+```bash
+PYTHONPATH=. predicate-authorityd \
+  --host 127.0.0.1 \
+  --port 8787 \
+  --mode local_only \
+  --policy-file examples/authorityd/policy.json \
+  --policy-poll-interval-s 2.0 \
+  --credential-store-file ./.predicate-authorityd/credentials.json
+```
+
+### Optional: enable control-plane shipping
+
+To automatically ship proof events and usage records to
+`predicate-authority-control-plane`, set:
+
+```bash
+export CONTROL_PLANE_URL="http://127.0.0.1:8080"
+export CONTROL_PLANE_TENANT_ID="dev-tenant"
+export CONTROL_PLANE_PROJECT_ID="dev-project"
+export CONTROL_PLANE_AUTH_TOKEN="<bearer-token>"
+
+PYTHONPATH=. predicate-authorityd \
+  --host 127.0.0.1 \
+  --port 8787 \
+  --mode local_only \
+  --policy-file examples/authorityd/policy.json \
+  --control-plane-enabled \
+  --control-plane-fail-open
+```
+
+When enabled, daemon bootstrap auto-attaches `ControlPlaneTraceEmitter` so each
+authority decision pushes:
+
+- audit events -> `/v1/audit/events:batch`
+- usage credits -> `/v1/metering/usage:batch`
+
+Expected startup output:
+
+```text
+predicate-authorityd listening on http://127.0.0.1:8787 (mode=local_only)
+```
+
+## 3) Endpoint checks
+
+### Health
+
+```bash
+curl -s http://127.0.0.1:8787/health | jq
+```
+
+Example response:
+
+```json
+{
+  "status": "ok",
+  "mode": "local_only",
+  "uptime_s": 12
+}
+```
+
+### Status
+
+```bash
+curl -s http://127.0.0.1:8787/status | jq
+```
+
+Example response:
+
+```json
+{
+  "mode": "local_only",
+  "policy_hot_reload_enabled": true,
+  "revoked_principal_count": 0,
+  "revoked_intent_count": 0,
+  "revoked_mandate_count": 0,
+  "proof_event_count": 0,
+  "daemon_running": true,
+  "policy_reload_count": 1,
+  "policy_poll_error_count": 0,
+  "last_policy_reload_epoch_s": 1700000000.0,
+  "last_policy_poll_error": null
+}
+```
+
+## 4) Verify policy hot-reload
+
+1. Update `examples/authorityd/policy.json`.
+2. Wait for at most `--policy-poll-interval-s`.
+3. Check `/status` and confirm `policy_reload_count` increases.
+
+## 5) Stop daemon
+
+Press `Ctrl+C` in the daemon terminal.

predicate_authority/README.md

@@ -8,4 +8,5 @@ Core pieces:
 - `ActionGuard` for pre-action `authorize` / `enforce`,
 - `LocalMandateSigner` for signed short-lived mandates,
 - `InMemoryProofLedger` and optional `OpenTelemetryTraceEmitter`,
-- typed integration adapters (including `sdk-python` mapping helpers).
+- typed integration adapters (including `sdk-python` mapping helpers),
+- control-plane client primitives for shipping proof and usage batches to hosted APIs.

predicate_authority/__init__.py

@@ -3,10 +3,19 @@
     EntraIdentityBridge,
     IdentityBridge,
     IdentityProviderType,
+    LocalIdPBridge,
+    LocalIdPBridgeConfig,
     OIDCBridgeConfig,
     OIDCIdentityBridge,
     TokenExchangeResult,
 )
+from predicate_authority.control_plane import (
+    AuditEventEnvelope,
+    ControlPlaneClient,
+    ControlPlaneClientConfig,
+    ControlPlaneTraceEmitter,
+    UsageCreditRecord,
+)
 from predicate_authority.daemon import DaemonConfig, PredicateAuthorityDaemon
 from predicate_authority.errors import AuthorizationDeniedError
 from predicate_authority.guard import ActionExecutionResult, ActionGuard
@@ -30,13 +39,19 @@
     "ActionGuard",
     "AuthorityMode",
     "AuthorizationDeniedError",
+    "AuditEventEnvelope",
+    "ControlPlaneClient",
+    "ControlPlaneClientConfig",
+    "ControlPlaneTraceEmitter",
     "CredentialRecord",
     "DaemonConfig",
     "EntraBridgeConfig",
     "EntraIdentityBridge",
     "IdentityBridge",
     "IdentityProviderType",
     "InMemoryProofLedger",
+    "LocalIdPBridge",
+    "LocalIdPBridgeConfig",
     "LocalCredentialStore",
     "LocalMandateSigner",
     "LocalRevocationCache",
@@ -53,4 +68,5 @@
     "SidecarError",
     "SidecarStatus",
     "TokenExchangeResult",
+    "UsageCreditRecord",
 ]

predicate_authority/bridge.py

@@ -1,7 +1,11 @@
 from __future__ import annotations
 
+import base64
 import hashlib
+import hmac
+import json
 import time
+from collections.abc import Mapping
 from dataclasses import dataclass
 from enum import Enum
 
@@ -10,6 +14,7 @@
 
 class IdentityProviderType(str, Enum):
     LOCAL = "local"
+    LOCAL_IDP = "local_idp"
     OIDC = "oidc"
     ENTRA = "entra"
     OKTA = "okta"
@@ -39,6 +44,14 @@ class EntraBridgeConfig:
     token_ttl_seconds: int = 300
 
 
+@dataclass(frozen=True)
+class LocalIdPBridgeConfig:
+    issuer: str = "http://localhost/predicate-local-idp"
+    audience: str = "api://predicate-authority"
+    signing_key: str = "predicate-local-idp-dev-key"
+    token_ttl_seconds: int = 300
+
+
 class IdentityBridge:
     """Local bridge implementation for development/local-only mode."""
 
@@ -120,3 +133,84 @@ def exchange_token(
             token_type=result.token_type,
             provider=IdentityProviderType.ENTRA,
         )
+
+
+class LocalIdPBridge:
+    """Local IdP emulator for dev/offline/air-gapped workflows."""
+
+    def __init__(self, config: LocalIdPBridgeConfig) -> None:
+        self._config = config
+
+    def exchange_token(
+        self, subject: PrincipalRef, state_evidence: StateEvidence
+    ) -> TokenExchangeResult:
+        expires_at = int(time.time()) + self._config.token_ttl_seconds
+        token = self._mint_token(
+            subject=subject,
+            state_evidence=state_evidence,
+            expires_at_epoch_s=expires_at,
+            grant_kind="access",
+            refresh_token=None,
+        )
+        return TokenExchangeResult(
+            access_token=token,
+            expires_at_epoch_s=expires_at,
+            provider=IdentityProviderType.LOCAL_IDP,
+        )
+
+    def refresh_token(
+        self, refresh_token: str, subject: PrincipalRef, state_evidence: StateEvidence
+    ) -> TokenExchangeResult:
+        expires_at = int(time.time()) + self._config.token_ttl_seconds
+        token = self._mint_token(
+            subject=subject,
+            state_evidence=state_evidence,
+            expires_at_epoch_s=expires_at,
+            grant_kind="refresh_access",
+            refresh_token=refresh_token,
+        )
+        return TokenExchangeResult(
+            access_token=token,
+            expires_at_epoch_s=expires_at,
+            provider=IdentityProviderType.LOCAL_IDP,
+        )
+
+    def _mint_token(
+        self,
+        subject: PrincipalRef,
+        state_evidence: StateEvidence,
+        expires_at_epoch_s: int,
+        grant_kind: str,
+        refresh_token: str | None,
+    ) -> str:
+        header = {"alg": "HS256", "typ": "JWT", "kid": "predicate-local-idp-dev"}
+        payload: dict[str, str | int | None] = {
+            "iss": self._config.issuer,
+            "aud": self._config.audience,
+            "sub": subject.principal_id,
+            "state_hash": state_evidence.state_hash,
+            "state_source": state_evidence.source,
+            "token_kind": grant_kind,
+            "exp": expires_at_epoch_s,
+            "iat": int(time.time()),
+            "tenant_id": subject.tenant_id,
+            "session_id": subject.session_id,
+            "refresh_token_hash": (
+                hashlib.sha256(refresh_token.encode("utf-8")).hexdigest()
+                if refresh_token is not None
+                else None
+            ),
+        }
+        header_b64 = _b64url_json(header)
+        payload_b64 = _b64url_json(payload)
+        signing_input = f"{header_b64}.{payload_b64}".encode()
+        signature = hmac.new(
+            self._config.signing_key.encode("utf-8"), signing_input, hashlib.sha256
+        ).digest()
+        signature_b64 = base64.urlsafe_b64encode(signature).rstrip(b"=").decode("utf-8")
+        return f"{header_b64}.{payload_b64}.{signature_b64}"
+
+
+def _b64url_json(value: Mapping[str, str | int | None]) -> str:
+    encoded = json.dumps(value, separators=(",", ":")).encode("utf-8")
+    return base64.urlsafe_b64encode(encoded).rstrip(b"=").decode("utf-8")