edge-authz 0.1.0__py3-none-any.whl

edge_authz/__init__.py

@@ -0,0 +1,46 @@
+"""edge-authz: building blocks for an authorization enforcement point at the edge.
+
+- :class:`Principal`, :class:`Decision`, :class:`PolicyBackend` — who asks, what was decided, who decides
+- :class:`StaticTokenVerifier`, :func:`generate_token`, :func:`hash_token` — per-client bearer tokens
+- :func:`load_policy`, :func:`create_client_token`, :func:`revoke_client_token` — a versioned, archived TOML policy
+- :class:`JsonlAuditSink`, :func:`pseudonymize` — an audit log that must not lose entries or leak identifiers
+
+What a policy allows is up to the application; this package knows nothing about it.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .audit import AuditSink, JsonlAuditSink, pseudonymize
+from .decision import Decision, PolicyBackend, Principal
+from .policy_file import (
+    LoadedPolicy,
+    PolicyError,
+    create_client_token,
+    edit_policy,
+    load_policy,
+    revoke_client_token,
+)
+from .tokens import StaticTokenVerifier, generate_token, hash_token
+
+try:
+    __version__ = version("edge-authz")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+__all__ = [
+    "AuditSink",
+    "Decision",
+    "JsonlAuditSink",
+    "LoadedPolicy",
+    "PolicyBackend",
+    "PolicyError",
+    "Principal",
+    "StaticTokenVerifier",
+    "create_client_token",
+    "edit_policy",
+    "generate_token",
+    "hash_token",
+    "load_policy",
+    "pseudonymize",
+    "revoke_client_token",
+]

edge_authz/audit.py

@@ -0,0 +1,51 @@
+import hashlib
+import hmac
+import json
+import os
+import threading
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class AuditSink(Protocol):
+    """Receives one audit entry per decision. Raising means the entry was not kept."""
+
+    def write(self, entry: Mapping[str, Any]) -> None: ...
+
+
+class JsonlAuditSink:
+    """Appends audit entries as JSON lines and flushes each to disk before returning.
+
+    A failed write raises, so a caller can refuse the request it was about to
+    perform when its trace could not be kept. Entries carry a ``time`` field
+    (UTC, ISO 8601) unless the caller sets one.
+
+    Write only what may be kept: identifiers that are personal data go in
+    pseudonymized with :func:`pseudonymize`.
+    """
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    def write(self, entry: Mapping[str, Any]) -> None:
+        record = {"time": datetime.now(UTC).isoformat(timespec="milliseconds"), **entry}
+        line = json.dumps(
+            record, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+        )
+        with self._lock, self.path.open("a", encoding="utf-8", newline="\n") as f:
+            f.write(line + "\n")
+            f.flush()
+            os.fsync(f.fileno())
+
+
+def pseudonymize(key: bytes, value: str) -> str:
+    """Return a keyed hash of ``value`` for the audit log.
+
+    Equal values give equal pseudonyms, so entries can be correlated, but
+    without ``key`` a short identifier cannot be recovered by trying values.
+    """
+    return hmac.new(key, value.encode("utf-8"), hashlib.sha256).hexdigest()[:32]

edge_authz/decision.py

@@ -0,0 +1,50 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class Principal:
+    """The authenticated caller a decision is about, e.g. one client of a proxy.
+
+    ``attributes`` carries whatever the policy needs about the caller, such
+    as permissions read from the policy file.
+    """
+
+    id: str
+    attributes: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Decision:
+    """The outcome of a policy check.
+
+    ``reason_code`` is a stable, machine-readable word (``"allowed"``,
+    ``"method_not_enabled"``, …) and ``rule_id`` names the policy rule that
+    decided. ``details`` holds extra facts for the audit log; it must not
+    contain the secret or personal data the request carried.
+    """
+
+    allowed: bool
+    reason_code: str
+    rule_id: str = ""
+    details: Mapping[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def allow(cls, rule_id: str = "", **details: Any) -> "Decision":
+        return cls(True, "allowed", rule_id, details)
+
+    @classmethod
+    def deny(cls, reason_code: str, rule_id: str = "", **details: Any) -> "Decision":
+        return cls(False, reason_code, rule_id, details)
+
+
+class PolicyBackend(Protocol):
+    """Decides whether ``principal`` may perform ``action`` with ``attributes``.
+
+    Implementations must deny when they cannot decide.
+    """
+
+    async def decide(
+        self, principal: Principal, action: str, attributes: Mapping[str, Any]
+    ) -> Decision: ...

edge_authz/policy_file.py

@@ -0,0 +1,134 @@
+"""A policy kept in one TOML file, versioned and archived for traceability.
+
+The file carries an integer ``version`` in a table of the caller's choosing
+(``[proxy] version = 3``). Each load archives the exact bytes as
+``<archive_dir>/<version>-<sha256>.toml`` and refuses a version that was
+archived before with different content, so every decision can be traced to
+the policy that made it, even though the file itself lives outside version
+control.
+"""
+
+import hashlib
+import tomllib
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import tomlkit
+
+from .tokens import generate_token, hash_token
+
+
+class PolicyError(Exception):
+    """The policy file is missing, malformed, or inconsistent with its archive."""
+
+
+@dataclass(frozen=True)
+class LoadedPolicy:
+    path: Path
+    version: int
+    sha256: str
+    data: dict[str, Any]
+
+
+def load_policy(
+    path: str | Path, archive_dir: str | Path, *, version_table: str
+) -> LoadedPolicy:
+    """Read, version-check and archive the policy at ``path``.
+
+    Raises:
+        PolicyError: The file is unreadable or not TOML, ``[version_table].version``
+            is missing or not a positive integer, or the archive already holds this
+            version with different content (an edit without a version bump).
+    """
+    path = Path(path)
+    try:
+        raw = path.read_bytes()
+    except OSError as e:
+        raise PolicyError(f"cannot read policy file {path}: {type(e).__name__}") from e
+    try:
+        data = tomllib.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, tomllib.TOMLDecodeError) as e:
+        raise PolicyError(f"policy file {path} is not valid TOML: {e}") from e
+
+    version = data.get(version_table, {}).get("version")
+    if not isinstance(version, int) or isinstance(version, bool) or version < 1:
+        raise PolicyError(
+            f"policy file {path} needs [{version_table}] version = <positive integer>"
+        )
+
+    sha = hashlib.sha256(raw).hexdigest()
+    archive = Path(archive_dir)
+    archive.mkdir(parents=True, exist_ok=True)
+    for existing in archive.glob(f"{version}-*.toml"):
+        if existing.name != f"{version}-{sha}.toml":
+            raise PolicyError(
+                f"policy version {version} was archived before with different content; "
+                f"raise [{version_table}] version in {path}"
+            )
+    target = archive / f"{version}-{sha}.toml"
+    if not target.exists():
+        target.write_bytes(raw)
+    return LoadedPolicy(path, version, sha, data)
+
+
+def edit_policy(
+    path: str | Path,
+    change: Callable[[tomlkit.TOMLDocument], None],
+    *,
+    version_table: str,
+) -> int:
+    """Apply ``change`` to the policy document, raise its version, and save it.
+
+    Comments and layout are kept. Returns the new version.
+    """
+    path = Path(path)
+    doc = tomlkit.parse(path.read_text(encoding="utf-8"))
+    change(doc)
+    table = doc.setdefault(version_table, tomlkit.table())
+    version = int(table.get("version", 0)) + 1
+    table["version"] = version
+    path.write_text(tomlkit.dumps(doc), encoding="utf-8", newline="\n")
+    return version
+
+
+def create_client_token(
+    path: str | Path,
+    client: str,
+    *,
+    version_table: str,
+    clients_table: str = "clients",
+    prefix: str = "",
+) -> str:
+    """Issue a new token for ``client``: store its hash in the policy, return the token.
+
+    The token itself is not stored anywhere; show it once. Replaces an earlier
+    token of the same client.
+    """
+    token = generate_token(prefix)
+
+    def change(doc: tomlkit.TOMLDocument) -> None:
+        clients = doc.setdefault(clients_table, tomlkit.table(is_super_table=True))
+        entry = clients.setdefault(client, tomlkit.table())
+        entry["token_sha256"] = hash_token(token)
+
+    edit_policy(path, change, version_table=version_table)
+    return token
+
+
+def revoke_client_token(
+    path: str | Path, client: str, *, version_table: str, clients_table: str = "clients"
+) -> bool:
+    """Remove ``client``'s token hash from the policy. Returns whether it had one."""
+    removed = False
+
+    def change(doc: tomlkit.TOMLDocument) -> None:
+        nonlocal removed
+        entry = doc.get(clients_table, {}).get(client)
+        if entry is not None and "token_sha256" in entry:
+            del entry["token_sha256"]
+            removed = True
+
+    edit_policy(path, change, version_table=version_table)
+    return removed

