obsigil 0.1.0__py3-none-any.whl

obsigil/__init__.py

@@ -0,0 +1,65 @@
+"""obsigil — a mandate-token format and shared-secret JWT alternative.
+
+A token split into a public **manifest** and an encrypted **mandate**, each an
+authenticated, deterministically-sealed ciphertext (AES-SIV / AES-GCM-SIV) in
+compact text. Each half's fields are a canonical CBOR map (RFC 8949 §4.2);
+reserved fields take negative integer keys, application data non-negative
+integer or text keys. Verification is symmetric — the same mandate key both
+mints and verifies — so obsigil fits shared-secret (HS256-style) JWT/JWE use
+cases, not public-key verification.
+
+This package is the pure-Python reference implementation, built on
+``cryptography`` for the AEAD primitives and ``cbor2`` for CBOR decoding (the
+canonical encoder is obsigil's own).
+
+    import obsigil
+
+    key = obsigil.generate_key()
+    tok = obsigil.Obsigil.mint(
+        clauses={"role": "admin"},
+        mandate_key=key,
+        exp=4_000_000_000,
+        aud=["api"],
+        manifest={"iss": "auth.example"},
+    )
+    obsigil.Obsigil(tok.token()).claims()                       # advisory, front end
+    obsigil.Obsigil(tok.token(), keys=key, audience="api",
+                    now=1).clauses()                            # authoritative, backend
+
+The free functions ``mint`` / ``clauses`` / ``claims`` / ``mandate`` /
+``manifest`` wrap the same core.
+"""
+
+from __future__ import annotations
+
+from ._constants import MANIFEST_KEY
+from .core import Obsigil, clauses_unchecked, mandate_plaintext
+from .errors import ObsigilError, Reason
+from .keys import generate_key
+from .manifest import authorization_header, claims, mandate, manifest, manifest_plaintext
+from .mint import mint
+from .uuid7 import generate_uuid7, is_uuid7, is_uuid7_bytes, uuid7_time
+from .verify import clauses
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MANIFEST_KEY",
+    "Obsigil",
+    "ObsigilError",
+    "Reason",
+    "authorization_header",
+    "claims",
+    "clauses",
+    "clauses_unchecked",
+    "generate_key",
+    "generate_uuid7",
+    "is_uuid7",
+    "is_uuid7_bytes",
+    "mandate",
+    "mandate_plaintext",
+    "manifest",
+    "manifest_plaintext",
+    "mint",
+    "uuid7_time",
+]

obsigil/_constants.py

@@ -0,0 +1,51 @@
+"""Pinned constants and the reserved-key namespace (the published manifest
+key of Construction §5.2, the output layout of Algorithm registry §6.2, the
+Limits and robustness rules of the Security Considerations §16.10, the
+reserved namespace of Reserved fields §8.1)."""
+
+from __future__ import annotations
+
+# The public 64-byte manifest key (the published manifest key, Construction §5.2). Public by design: it opens
+# AND forges manifests. Every conformant implementation MUST use this value.
+MANIFEST_KEY: bytes = bytes.fromhex(
+    "381284633d02ea5f35df8596b5cc4218310060468e8b465455a415174ea6e966"
+    "a9f48eec4ba446ddfc8b78587895356f45a75a1ab7419454dd9f7aa8a95dbdd5"
+)
+
+# Lowest legal decoded length of a sealed half (the output layout of
+# Sealing parameters and output layout, §6.2): the AEAD's
+# 16-byte floor plus at least one byte of CBOR plaintext (the empty map
+# 0xa0).
+MIN_HALF_BYTES: int = 17
+
+# Reserved field keys: the negative-integer namespace (the reserved
+# namespace of Reserved fields, §8.1). The
+# sign of a map key is its namespace — negative is obsigil's, non-negative
+# integers and text strings are the application's.
+TID_KEY: int = -1
+EXP_KEY: int = -2
+AUD_KEY: int = -3
+SUB_KEY: int = -4
+ISS_KEY: int = -5
+
+# Reserved wire key -> conventional name, and the inverse. An implementation
+# MAY surface reserved fields under their names (Reserved fields §8.1; the
+# reserved-field access of API conformance §12.4).
+RESERVED_KEYS: dict = {
+    TID_KEY: "tid",
+    EXP_KEY: "exp",
+    AUD_KEY: "aud",
+    SUB_KEY: "sub",
+    ISS_KEY: "iss",
+}
+RESERVED_NAMES: dict = {name: key for key, name in RESERVED_KEYS.items()}
+
+# Hard ceiling on clock-skew leeway, seconds (Limits and robustness, §16.10): a configured
+# leeway is clamped to this so an over-large value cannot silently extend a
+# token past its exp.
+MAX_LEEWAY: int = 60
+
+# Default cap on a half's decoded byte length (Limits and robustness, §16.10): admits any
+# realistic mandate while refusing an attacker-supplied oversize half before
+# any trial decryption.
+DEFAULT_MAX_DECODED_LEN: int = 64 * 1024

