delcred 0.2.0__py3-none-any.whl

delcred/__init__.py

@@ -0,0 +1,189 @@
+"""delcred — short-lived, per-task, per-user-scoped credentials for AI agents.
+
+Five-line happy path::
+
+    import delcred
+
+    tok = delcred.delegate(
+        user="u_123", agent="billing-agent",
+        scope="invoices:read", resource="https://api.acme.test/v1",
+        user_token=user_jwt, agent_token=agent_jwt,
+    )
+    claims = delcred.verify(tok, expected_resource="https://api.acme.test/v1")
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import keys, policy, tokens
+from ._common import DEFAULT_TTL
+from .audit import AuditLog
+from .broker import Broker
+from .exchange import (
+    TOKEN_TYPE_BROKER_KEY,
+    TOKEN_TYPE_JWT,
+    ExchangeError,
+)
+from .exchange import (
+    exchange as _exchange,
+)
+from .exchange import (
+    verify as _verify,
+)
+from .policy import PolicyError
+from .revocation import RevocationList
+from .tokens import ExpiredToken, InvalidToken, TokenError
+from .trust import TrustConfigError, add_trusted_issuer, trusted_issuers
+
+__version__ = "0.2.0"
+__all__ = [
+    "DEFAULT_TTL",
+    "TOKEN_TYPE_BROKER_KEY",
+    "TOKEN_TYPE_JWT",
+    "ExchangeError",
+    "ExpiredToken",
+    "InvalidToken",
+    "PolicyError",
+    "TokenError",
+    "TrustConfigError",
+    "__version__",
+    "agent_token",
+    "delegate",
+    "delegate_api_key",
+    "init",
+    "revoke_agent",
+    "revoke_token",
+    "revoke_user",
+    "trust_add",
+    "trusted_issuers",
+    "user_token",
+    "verify",
+    "verify_broker_key",
+]
+
+
+def init(base: Path | None = None, force: bool = False) -> Path:
+    """Create a delcred home: issuer keypair + default policy. Returns home path."""
+    from ._common import home as _home
+    from .keys import key_paths
+
+    h = base or _home()
+    priv, _ = key_paths(h)
+    if priv.exists() and not force:
+        raise FileExistsError(f"issuer key already exists at {priv} (use force=True)")
+    keys.generate(h)
+    policy.policy_path(h).write_text(policy.default_policy())
+    AuditLog(h).record("init", home=str(h))
+    return h
+
+
+def delegate(
+    *,
+    user: str | None = None,
+    agent: str | None = None,
+    scope: str,
+    resource: str,
+    user_token: str,
+    agent_token: str,
+    ttl: int = DEFAULT_TTL,
+    base: Path | None = None,
+) -> str:
+    """Mint a delegation JWT via RFC 8693 exchange. Returns the token."""
+    result = _exchange(
+        subject_token=user_token,
+        actor_token=agent_token,
+        scope=scope,
+        resource=resource,
+        requested_token_type=TOKEN_TYPE_JWT,
+        ttl=ttl,
+        base=base,
+    )
+    return result.credential
+
+
+def delegate_api_key(
+    *,
+    scope: str,
+    resource: str,
+    user_token: str,
+    agent_token: str,
+    ttl: int = DEFAULT_TTL,
+    base: Path | None = None,
+) -> str:
+    """Mint an opaque ephemeral API key (``dk_…``) backed by a delegation."""
+    result = _exchange(
+        subject_token=user_token,
+        actor_token=agent_token,
+        scope=scope,
+        resource=resource,
+        requested_token_type=TOKEN_TYPE_BROKER_KEY,
+        ttl=ttl,
+        base=base,
+    )
+    return result.credential
+
+
+def verify(
+    token: str,
+    *,
+    expected_resource: str,
+    base: Path | None = None,
+) -> dict[str, Any]:
+    """Verify a delegation JWT (signature → expiry → revocation → audience).
+
+    ``expected_resource`` is required — audience pinning is the
+    confused-deputy defense and must not be skippable.
+    """
+    return _verify(token, expected_resource=expected_resource, base=base)
+
+
+def verify_broker_key(key: str, base: Path | None = None) -> dict[str, Any]:
+    """Redeem an opaque broker key → capability record (burns single-use keys)."""
+    from ._common import home as _home
+
+    return Broker(base or _home()).redeem(key)
+
+
+def revoke_token(jti: str, reason: str = "", base: Path | None = None) -> None:
+    from ._common import home as _home
+
+    RevocationList(base or _home()).revoke_jti(jti, reason=reason)
+
+
+def revoke_agent(agent: str, reason: str = "", base: Path | None = None) -> None:
+    """Kill switch: invalidate every credential for this agent, user untouched."""
+    from ._common import home as _home
+
+    h = base or _home()
+    RevocationList(h).revoke_agent(agent, reason=reason)
+    AuditLog(h).record("agent_revoked", agent=agent, reason=reason)
+
+
+def revoke_user(user: str, reason: str = "", base: Path | None = None) -> None:
+    """Kill switch: invalidate every delegation made by this user."""
+    from ._common import home as _home
+
+    h = base or _home()
+    RevocationList(h).revoke_user(user, reason=reason)
+    AuditLog(h).record("user_revoked", user=user, reason=reason)
+
+
+def agent_token(agent_id: str, ttl: int = 86400, base: Path | None = None) -> str:
+    from ._common import home as _home
+
+    return tokens.mint_agent_token(agent_id, ttl=ttl, base=base or _home())
+
+
+def trust_add(iss: str, key_file: str, base: Path | None = None) -> Path:
+    """Trust an external IdP's subject tokens: register its Ed25519 public key."""
+    from ._common import home as _home
+
+    return add_trusted_issuer(iss, key_file, base=base or _home())
+
+
+def user_token(user_id: str, ttl: int = 3600, base: Path | None = None) -> str:
+    from ._common import home as _home
+
+    return tokens.mint_user_token(user_id, ttl=ttl, base=base or _home())