edge_authz/tokens.py

@@ -0,0 +1,65 @@
+import hashlib
+import hmac
+import secrets
+from collections.abc import Mapping
+
+from .decision import Principal
+
+#: Random bytes per generated token (256 bits).
+TOKEN_BYTES = 32
+
+
+def generate_token(prefix: str = "") -> str:
+    """Return a new random token, URL-safe, optionally with an identifying prefix."""
+    return f"{prefix}{secrets.token_urlsafe(TOKEN_BYTES)}"
+
+
+def hash_token(token: str) -> str:
+    """Return the hex SHA-256 of ``token``, the form in which tokens are stored.
+
+    A plain hash is enough: generated tokens carry 256 random bits, so there is
+    nothing to guess, and no salt or slow hash would add protection.
+    """
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+class StaticTokenVerifier:
+    """Maps bearer tokens to principals through a fixed table of token hashes.
+
+    ``token_hashes`` maps a principal id to the hex SHA-256 of its token.
+    ``attributes`` optionally maps a principal id to its attributes.
+    """
+
+    def __init__(
+        self,
+        token_hashes: Mapping[str, str],
+        attributes: Mapping[str, Mapping[str, object]] | None = None,
+    ):
+        self._hashes = {pid: h.lower() for pid, h in token_hashes.items()}
+        self._attributes = attributes or {}
+
+    def verify(self, token: str | None) -> Principal | None:
+        """Return the principal ``token`` belongs to, or ``None``.
+
+        Every entry is compared in constant time, so timing reveals neither a
+        matching hash nor which entry it belongs to.
+        """
+        if not token:
+            return None
+        presented = hash_token(token)
+        found: str | None = None
+        for pid, expected in self._hashes.items():
+            if hmac.compare_digest(presented, expected):
+                found = pid
+        if found is None:
+            return None
+        return Principal(found, dict(self._attributes.get(found, {})))
+
+    def verify_authorization(self, header_value: str | None) -> Principal | None:
+        """Verify an ``Authorization`` header value of the form ``Bearer <token>``."""
+        if not header_value:
+            return None
+        scheme, _, token = header_value.partition(" ")
+        if scheme.lower() != "bearer" or not token or " " in token.strip():
+            return None
+        return self.verify(token.strip())