obsigil/aead.py

@@ -0,0 +1,52 @@
+"""Deterministic AEAD seal/open (Algorithm registry, spec §6), on pyca/cryptography.
+
+No random nonce, no associated data (Sealing parameters and output layout, §6.2):
+
+* Code 0 (AES-SIV, RFC 5297): the full 64-byte master is the AES-256-SIV
+  key; sealed with a zero-element associated-data vector. Layout
+  ``synthetic-IV(16) || ciphertext``.
+* Code 1 (AES-GCM-SIV, RFC 8452): the 32-byte key is
+  ``HKDF-Expand(master, "gcmsiv", 32)`` over HMAC-SHA-256 (Expand only);
+  sealed with a fixed all-zero 12-byte nonce. Layout
+  ``ciphertext || tag(16)``.
+
+All cryptography-library usage is isolated to this module.
+"""
+
+from __future__ import annotations
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCMSIV, AESSIV
+from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpand
+
+_GCMSIV_NONCE = b"\x00" * 12
+
+
+def _gcmsiv_key(master: bytes) -> bytes:
+    # Expand-only: master IS the PRK; info = "gcmsiv", L = 32 (Key material, §6.1).
+    return HKDFExpand(algorithm=hashes.SHA256(), length=32, info=b"gcmsiv").derive(master)
+
+
+def seal(plaintext: bytes, master: bytes, alg: str) -> bytes:
+    """Seal a half's plaintext under a 64-byte master with the AEAD named by
+    ``alg``. Output layout per the Sealing parameters and output layout section (§6.2)."""
+    if alg == "0":
+        # Empty AD list => zero-element S2V vector, not one empty component.
+        return AESSIV(master).encrypt(plaintext, [])
+    if alg == "1":
+        return AESGCMSIV(_gcmsiv_key(master)).encrypt(_GCMSIV_NONCE, plaintext, None)
+    raise ValueError(f"obsigil: unsupported algorithm code {alg!r}")
+
+
+def open_(sealed: bytes, master: bytes, alg: str) -> bytes | None:
+    """Open a sealed half. Returns the plaintext, or ``None`` on
+    authentication failure or an algorithm code this build cannot open."""
+    try:
+        if alg == "0":
+            return AESSIV(master).decrypt(sealed, [])
+        if alg == "1":
+            return AESGCMSIV(_gcmsiv_key(master)).decrypt(_GCMSIV_NONCE, sealed, None)
+        return None
+    except (InvalidTag, ValueError):
+        return None

obsigil/core.py

