delcred 0.2.0__tar.gz

delcred-0.2.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: delcred
+Version: 0.2.0
+Summary: Short-lived, per-task, per-user-scoped credentials for AI agents — RFC 8693 delegation + ephemeral API-key broker
+Author: Calas Automations Inc.
+License: MIT
+Keywords: agents,oauth,delegation,credentials,zero-trust,rfc8693
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyJWT>=2.8
+Requires-Dist: cryptography>=41
+Requires-Dist: PyYAML>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# delcred — delegated credentials for AI agents
+
+**Stop giving agents your real API keys.** delcred mints short-lived,
+per-task, per-user-scoped credentials for agents: one credential naming both
+the human (`sub`) and the agent (`act`), pinned to a single API, expiring in
+minutes. Revoke the agent without locking out the human.
+
+This is **market-gap #1 (Agent Identity & Delegated Credentials) merged with
+#10 (Agent API Key Broker)** — the broker is the redemption half of
+delegation: agents get *capability-shaped* credentials (a scoped JWT or an
+opaque `dk_…` key), never the underlying secret.
+
+```
+pip install delcred
+delcred init
+# edit ~/.delcred/policy.yaml — one grant per (user, agent) pair
+```
+
+## 30-second tour
+
+```bash
+# 1. identities (agent = actor_token, user = subject_token)
+delcred agent-token billing-agent > /tmp/agent.jwt
+delcred user-token u_alice > /tmp/user.jwt        # dev only; prod uses your IdP's JWT
+
+# 2. exchange → delegation (RFC 8693 style).
+#    Prefer files/env over CLI args — command lines are visible in `ps`.
+delcred agent-token billing-agent > /tmp/agent.jwt
+delcred user-token u_alice > /tmp/user.jwt        # dev only; prod uses your IdP's JWT
+delcred exchange --subject-token-file /tmp/user.jwt \
+                 --actor-token-file   /tmp/agent.jwt \
+                 --scope "invoices:read" --resource https://api.acme.test/v1
+# ($DELCRED_SUBJECT_TOKEN / $DELCRED_ACTOR_TOKEN work too)
+# → eyJhbGciOiJFZERTQSIs...   (15-min JWT: sub=u_alice, act=billing-agent)
+
+# 3. or an opaque API-key-shaped credential instead of a JWT
+delcred exchange ... --as-api-key
+# → dk_7f3a...
+
+# 4. verify — --resource is REQUIRED (audience pinning is the confused-deputy defense)
+delcred verify <token> --resource https://api.acme.test/v1
+
+# 5. revoke the agent — the human is untouched
+delcred revoke --agent billing-agent --reason "suspected prompt injection"
+```
+
+## External IdPs (production subject tokens)
+
+delcred is **not** an IdP — it never does login or OAuth flows. But it
+accepts your IdP's user JWTs as `subject_token`: register the issuer once
+(Ed25519 public key), then pass the IdP's tokens straight into `exchange`:
+
+```bash
+delcred trust-add --iss https://idp.example.com --key-file ./idp-pub.pem
+# → copies the key to ~/.delcred/trusted_issuers/ and records the mapping
+#   in policy.yaml under `trusted_issuers:`
+
+delcred exchange --subject-token-file /tmp/idp-user.jwt \
+                 --actor-token-file   /tmp/agent.jwt \
+                 --scope "invoices:read" --resource https://api.acme.test/v1
+# subject claims come from the IdP token (iss/sub verified against the
+# registered key); only EdDSA tokens are accepted, mirroring local policy.
+```
+
+Or declare it directly in `policy.yaml`:
+
+```yaml
+trusted_issuers:
+  "https://idp.example.com": "trusted_issuers/idp.pem"   # relative to ~/.delcred
+```
+
+Notes: the local issuer (`iss: delcred`) can never be shadowed by this
+registry; unknown issuers are rejected; a trusted token with `kind: agent`
+is still refused as a subject (no token laundering).
+
+## Library (5 lines)
+
+```python
+import delcred
+
+tok = delcred.delegate(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")
+
+key = delcred.delegate_api_key(...)          # opaque dk_… credential
+cap = delcred.verify_broker_key(key)         # redeem → capability record
+
+delcred.revoke_agent("billing-agent", reason="...")  # kill switch
+delcred.revoke_user("u_alice")                       # kill switch
+delcred.revoke_token(jti)                            # single token
+```
+
+## The sidecar pattern (recommended)
+
+Agents should never see tokens at all. Run the sidecar; it mints, caches,
+and injects credentials for allowlisted upstreams:
+
+```bash
+delcred sidecar --port 8080 \
+  --map 'api.acme.test=invoices:read|https://api.acme.test/v1' \
+  --user-token-file /tmp/user.jwt --agent-token-file /tmp/agent.jwt
+# agent calls http://localhost:8080 with X-Delcred-Upstream: api.acme.test
+# sidecar injects: Authorization: Bearer <15-min delegation token>
+#
+# The sidecar's own identity can come from --user-token/--agent-token,
+# --user-token-file/--agent-token-file, or $DELCRED_SIDECAR_USER_TOKEN /
+# $DELCRED_SIDECAR_AGENT_TOKEN. Prefer files or env — command lines are
+# visible in `ps`. The sidecar reads them once at startup into memory.
+```
+
+Or run the HTTP API: `delcred serve --port 8400`
+(`POST /exchange`, `/verify`, `/broker/redeem`, `/revoke`, `GET /health`).
+
+## Policy (`~/.delcred/policy.yaml`)
+
+Deny by default. A grant is the *only* thing that lets an exchange mint:
+
+```yaml
+grants:
+  - user: u_alice
+    agent: billing-agent
+    scopes: ["invoices:read"]
+    resources: ["https://api.acme.test/v1"]  # exact match (RFC 8707)
+    max_ttl: 900        # seconds; global hard cap is 3600
+    single_use: false   # true → jti burned on first verify
+```
+
+Dry-run: `delcred policy check --user u_alice --agent billing-agent --scope invoices:read --resource https://api.acme.test/v1`
+
+## Security model
+
+- **Ed25519 only.** Strict `algorithms=["EdDSA"]`, issuer pinned, `typ: at+jwt`.
+  `none`/HS256/RSA confusion rejected.
+- **Short lifetimes are the primary control:** default 15 min, hard cap 60 min,
+  clamped server-side no matter what the requester asks.
+- **Confused-deputy defense:** every token carries an RFC 8707 resource
+  indicator; verifiers must check audience (`delcred verify --resource`).
+- **Scope discipline:** requested scopes must be ⊆ the grant; agents can never
+  mint beyond their grant.
+- **Revocation:** per-token `jti` denylist + per-agent and per-user kill
+  switches, checked on every verify. Single-use tokens burn on first verify.
+- **Broker keys:** only SHA-256 hashes stored; constant-time compare on redeem;
+  uniform error messages (no key-existence oracle); every broker key is bound
+  to its delegation JWT — revoking the JWT's `jti` kills the key too.
+- **Hygiene:** private keys 0600 (refuses to load otherwise), state dir 0700,
+  fcntl-locked append-only JSONL, audit log never contains token/key values,
+  token inputs via file/env (not `ps`-visible CLI args).
+- **Trust boundary:** agent identity tokens are operator-asserted — whoever
+  controls the delcred home defines agent identities. Host access control
+  *is* the identity root.
+
+## Limitations (read before production)
+
+1. **Bearer tokens.** Delegation JWTs and `dk_…` keys are bearer credentials:
+   anyone holding one can use it until it expires. Mitigations shipped: 15-min
+   default TTL, single-use option, resource pinning, instant local revocation.
+   Sender-constrained tokens (DPoP/mTLS) are **not** in v1 — on the roadmap.
+2. **Single-writer revocation.** The denylist lives in one delcred home.
+   There is no multi-host revocation sync in v1 — run one issuer per trust
+   domain, or accept that a revocation on host A doesn't reach host B.
+3. **Single-use semantics.** The burn is atomic across processes and threads
+   (check-and-set under an exclusive lock): exactly one concurrent verify or
+   redeem wins, the rest are rejected. Don't use single-use as an exactly-once
+   *execution* primitive — it bounds credential replay, not downstream effects.
+4. **Local user assertions are dev-only.** `delcred user-token` mints a
+   self-asserted subject token. In production, register your IdP with
+   `delcred trust-add` and pass its real user JWTs as `subject_token` —
+   delcred verifies signature/issuer/expiry against the registered key, not
+   your login flow. delcred is a token service, not an IdP.
+5. **`delcred serve` binds localhost without auth.** Put TLS + authentication
+   in front before exposing it; anyone who can reach `/exchange` can mint
+   within policy.
+6. **No chained delegation.** `may_act` (agent→sub-agent) is deferred to v2.
+7. **Clock skew.** 60s leeway is assumed; larger drift breaks verification.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest tests/ -q
+```
+
+Layout: `delcred/{tokens,keys,policy,exchange,revocation,broker,audit,cli,server,sidecar}.py`
+
+## License
+
+MIT — Calas Automations Inc.

delcred-0.2.0/README.md

@@ -0,0 +1,188 @@
+# delcred — delegated credentials for AI agents
+
+**Stop giving agents your real API keys.** delcred mints short-lived,
+per-task, per-user-scoped credentials for agents: one credential naming both
+the human (`sub`) and the agent (`act`), pinned to a single API, expiring in
+minutes. Revoke the agent without locking out the human.
+
+This is **market-gap #1 (Agent Identity & Delegated Credentials) merged with
+#10 (Agent API Key Broker)** — the broker is the redemption half of
+delegation: agents get *capability-shaped* credentials (a scoped JWT or an
+opaque `dk_…` key), never the underlying secret.
+
+```
+pip install delcred
+delcred init
+# edit ~/.delcred/policy.yaml — one grant per (user, agent) pair
+```
+
+## 30-second tour
+
+```bash
+# 1. identities (agent = actor_token, user = subject_token)
+delcred agent-token billing-agent > /tmp/agent.jwt
+delcred user-token u_alice > /tmp/user.jwt        # dev only; prod uses your IdP's JWT
+
+# 2. exchange → delegation (RFC 8693 style).
+#    Prefer files/env over CLI args — command lines are visible in `ps`.
+delcred agent-token billing-agent > /tmp/agent.jwt
+delcred user-token u_alice > /tmp/user.jwt        # dev only; prod uses your IdP's JWT
+delcred exchange --subject-token-file /tmp/user.jwt \
+                 --actor-token-file   /tmp/agent.jwt \
+                 --scope "invoices:read" --resource https://api.acme.test/v1
+# ($DELCRED_SUBJECT_TOKEN / $DELCRED_ACTOR_TOKEN work too)
+# → eyJhbGciOiJFZERTQSIs...   (15-min JWT: sub=u_alice, act=billing-agent)
+
+# 3. or an opaque API-key-shaped credential instead of a JWT
+delcred exchange ... --as-api-key
+# → dk_7f3a...
+
+# 4. verify — --resource is REQUIRED (audience pinning is the confused-deputy defense)
+delcred verify <token> --resource https://api.acme.test/v1
+
+# 5. revoke the agent — the human is untouched
+delcred revoke --agent billing-agent --reason "suspected prompt injection"
+```
+
+## External IdPs (production subject tokens)
+
+delcred is **not** an IdP — it never does login or OAuth flows. But it
+accepts your IdP's user JWTs as `subject_token`: register the issuer once
+(Ed25519 public key), then pass the IdP's tokens straight into `exchange`:
+
+```bash
+delcred trust-add --iss https://idp.example.com --key-file ./idp-pub.pem
+# → copies the key to ~/.delcred/trusted_issuers/ and records the mapping
+#   in policy.yaml under `trusted_issuers:`
+
+delcred exchange --subject-token-file /tmp/idp-user.jwt \
+                 --actor-token-file   /tmp/agent.jwt \
+                 --scope "invoices:read" --resource https://api.acme.test/v1
+# subject claims come from the IdP token (iss/sub verified against the
+# registered key); only EdDSA tokens are accepted, mirroring local policy.
+```
+
+Or declare it directly in `policy.yaml`:
+
+```yaml
+trusted_issuers:
+  "https://idp.example.com": "trusted_issuers/idp.pem"   # relative to ~/.delcred
+```
+
+Notes: the local issuer (`iss: delcred`) can never be shadowed by this
+registry; unknown issuers are rejected; a trusted token with `kind: agent`
+is still refused as a subject (no token laundering).
+
+## Library (5 lines)
+
+```python
+import delcred
+
+tok = delcred.delegate(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")
+
+key = delcred.delegate_api_key(...)          # opaque dk_… credential
+cap = delcred.verify_broker_key(key)         # redeem → capability record
+
+delcred.revoke_agent("billing-agent", reason="...")  # kill switch
+delcred.revoke_user("u_alice")                       # kill switch
+delcred.revoke_token(jti)                            # single token
+```
+
+## The sidecar pattern (recommended)
+
+Agents should never see tokens at all. Run the sidecar; it mints, caches,
+and injects credentials for allowlisted upstreams:
+
+```bash
+delcred sidecar --port 8080 \
+  --map 'api.acme.test=invoices:read|https://api.acme.test/v1' \
+  --user-token-file /tmp/user.jwt --agent-token-file /tmp/agent.jwt
+# agent calls http://localhost:8080 with X-Delcred-Upstream: api.acme.test
+# sidecar injects: Authorization: Bearer <15-min delegation token>
+#
+# The sidecar's own identity can come from --user-token/--agent-token,
+# --user-token-file/--agent-token-file, or $DELCRED_SIDECAR_USER_TOKEN /
+# $DELCRED_SIDECAR_AGENT_TOKEN. Prefer files or env — command lines are
+# visible in `ps`. The sidecar reads them once at startup into memory.
+```
+
+Or run the HTTP API: `delcred serve --port 8400`
+(`POST /exchange`, `/verify`, `/broker/redeem`, `/revoke`, `GET /health`).
+
+## Policy (`~/.delcred/policy.yaml`)
+
+Deny by default. A grant is the *only* thing that lets an exchange mint:
+
+```yaml
+grants:
+  - user: u_alice
+    agent: billing-agent
+    scopes: ["invoices:read"]
+    resources: ["https://api.acme.test/v1"]  # exact match (RFC 8707)
+    max_ttl: 900        # seconds; global hard cap is 3600
+    single_use: false   # true → jti burned on first verify
+```
+
+Dry-run: `delcred policy check --user u_alice --agent billing-agent --scope invoices:read --resource https://api.acme.test/v1`
+
+## Security model
+
+- **Ed25519 only.** Strict `algorithms=["EdDSA"]`, issuer pinned, `typ: at+jwt`.
+  `none`/HS256/RSA confusion rejected.
+- **Short lifetimes are the primary control:** default 15 min, hard cap 60 min,
+  clamped server-side no matter what the requester asks.
+- **Confused-deputy defense:** every token carries an RFC 8707 resource
+  indicator; verifiers must check audience (`delcred verify --resource`).
+- **Scope discipline:** requested scopes must be ⊆ the grant; agents can never
+  mint beyond their grant.
+- **Revocation:** per-token `jti` denylist + per-agent and per-user kill
+  switches, checked on every verify. Single-use tokens burn on first verify.
+- **Broker keys:** only SHA-256 hashes stored; constant-time compare on redeem;
+  uniform error messages (no key-existence oracle); every broker key is bound
+  to its delegation JWT — revoking the JWT's `jti` kills the key too.
+- **Hygiene:** private keys 0600 (refuses to load otherwise), state dir 0700,
+  fcntl-locked append-only JSONL, audit log never contains token/key values,
+  token inputs via file/env (not `ps`-visible CLI args).
+- **Trust boundary:** agent identity tokens are operator-asserted — whoever
+  controls the delcred home defines agent identities. Host access control
+  *is* the identity root.
+
+## Limitations (read before production)
+
+1. **Bearer tokens.** Delegation JWTs and `dk_…` keys are bearer credentials:
+   anyone holding one can use it until it expires. Mitigations shipped: 15-min
+   default TTL, single-use option, resource pinning, instant local revocation.
+   Sender-constrained tokens (DPoP/mTLS) are **not** in v1 — on the roadmap.
+2. **Single-writer revocation.** The denylist lives in one delcred home.
+   There is no multi-host revocation sync in v1 — run one issuer per trust
+   domain, or accept that a revocation on host A doesn't reach host B.
+3. **Single-use semantics.** The burn is atomic across processes and threads
+   (check-and-set under an exclusive lock): exactly one concurrent verify or
+   redeem wins, the rest are rejected. Don't use single-use as an exactly-once
+   *execution* primitive — it bounds credential replay, not downstream effects.
+4. **Local user assertions are dev-only.** `delcred user-token` mints a
+   self-asserted subject token. In production, register your IdP with
+   `delcred trust-add` and pass its real user JWTs as `subject_token` —
+   delcred verifies signature/issuer/expiry against the registered key, not
+   your login flow. delcred is a token service, not an IdP.
+5. **`delcred serve` binds localhost without auth.** Put TLS + authentication
+   in front before exposing it; anyone who can reach `/exchange` can mint
+   within policy.
+6. **No chained delegation.** `may_act` (agent→sub-agent) is deferred to v2.
+7. **Clock skew.** 60s leeway is assumed; larger drift breaks verification.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest tests/ -q
+```
+
+Layout: `delcred/{tokens,keys,policy,exchange,revocation,broker,audit,cli,server,sidecar}.py`
+
+## License
+
+MIT — Calas Automations Inc.

delcred-0.2.0/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-0.2.0/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-0.2.0/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