delcred/_common.py

@@ -0,0 +1,53 @@
+"""delcred home-directory layout and shared helpers."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+DEFAULT_TTL = 900  # 15 minutes — the primary blast-radius control
+MAX_TTL = 3600  # hard cap: 60 minutes, enforced server-side
+CLOCK_SKEW_LEEWAY = 60  # seconds of acceptable clock skew
+ISSUER_ID = "delcred"
+KEY_PREFIX = "dk_"  # opaque broker keys look like: dk_<urlsafe>
+
+
+def home() -> Path:
+    """State directory: $DELCRED_HOME or ~/.delcred (created 0700)."""
+    p = Path(os.environ.get("DELCRED_HOME", Path.home() / ".delcred"))
+    p.mkdir(mode=0o700, parents=True, exist_ok=True)
+    # Harden pre-existing dirs too.
+    try:
+        os.chmod(p, 0o700)
+    except OSError:
+        pass
+    return p
+
+
+def assert_private(path: Path) -> None:
+    """Refuse to use a private key file that is readable by group/other."""
+    mode = stat.S_IMODE(path.stat().st_mode)
+    if mode & 0o077:
+        raise PermissionError(
+            f"refusing to use {path}: permissions {oct(mode)} are too open "
+            "(must be 0600 or stricter)"
+        )
+
+
+def write_private(path: Path, data: bytes) -> None:
+    """Write a secret file with 0600 permissions (no races via O_CREAT|O_EXCL)."""
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, data)
+    finally:
+        os.close(fd)
+    os.chmod(path, 0o600)
+
+
+def load_json(path: Path, default):
+    try:
+        return json.loads(path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return default

delcred/audit.py

@@ -0,0 +1,53 @@
+"""Append-only audit log (JSONL).
+
+Every security-relevant event is logged with actor identities, jti, scope,
+resource, and outcome — but NEVER token values or raw API keys.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from ._common import home
+
+# Intra-process half of mutual exclusion (see revocation.py): keeps
+# concurrent threads from interleaving JSON lines.
+_thread_lock = threading.Lock()
+
+
+class AuditLog:
+    def __init__(self, base: Path | None = None):
+        self.path = (base or home()) / "audit.jsonl"
+        self.path.touch(exist_ok=True)
+
+    def record(self, event: str, **fields: Any) -> None:
+        entry = {"ts": int(time.time()), "event": event}
+        entry.update(fields)
+        # Defense in depth: never allow a token/key value into the log, even
+        # if a caller passes one by mistake.
+        for banned in ("token", "subject_token", "actor_token", "api_key", "key"):
+            entry.pop(banned, None)
+        with _thread_lock, open(self.path, "a") as f:
+            fcntl.flock(f, fcntl.LOCK_EX)
+            try:
+                f.write(json.dumps(entry) + "\n")
+                f.flush()
+                os.fsync(f.fileno())
+            finally:
+                fcntl.flock(f, fcntl.LOCK_UN)
+
+    def tail(self, n: int = 20) -> list[dict[str, Any]]:
+        lines = self.path.read_text().splitlines()
+        out = []
+        for line in lines[-n:]:
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return out