edge_authz-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: edge-authz
+Version: 0.1.0
+Summary: Edge authorization building blocks: client tokens, principals, decisions, a versioned and archived policy file, and a JSONL audit log. Framework-neutral.
+Author-email: Stephan Eberle <stephaneberle9@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: tomlkit>=0.13
+Description-Content-Type: text/markdown
+
+# edge-authz <!-- omit in toc -->
+
+Building blocks for an authorization enforcement point at the edge — a proxy
+or gateway that decides, per request, whether a caller may do something, and
+keeps a trace of every decision. Framework-neutral: no web framework, no
+policy engine.
+
+- [What it provides](#what-it-provides)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Client tokens](#client-tokens)
+  - [A versioned policy file](#a-versioned-policy-file)
+  - [Decisions](#decisions)
+  - [Audit log](#audit-log)
+- [Contributing](#contributing)
+- [License](#license)
+
+## What it provides
+
+| Piece | Purpose |
+| --- | --- |
+| `generate_token`, `hash_token`, `StaticTokenVerifier` | One random bearer token per client; only its SHA-256 is stored |
+| `load_policy` | Reads a TOML policy file, requires a version number, and archives every version it loads |
+| `create_client_token`, `revoke_client_token`, `edit_policy` | Change the policy file in place, keeping comments and raising its version |
+| `Principal`, `Decision`, `PolicyBackend` | Who asks, what was decided and why, and the interface of whatever decides |
+| `JsonlAuditSink`, `pseudonymize` | An append-only audit log flushed to disk per entry, and keyed pseudonyms for identifiers |
+
+What a policy allows is the application's business; this package only
+supplies the plumbing around it.
+
+## Installation
+
+The package is not published to PyPI. Install it from its Git repository:
+
+```bash
+uv add "edge-authz @ git+https://github.com/stephaneberle9/python-edge-authz.git"
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+### Client tokens
+
+```python
+from edge_authz import StaticTokenVerifier
+
+verifier = StaticTokenVerifier(
+    {"agent-a": "<sha256 of agent-a's token>"},
+    {"agent-a": {"may_write": True}},
+)
+principal = verifier.verify_authorization(request.headers.get("authorization"))
+if principal is None:
+    ...  # 401
+```
+
+Tokens carry 256 random bits, so a plain SHA-256 is enough to store them; all
+stored hashes are compared in constant time.
+
+### A versioned policy file
+
+```toml
+[proxy]
+version = 3
+
+[clients.agent-a]
+token_sha256 = "…"
+may_write = true
+```
+
+```python
+from edge_authz import create_client_token, load_policy
+
+policy = load_policy("policy.toml", "policy-archive", version_table="proxy")
+token = create_client_token("policy.toml", "agent-b", version_table="proxy", prefix="dcp_")
+print(token)  # shown once; only its hash is in the file
+```
+
+`load_policy` copies each version it loads to `<archive>/<version>-<sha256>.toml`
+and refuses a version that was archived before with different content, so a
+decision logged with a version and hash can always be traced back to the exact
+policy, even when the file itself is not under version control. Editing the
+file by hand means raising `version`; the token functions do that themselves.
+
+### Decisions
+
+```python
+from edge_authz import Decision, Principal
+
+class MyPolicy:
+    async def decide(self, principal: Principal, action: str, attributes) -> Decision:
+        if action in {"read"}:
+            return Decision.allow("reads")
+        return Decision.deny("action_not_enabled", "default")
+```
+
+### Audit log
+
+```python
+from edge_authz import JsonlAuditSink, pseudonymize
+
+audit = JsonlAuditSink("audit/audit.jsonl")
+audit.write({"client": principal.id, "decision": "allow", "subject": pseudonymize(key, subject_id)})
+```
+
+`write` raises when the entry could not be stored; refuse the request then.
+Pseudonymize identifiers that are personal data with a secret key: plain
+hashes of short identifiers are easy to reverse by trying values.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

edge_authz-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+edge_authz/__init__.py,sha256=V2HMjrz_FZc6e1OqUvS-GZNg2zfgCdeznzi5Vf5uTfc,1441
+edge_authz/audit.py,sha256=Tk0zyIReTlyoVZxmcFt64daqgbIlWFL8555WfUNAjOQ,1767
+edge_authz/decision.py,sha256=roZxuwCxfC6Xhug-z1-Z1TjgEe7tDsStYA3q_k_HzCk,1543
+edge_authz/policy_file.py,sha256=N5amWtapcdEnARA2erjDMJmSW8h15O-OyvFplMMoZwU,4464
+edge_authz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+edge_authz/tokens.py,sha256=XsOnRTOfc9vnhIo4ImmUR5hLUZDOQcLD7QH71WjL1fU,2303
+edge_authz-0.1.0.dist-info/METADATA,sha256=kb9AazkrmzSaFBwyj29dcJlEJ17TAMlmmbDuxkAOHr0,4132
+edge_authz-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+edge_authz-0.1.0.dist-info/licenses/LICENSE,sha256=gj8yMQmXVQ-u8qsZ6UdnofKnIp2wv0tBByT9E-mkpYE,1071
+edge_authz-0.1.0.dist-info/RECORD,,

edge_authz-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

edge_authz-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephan Eberle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.