@@ -0,0 +1,249 @@
+"""The :class:`Obsigil` token view (API conformance, §12): one type, three roles — a
+keyless front-end view, a verifying backend view, and a minting issuer — over
+an obsigil token. The free functions ``mint`` / ``clauses`` / ``claims`` /
+``mandate`` / ``manifest`` remain as thin wrappers around the same core.
+
+Each half is reachable at three fidelities (the three fidelities of API conformance, §12.2): the wire string
+(:meth:`Obsigil.mandate` / :meth:`Obsigil.manifest`), the decrypted plaintext
+(``*_plaintext``), and the parsed fields (:meth:`Obsigil.clauses` /
+:meth:`Obsigil.claims`). The mandate ladder relaxes one layer at a time and
+never relaxes authentication (authentication vs policy layers, §16.3).
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional, Union
+
+from ._constants import DEFAULT_MAX_DECODED_LEN
+from .errors import ObsigilError, Reason
+from .manifest import authorization_header as _authorization_header
+from .manifest import claims as _claims
+from .manifest import mandate as _mandate
+from .manifest import manifest as _manifest
+from .manifest import manifest_plaintext as _manifest_plaintext
+from .mint import mint as _mint
+from .serial import deserialize
+from .uuid7 import uuid7_time
+from .verify import _authenticate, _surface_unenforced
+from .verify import clauses as _clauses_verify
+
+_UNSET = object()
+Keys = Union[bytes, "list[bytes]", "tuple[bytes, ...]"]
+
+
+class Obsigil:
+    """A view over an obsigil token (API conformance, §12).
+
+    * ``Obsigil(token)`` — keyless front-end view: read the advisory manifest
+      (:meth:`claims`) and forward the mandate (:meth:`mandate`).
+    * ``Obsigil(token, keys=…, audience=…, …)`` — verifying backend view:
+      :meth:`clauses` authenticates and enforces policy, raising on failure.
+    * ``Obsigil.mint(…)`` — issuer: build and seal a fresh token.
+
+    >>> import obsigil
+    >>> key = bytes(range(1, 65))
+    >>> tok = obsigil.Obsigil.mint(clauses={"role": "admin"}, mandate_key=key,
+    ...                            exp=4_000_000_000, aud=["api"])
+    >>> obsigil.Obsigil(tok.token(), keys=key, audience="api", now=1).clause("role")
+    'admin'
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        keys: Optional[Keys] = None,
+        audience: Optional[str] = None,
+        leeway: int = 0,
+        now: Optional[int] = None,
+        max_decoded_len: int = DEFAULT_MAX_DECODED_LEN,
+        on_reject: Optional[Callable[[Reason], None]] = None,
+    ) -> None:
+        self._token = token
+        self._keys = keys
+        self._audience = audience
+        self._leeway = leeway
+        self._now = now
+        self._max = max_decoded_len
+        self._on_reject = on_reject
+        self._clauses_cache: object = _UNSET
+
+    @classmethod
+    def mint(
+        cls,
+        *,
+        clauses: dict,
+        mandate_key: bytes,
+        exp: int,
+        tid=None,
+        aud: Optional[list] = None,
+        sub: Optional[str] = None,
+        iss: Optional[str] = None,
+        alg: str = "0",
+        encoding: str = "b64",
+        manifest: Optional[dict] = None,
+    ) -> "Obsigil":
+        """Mint a token and return it as an :class:`Obsigil` view (Construction, §5).
+        ``tid`` is generated unless supplied (the tid clause, Reserved fields §8.2)."""
+        return cls(
+            _mint(
+                clauses=clauses,
+                mandate_key=mandate_key,
+                exp=exp,
+                tid=tid,
+                aud=aud,
+                sub=sub,
+                iss=iss,
+                alg=alg,
+                encoding=encoding,
+                manifest=manifest,
+            )
+        )
+
+    # --- wire fidelity (the three fidelities of API conformance, §12.2) ---
+
+    def token(self) -> str:
+        """The whole token string."""
+        return self._token
+
+    def mandate(self) -> Optional[str]:
+        """The mandate half as a standalone ``.0mandate`` token — the value
+        forwarded to the backend (Audiences, §9). ``None`` if no mandate half."""
+        return _mandate(self._token)
+
+    def manifest(self) -> Optional[str]:
+        """The manifest half as a standalone ``manifest0.`` token. ``None`` if
+        no manifest half."""
+        return _manifest(self._token)
+
+    # --- plaintext fidelity (authenticate only; backend-internal, authentication vs policy layers §16.3) ---
+
+    def mandate_plaintext(self) -> bytes:
+        """The decrypted mandate plaintext (canonical CBOR octets), with no
+        validation (the decoded reads of API conformance, §12.3). Authenticates first; raises on auth failure.
+        Backend-internal — keep non-bearer-facing (authentication vs policy layers, §16.3)."""
+        return self._decrypt()
+
+    def manifest_plaintext(self) -> Optional[bytes]:
+        """The decrypted manifest plaintext (canonical CBOR octets), keyless
+        and advisory (the three fidelities of API conformance, §12.2). ``None`` if absent or auth fails."""
+        return _manifest_plaintext(self._token, max_decoded_len=self._max)
+
+    # --- parsed fidelity (the three fidelities of API conformance, §12.2) ---
+
+    def claims(self) -> Optional[dict]:
+        """The advisory manifest claims, or ``None`` (keyless; the manifest is non-authoritative, §16.7).
+        Never raises."""
+        return _claims(self._token, max_decoded_len=self._max)
+
+    def clauses(self) -> dict:
+        """The verified mandate clauses (the decoded reads of API conformance, §12.3): authenticate and enforce
+        policy, raising :class:`ObsigilError` on any failure. The result is
+        cached. Requires a verifying view built with ``keys=``."""
+        if self._clauses_cache is _UNSET:
+            if self._keys is None:
+                raise ValueError("obsigil: no mandate key configured; build the view with keys=")
+            self._clauses_cache = _clauses_verify(
+                self._token,
+                keys=self._keys,
+                audience=self._audience,
+                leeway=self._leeway,
+                now=self._now,
+                max_decoded_len=self._max,
+                on_reject=self._on_reject,
+            )
+        return self._clauses_cache  # type: ignore[return-value]
+
+    def clauses_unchecked(self) -> dict:
+        """The mandate clauses with **no policy** applied (the decoded reads of API conformance, §12.3):
+        authenticate and decode the canonical CBOR map, but skip the value
+        checks (``exp`` / ``aud`` / ``tid`` well-formedness / reserved types).
+        A non-canonical or duplicate-key encoding still fails. Backend-internal
+        — keep non-bearer-facing (authentication vs policy layers, §16.3)."""
+        fields = deserialize(self._decrypt())
+        if fields is None:
+            raise ObsigilError()
+        return _surface_unenforced(fields)
+
+    # --- reserved-clause accessors (the reserved-field access of API conformance, §12.4) ---
+
+    def exp(self) -> int:
+        """Authoritative expiry (the exp clause, Reserved fields §8.3)."""
+        return self.clauses()["exp"]
+
+    def tid(self) -> str:
+        """The unique token id, UUIDv7 text form (the tid clause, Reserved fields §8.2)."""
+        return self.clauses()["tid"]
+
+    def issued_at(self) -> int:
+        """Issue time (NumericDate seconds), derived from ``tid`` (the tid clause, Reserved fields §8.2)."""
+        return uuid7_time(self.clauses()["tid"])
+
+    def sub(self) -> Optional[str]:
+        """Subject authorized, if present (the sub clause, Reserved fields §8.5)."""
+        return self.clauses().get("sub")
+
+    def iss(self) -> Optional[str]:
+        """Issuer, if present (the iss clause, Reserved fields §8.6)."""
+        return self.clauses().get("iss")
+
+    def aud(self) -> Optional[list]:
+        """Intended verifiers, if present (the aud clause, Reserved fields §8.4)."""
+        return self.clauses().get("aud")
+
+    def clause(self, key):
+        """A single clause by reserved name (``"tid"``, ``"exp"``, …) or by
+        application key (a non-negative integer or text string)."""
+        return self.clauses().get(key)
+
+    def authorization_header(self, scheme: str = "Bearer") -> Optional[str]:
+        """The ``Authorization`` value carrying the mandate (Audiences, §9)."""
+        return _authorization_header(self._token, scheme)
+
+    # --- internal ---
+
+    def _decrypt(self) -> bytes:
+        if self._keys is None:
+            raise ValueError("obsigil: no mandate key configured; build the view with keys=")
+        ok, payload = _authenticate(self._token, self._keys, self._max)
+        if not ok:
+            if self._on_reject is not None:
+                self._on_reject(payload)  # type: ignore[arg-type]
+            raise ObsigilError()
+        return payload  # type: ignore[return-value]
+
+
+# --- free-function wrappers over the backend-internal fidelities (the decoded
+# reads of API conformance §12.3, authentication vs policy layers §16.3). Thin
+# shims over the Obsigil view, mirroring the keyless free
+# functions in manifest.py. ---
+
+
+def clauses_unchecked(
+    token: str,
+    *,
+    keys: Keys,
+    max_decoded_len: int = DEFAULT_MAX_DECODED_LEN,
+    on_reject: Optional[Callable[[Reason], None]] = None,
+) -> dict:
+    """The mandate clauses with **no policy** applied (the decoded reads of API conformance, §12.3): authenticate
+    and decode the canonical CBOR map, but skip the value checks (``exp`` /
+    ``aud`` / ``tid`` well-formedness / reserved types). A non-canonical or
+    duplicate-key encoding still fails. Backend-internal — keep
+    non-bearer-facing (authentication vs policy layers, §16.3)."""
+    return Obsigil(token, keys=keys, max_decoded_len=max_decoded_len,
+                   on_reject=on_reject).clauses_unchecked()
+
+
+def mandate_plaintext(
+    token: str,
+    *,
+    keys: Keys,
+    max_decoded_len: int = DEFAULT_MAX_DECODED_LEN,
+    on_reject: Optional[Callable[[Reason], None]] = None,
+) -> bytes:
+    """The decrypted mandate plaintext — the canonical CBOR octets — with no
+    validation (the decoded reads of API conformance, §12.3). Authenticates first; raises on auth failure.
+    Backend-internal — keep non-bearer-facing (authentication vs policy layers, §16.3)."""
+    return Obsigil(token, keys=keys, max_decoded_len=max_decoded_len,
+                   on_reject=on_reject).mandate_plaintext()