delcred/broker.py

@@ -0,0 +1,268 @@
+"""Ephemeral API-key broker (merged market-gap #10).
+
+Problem: agents today hold raw API keys (Stripe keys, DB passwords) in their
+environment — one prompt injection and the key is exfiltrated. delcred's
+answer: the agent never sees the real key. Instead it gets an *opaque,
+short-lived, single-purpose* key (``dk_<urlsafe>``) that maps to a delegation
+record. Redeeming it yields the *capability* (a delegation JWT scoped to one
+resource), never the underlying secret.
+
+Storage: only SHA-256 hashes of keys are kept (constant-time compare on
+redeem). Records carry the same TTL + revocation semantics as JWT
+delegations. This module is intentionally the *redemption half* of the
+exchange — every broker key is born from a policy-checked delegation.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from ._common import KEY_PREFIX, home
+from .audit import AuditLog
+from .revocation import RevocationList
+from .tokens import InvalidToken, decode_unverified
+
+# fcntl locks are process-associated (see revocation.py): this module-level
+# lock provides the intra-process half of mutual exclusion for the broker
+# file. Never nest it.
+_thread_lock = threading.Lock()
+
+# Grace added to revocation entries so a burned jti stays denylisted past
+# the token's exp + clock-skew leeway (finding #5).
+BURN_GRACE = 300
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+def _hash(key: str) -> str:
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+class BrokerError(Exception):
+    pass
+
+
+class Broker:
+    """Issues and redeems opaque ephemeral keys backed by delegation records."""
+
+    def __init__(self, base: Path | None = None):
+        self.base = base or home()
+        self.path = self.base / "broker.jsonl"
+        self.path.touch(exist_ok=True)
+        self.revocations = RevocationList(self.base)
+        self.audit = AuditLog(self.base)
+
+    def _append(self, record: dict[str, Any]) -> None:
+        with _thread_lock, open(self.path, "a") as f:
+            fcntl.flock(f, fcntl.LOCK_EX)
+            try:
+                f.write(json.dumps(record) + "\n")
+                f.flush()
+                os.fsync(f.fileno())
+            finally:
+                fcntl.flock(f, fcntl.LOCK_UN)
+
+    def _records(self) -> list[dict[str, Any]]:
+        rows = []
+        with _thread_lock, open(self.path) as f:
+            fcntl.flock(f, fcntl.LOCK_SH)
+            try:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        try:
+                            rows.append(json.loads(line))
+                        except json.JSONDecodeError:
+                            continue
+            finally:
+                fcntl.flock(f, fcntl.LOCK_UN)
+        return rows
+
+    def issue(
+        self,
+        *,
+        user: str,
+        agent: str,
+        scope: str,
+        resource: str,
+        ttl: int,
+        delegation_jwt: str,
+        single_use: bool = False,
+        label: str = "",
+    ) -> str:
+        """Create an opaque key bound to an already-minted delegation JWT."""
+        raw = KEY_PREFIX + secrets.token_urlsafe(32)
+        now = _now()
+        try:
+            delegation_jti = decode_unverified(delegation_jwt).get("jti")
+        except InvalidToken:
+            delegation_jti = None
+        self._append(
+            {
+                "key_hash": _hash(raw),
+                "jti": f"broker-{secrets.token_urlsafe(12)}",
+                # Finding #1: bind the key to its delegation JWT so revoking
+                # the JWT's jti also kills this key.
+                "delegation_jti": delegation_jti,
+                "user": user,
+                "agent": agent,
+                "scope": scope,
+                "resource": resource,
+                "issued_at": now,
+                "expires_at": now + ttl,
+                "single_use": single_use,
+                "label": label,
+                # NOTE: the raw key is never written anywhere; only its hash.
+            }
+        )
+        return raw
+
+    def _reject(self, reason: str, **fields: Any) -> BrokerError:
+        # Finding #6: uniform outward message (no key-existence oracle);
+        # distinct reason only in the audit log, never with key material.
+        self.audit.record("broker_redeem_failed", reason=reason, **fields)
+        return BrokerError("invalid API key")
+
+    def check(self, key: str) -> bool:
+        """Non-consuming validity check (no single-use burn).
+
+        Used by the sidecar to re-validate cached broker keys.
+        Returns True only if the key would redeem successfully.
+        """
+        want = _hash(key)
+        match: dict[str, Any] | None = None
+        for rec in self._records():
+            if hmac.compare_digest(rec.get("key_hash", ""), want):
+                match = rec
+                break
+        if match is None or match["expires_at"] < _now():
+            return False
+        claims = {
+            "jti": match["jti"],
+            "sub": match["user"],
+            "act": {"sub": match["agent"]},
+        }
+        revoked, _ = self.revocations.is_revoked(claims)
+        if not revoked and match.get("delegation_jti"):
+            revoked, _ = self.revocations.is_revoked(
+                {**claims, "jti": match["delegation_jti"]}
+            )
+        # NOTE: single-use keys report False once consumed — the sidecar
+        # then mints a fresh one instead of serving a dead credential.
+        return not revoked
+
+    def redeem(self, key: str) -> dict[str, Any]:
+        """Validate an opaque key → capability record. Burns single-use keys.
+
+        Raises BrokerError("invalid API key") on any failure — unknown,
+        expired, or revoked are indistinguishable by design.
+        """
+        want = _hash(key)
+        match: dict[str, Any] | None = None
+        for rec in self._records():
+            if hmac.compare_digest(rec.get("key_hash", ""), want):
+                match = rec
+                break
+        if match is None:
+            raise self._reject("unknown_key")
+        now = _now()
+        if match["expires_at"] < now:
+            raise self._reject("expired", jti=match["jti"])
+        claims = {
+            "jti": match["jti"],
+            "sub": match["user"],
+            "act": {"sub": match["agent"]},
+        }
+        revoked, why = self.revocations.is_revoked(claims)
+        # Finding #1: also honor revocation of the bound delegation JWT.
+        if not revoked and match.get("delegation_jti"):
+            revoked, why = self.revocations.is_revoked(
+                {**claims, "jti": match["delegation_jti"]}
+            )
+        if revoked:
+            raise self._reject("revoked", jti=match["jti"], detail=why)
+        if match.get("single_use"):
+            # Atomic burn: exactly one concurrent redeem wins; the losers get
+            # the uniform "invalid API key" (no double-spend, no oracle).
+            burned = self.revocations.burn_once(
+                match["jti"],
+                reason="single-use broker key consumed",
+                expires_at=match["expires_at"] + BURN_GRACE,
+            )
+            if not burned:
+                raise self._reject("replay", jti=match["jti"])
+        self.audit.record(
+            "broker_redeemed",
+            jti=match["jti"],
+            user=match["user"],
+            agent=match["agent"],
+            resource=match["resource"],
+        )
+        return {
+            "user": match["user"],
+            "agent": match["agent"],
+            "scope": match["scope"],
+            "resource": match["resource"],
+            "expires_at": match["expires_at"],
+            "label": match.get("label", ""),
+        }
+
+    def revoke_key(self, key: str, reason: str = "") -> bool:
+        """Revoke by raw key value (hashes it, denylists the record's jti)."""
+        want = _hash(key)
+        for rec in self._records():
+            if hmac.compare_digest(rec.get("key_hash", ""), want):
+                self.revocations.revoke_jti(
+                    rec["jti"],
+                    reason=reason or "broker key revoked",
+                    expires_at=rec["expires_at"],
+                )
+                return True
+        return False
+
+    def prune(self) -> int:
+        """Drop expired records. Returns number removed.
+
+        The read-filter-replace cycle holds an exclusive lock throughout:
+        keys issued concurrently (mid-prune) are never lost to the replace.
+        """
+        now = _now()
+        with _thread_lock, open(self.path, "a+") as f:
+            fcntl.flock(f, fcntl.LOCK_EX)
+            try:
+                f.seek(0)
+                kept, dropped = [], 0
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        r = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    if r.get("expires_at", 0) < now:
+                        dropped += 1
+                        continue
+                    kept.append(r)
+                if dropped:
+                    tmp = self.path.with_suffix(".tmp")
+                    with open(tmp, "w") as tf:
+                        for r in kept:
+                            tf.write(json.dumps(r) + "\n")
+                        tf.flush()
+                        os.fsync(tf.fileno())
+                    os.replace(tmp, self.path)
+                return dropped
+            finally:
+                fcntl.flock(f, fcntl.LOCK_UN)