obsigil/encoding.py

@@ -0,0 +1,90 @@
+"""Strict, canonical text codecs (Token structure, spec §4).
+
+Decoders return ``None`` on any non-canonical input — padding, whitespace,
+out-of-alphabet characters, non-zero trailing b64 bits, or a bad length —
+so callers can fold the failure into a uniform rejection (the uniform-failure rule of the Security Considerations, spec §16.6). We
+hand-roll these because the stdlib decoders do not enforce that strictness.
+"""
+
+from __future__ import annotations
+
+_B64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+_B64URL_REV = {ord(c): i for i, c in enumerate(_B64URL)}
+
+
+def decode_b64url(s: str) -> bytes | None:
+    """Decode URL-safe base64 with no padding (Token structure, spec §4)."""
+    n = len(s)
+    if n % 4 == 1:
+        return None
+    out = bytearray()
+    full = n // 4
+    i = 0
+    for _ in range(full):
+        a = _B64URL_REV.get(ord(s[i]))
+        b = _B64URL_REV.get(ord(s[i + 1]))
+        c = _B64URL_REV.get(ord(s[i + 2]))
+        d = _B64URL_REV.get(ord(s[i + 3]))
+        if a is None or b is None or c is None or d is None:
+            return None
+        out.append((a << 2) | (b >> 4))
+        out.append(((b & 0x0F) << 4) | (c >> 2))
+        out.append(((c & 0x03) << 6) | d)
+        i += 4
+    rem = n - full * 4
+    if rem == 2:
+        a = _B64URL_REV.get(ord(s[i]))
+        b = _B64URL_REV.get(ord(s[i + 1]))
+        if a is None or b is None or (b & 0x0F) != 0:
+            return None
+        out.append((a << 2) | (b >> 4))
+    elif rem == 3:
+        a = _B64URL_REV.get(ord(s[i]))
+        b = _B64URL_REV.get(ord(s[i + 1]))
+        c = _B64URL_REV.get(ord(s[i + 2]))
+        if a is None or b is None or c is None or (c & 0x03) != 0:
+            return None
+        out.append((a << 2) | (b >> 4))
+        out.append(((b & 0x0F) << 4) | (c >> 2))
+    return bytes(out)
+
+
+def encode_b64url(data: bytes) -> str:
+    """Encode bytes as URL-safe base64 with no padding (Token structure, spec §4)."""
+    out = []
+    n = len(data)
+    i = 0
+    while i + 3 <= n:
+        x = (data[i] << 16) | (data[i + 1] << 8) | data[i + 2]
+        out.append(_B64URL[(x >> 18) & 63])
+        out.append(_B64URL[(x >> 12) & 63])
+        out.append(_B64URL[(x >> 6) & 63])
+        out.append(_B64URL[x & 63])
+        i += 3
+    rem = n - i
+    if rem == 1:
+        x = data[i] << 16
+        out.append(_B64URL[(x >> 18) & 63])
+        out.append(_B64URL[(x >> 12) & 63])
+    elif rem == 2:
+        x = (data[i] << 16) | (data[i + 1] << 8)
+        out.append(_B64URL[(x >> 18) & 63])
+        out.append(_B64URL[(x >> 12) & 63])
+        out.append(_B64URL[(x >> 6) & 63])
+    return "".join(out)
+
+
+def decode_hex(s: str) -> bytes | None:
+    """Decode lowercase hex of even length (Token structure, spec §4). Uppercase is rejected."""
+    if len(s) % 2 != 0:
+        return None
+    for ch in s:
+        o = ord(ch)
+        if not (0x30 <= o <= 0x39 or 0x61 <= o <= 0x66):
+            return None
+    return bytes.fromhex(s)
+
+
+def encode_hex(data: bytes) -> str:
+    """Encode bytes as lowercase hex (Token structure, spec §4)."""
+    return data.hex()

obsigil/errors.py

@@ -0,0 +1,30 @@
+"""Error types. Verification failures are uniform and opaque to the bearer
+(the uniform-failure rule of the Security Considerations, spec §16.6)."""
+
+from __future__ import annotations
+
+import enum
+
+
+class Reason(str, enum.Enum):
+    """The internal cause of a rejection — for server-side logging via
+    ``clauses(..., on_reject=...)`` ONLY. A verifier MUST NOT signal *why* a
+    token was rejected to the bearer (the uniform-failure rule of the Security Considerations, spec §16.6)."""
+
+    MALFORMED = "malformed"
+    UNSUPPORTED = "unsupported"
+    AUTH_FAILED = "auth-failed"
+    EMPTY_MANDATE = "empty-mandate"
+    BAD_TID = "bad-tid"
+    MISSING_CLAUSE = "missing-clause"
+    EXPIRED = "expired"
+    AUDIENCE_MISMATCH = "audience-mismatch"
+
+
+class ObsigilError(Exception):
+    """The single, opaque failure :func:`obsigil.clauses` raises on any
+    rejection. Its message is uniform across every cause (the uniform-failure rule of the Security Considerations, spec §16.6); the
+    granular :class:`Reason` is delivered to ``on_reject``, never here."""
+
+    def __init__(self) -> None:
+        super().__init__("obsigil: token rejected")

obsigil/keys.py

@@ -0,0 +1,28 @@
+"""Mandate key handling (the mandate-key rules of Construction, spec §5.1)."""
+
+from __future__ import annotations
+
+import os
+
+from ._constants import MANIFEST_KEY
+
+
+def generate_key() -> bytes:
+    """Generate a fresh 64-byte mandate key from the platform CSPRNG (Construction, §5.1)."""
+    return os.urandom(64)
+
+
+def _assert_mandate_key(key: bytes) -> None:
+    """Reject a key that cannot be a mandate key: wrong length, the public
+    manifest key (accepting which would let anyone mint mandates, Construction §5.1), or
+    all-zero (a misconfiguration, never a CSPRNG output). Raises a
+    (non-uniform) configuration error; this is a deployment bug, not a token
+    rejection."""
+    if not isinstance(key, (bytes, bytearray)):
+        raise ValueError("obsigil: mandate key must be bytes")
+    if len(key) != 64:
+        raise ValueError("obsigil: mandate key must be 64 bytes")
+    if key == MANIFEST_KEY:
+        raise ValueError("obsigil: mandate key must not be the public manifest key")
+    if not any(key):
+        raise ValueError("obsigil: mandate key must not be all-zero")