veltro-suite-auth 0.1.0__tar.gz

veltro_suite_auth-0.1.0/.gitignore

@@ -0,0 +1,103 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+/src/generated/prisma
+
+/docs/plans/*
+/docs/screenshots/*
+/docs/internal/*
+# agent build output
+/agent/bin/
+.vectorflow/
+/scripts/internal/
+artifacts/
+
+# codeql
+.codeql/
+# worktrees
+.worktrees/
+
+Thumbs.db
+*.swp
+*.swo
+*~
+.idea/
+.vscode/
+*.code-workspace
+.env.*
+!.env.example
+
+# docs/cloud/ is gitignored: the directory holds Cloud-only documentation
+# (threat model, runbooks, operator notes) that lives in the closed
+# `cloud/` workspace and is published to vectorflow.sh/trust as a
+# customer-facing summary. The full documents are not part of the AGPL OSS
+# repo (see plan §15a R5 — 2026-05-17 removal).
+!docs/cloud/
+docs/cloud/*
+node_modules/
+.next/
+dist/
+build/
+__pycache__/
+*.pyc
+.venv/
+venv/
+.pytest_cache/
+*.egg-info/
+target/
+vendor/
+*.log
+coverage/
+.cache/
+tmp/
+
+# playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+e2e/.auth/
+/cloud/
+
+# understand-anything intermediate scan output (local-only artifacts)
+.understand-anything/

veltro_suite_auth-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: veltro-suite-auth
+Version: 0.1.0
+Summary: Canonical Veltro suite auth contract: Auth.js session decode + suite-service token mint/verify.
+Project-URL: Homepage, https://github.com/veltrosecurity/vectorflow/tree/main/packages/suite-auth-py
+Project-URL: Repository, https://github.com/veltrosecurity/vectorflow
+Author: Veltro Security
+License: AGPL-3.0-or-later
+Keywords: auth,authjs,jwe,suite-service-token,veltro
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: python-jose[cryptography]>=3.5.0
+Description-Content-Type: text/markdown
+
+# veltro-suite-auth
+
+The **canonical Veltro suite auth contract** — one published Python package for
+the two cross-service security primitives shared across the Veltro suite
+(VectorFlow, CHAD, WARDEN). Before this package each app carried its own
+byte-identical copy of the decoder/verifier; CHAD and WARDEN now depend on this
+package and carry none.
+
+## What it provides
+
+- **`veltro_suite_auth.session`** — decode VectorFlow's Auth.js v5 session
+  cookie (JWE, `alg=dir` / `enc=A256CBC-HS512`, HKDF-SHA256 key salted by the
+  cookie name) for delegated suite login.
+  - `decode_session(cookies, secret) -> SessionClaims | None`
+  - `SessionClaims`, `SessionError` / `SessionInvalid` / `SessionExpired`
+  - `SESSION_COOKIE_NAMES`, `derive_encryption_key`
+- **`veltro_suite_auth.service_token`** — mint + verify the short-lived (60s),
+  scoped, HS256 suite-service token used for machine-to-machine calls between
+  suite apps (issuer `veltro-suite`, audience `suite-service`).
+  - `mint_service_token(secret, *, scope, svc, actor_email=None, actor_suite_role=None) -> str`
+  - `verify_service_token(token, secret, required_scope) -> ServiceTokenClaims`
+  - `ServiceTokenClaims`, `ServiceTokenError` / `ServiceTokenInvalid` / `ServiceTokenExpired`
+  - `SUITE_SERVICE_ISSUER`, `SUITE_SERVICE_AUDIENCE`, `SUITE_SERVICE_MINTERS`,
+    `SUITE_SERVICE_TOKEN_TTL_SECONDS`
+- **`veltro_suite_auth.testing`** — golden cross-language vectors, shipped in
+  the wheel: `session_fixture()`, `service_token_vectors()`.
+
+All decode/verify behavior (including the `suite_role` fail-open-to-viewer
+semantics, family-aware scope satisfaction, and the optional `svc`/actor
+claims) is preserved exactly from the original CHAD/WARDEN implementations.
+
+## Contract source & rename map
+
+The code was moved **verbatim** from CHAD's `backend/app/core/vf_session.py`
+and `backend/app/core/suite_service_token.py`, plus WARDEN's minting logic from
+`backend/app/services/suite_token.py`. Only symbol names and CHAD/WARDEN-specific
+docstring prose changed:
+
+| old (CHAD / WARDEN) | new (`veltro_suite_auth`) |
+|---|---|
+| `decode_vf_session` | `decode_session` |
+| `VfSessionClaims` | `SessionClaims` |
+| `VfSessionError` / `VfSessionInvalid` / `VfSessionExpired` | `SessionError` / `SessionInvalid` / `SessionExpired` |
+| `SESSION_COOKIE_NAMES`, `derive_encryption_key` | *unchanged* |
+| `verify_suite_service_token` | `verify_service_token` |
+| `SuiteServiceClaims` | `ServiceTokenClaims` |
+| `SuiteServiceTokenError` / `...Invalid` / `...Expired` | `ServiceTokenError` / `ServiceTokenInvalid` / `ServiceTokenExpired` |
+| `SUITE_SERVICE_ISSUER` / `SUITE_SERVICE_AUDIENCE` / `SUITE_SERVICE_MINTERS` | *unchanged* |
+| WARDEN `mint_suite_service_token(scope)` (settings-coupled) | `mint_service_token(secret, *, scope, svc, ...)` (explicit params) |
+
+## Cross-language conformance
+
+The suite has a TypeScript minter (VectorFlow's
+`src/server/services/suite/service-token.ts`) and this Python decoder/verifier.
+Two per-PR gates in the VectorFlow repo keep them from drifting:
+
+- **`suite-auth-contract` CI job** — installs this package and runs its tests,
+  including `tests/conformance/test_fresh_session_roundtrip.py`, which shells
+  `node scripts/mint-test-session.mjs` to mint a **fresh** Auth.js cookie and
+  decodes it here. Catches VF-minter ⟂ Python-decoder drift on the session
+  cookie.
+- **`contract-vectors.test.ts`** — pins the committed
+  `vectors/service-token-vectors.json` against the live TS minters
+  (`mintSuiteServiceToken` / `mintSuiteExternalToken`). Catches TS-minter
+  drift on the service token; the Python side of the same vectors is asserted
+  by `tests/test_vectors.py`.
+
+## Regenerating the vectors
+
+- **`session-fixture.json`** — a fixed Auth.js cookie. Regenerate with
+  VectorFlow's script (from the repo root):
+
+  ```sh
+  node scripts/mint-test-session.mjs > packages/suite-auth-py/src/veltro_suite_auth/vectors/session-fixture.json
+  ```
+
+- **`service-token-vectors.json`** — the four suite-service token vectors
+  (`settings:read`, `settings:write` with actor; `external:read`,
+  `external:write` without actor), captured from the real TS minters under a
+  frozen clock. Regenerate with (from the repo root):
+
+  ```sh
+  EMIT_CONTRACT_VECTORS=1 pnpm vitest run src/server/services/suite/__tests__/contract-vectors.test.ts
+  ```
+
+## Local development
+
+```sh
+# from packages/suite-auth-py/
+python3.11 -m venv .venv && . .venv/bin/activate
+pip install -e . pytest
+pytest -v            # conformance test needs `node` + a repo checkout, else it skips
+```
+
+## Manual publish (after merge to main)
+
+There is no publish workflow — publishing is a manual step by the maintainer
+(matching the design system's manual-npm-publish precedent). From a clean
+checkout of `main`:
+
+```sh
+cd packages/suite-auth-py
+uv build            # or: python -m build
+uv publish          # or: twine upload dist/*   (needs a PyPI token)
+```
+
+Never republish an existing version — ship a new `0.1.x` for any fix.

veltro_suite_auth-0.1.0/README.md

@@ -0,0 +1,107 @@
+# veltro-suite-auth
+
+The **canonical Veltro suite auth contract** — one published Python package for
+the two cross-service security primitives shared across the Veltro suite
+(VectorFlow, CHAD, WARDEN). Before this package each app carried its own
+byte-identical copy of the decoder/verifier; CHAD and WARDEN now depend on this
+package and carry none.
+
+## What it provides
+
+- **`veltro_suite_auth.session`** — decode VectorFlow's Auth.js v5 session
+  cookie (JWE, `alg=dir` / `enc=A256CBC-HS512`, HKDF-SHA256 key salted by the
+  cookie name) for delegated suite login.
+  - `decode_session(cookies, secret) -> SessionClaims | None`
+  - `SessionClaims`, `SessionError` / `SessionInvalid` / `SessionExpired`
+  - `SESSION_COOKIE_NAMES`, `derive_encryption_key`
+- **`veltro_suite_auth.service_token`** — mint + verify the short-lived (60s),
+  scoped, HS256 suite-service token used for machine-to-machine calls between
+  suite apps (issuer `veltro-suite`, audience `suite-service`).
+  - `mint_service_token(secret, *, scope, svc, actor_email=None, actor_suite_role=None) -> str`
+  - `verify_service_token(token, secret, required_scope) -> ServiceTokenClaims`
+  - `ServiceTokenClaims`, `ServiceTokenError` / `ServiceTokenInvalid` / `ServiceTokenExpired`
+  - `SUITE_SERVICE_ISSUER`, `SUITE_SERVICE_AUDIENCE`, `SUITE_SERVICE_MINTERS`,
+    `SUITE_SERVICE_TOKEN_TTL_SECONDS`
+- **`veltro_suite_auth.testing`** — golden cross-language vectors, shipped in
+  the wheel: `session_fixture()`, `service_token_vectors()`.
+
+All decode/verify behavior (including the `suite_role` fail-open-to-viewer
+semantics, family-aware scope satisfaction, and the optional `svc`/actor
+claims) is preserved exactly from the original CHAD/WARDEN implementations.
+
+## Contract source & rename map
+
+The code was moved **verbatim** from CHAD's `backend/app/core/vf_session.py`
+and `backend/app/core/suite_service_token.py`, plus WARDEN's minting logic from
+`backend/app/services/suite_token.py`. Only symbol names and CHAD/WARDEN-specific
+docstring prose changed:
+
+| old (CHAD / WARDEN) | new (`veltro_suite_auth`) |
+|---|---|
+| `decode_vf_session` | `decode_session` |
+| `VfSessionClaims` | `SessionClaims` |
+| `VfSessionError` / `VfSessionInvalid` / `VfSessionExpired` | `SessionError` / `SessionInvalid` / `SessionExpired` |
+| `SESSION_COOKIE_NAMES`, `derive_encryption_key` | *unchanged* |
+| `verify_suite_service_token` | `verify_service_token` |
+| `SuiteServiceClaims` | `ServiceTokenClaims` |
+| `SuiteServiceTokenError` / `...Invalid` / `...Expired` | `ServiceTokenError` / `ServiceTokenInvalid` / `ServiceTokenExpired` |
+| `SUITE_SERVICE_ISSUER` / `SUITE_SERVICE_AUDIENCE` / `SUITE_SERVICE_MINTERS` | *unchanged* |
+| WARDEN `mint_suite_service_token(scope)` (settings-coupled) | `mint_service_token(secret, *, scope, svc, ...)` (explicit params) |
+
+## Cross-language conformance
+
+The suite has a TypeScript minter (VectorFlow's
+`src/server/services/suite/service-token.ts`) and this Python decoder/verifier.
+Two per-PR gates in the VectorFlow repo keep them from drifting:
+
+- **`suite-auth-contract` CI job** — installs this package and runs its tests,
+  including `tests/conformance/test_fresh_session_roundtrip.py`, which shells
+  `node scripts/mint-test-session.mjs` to mint a **fresh** Auth.js cookie and
+  decodes it here. Catches VF-minter ⟂ Python-decoder drift on the session
+  cookie.
+- **`contract-vectors.test.ts`** — pins the committed
+  `vectors/service-token-vectors.json` against the live TS minters
+  (`mintSuiteServiceToken` / `mintSuiteExternalToken`). Catches TS-minter
+  drift on the service token; the Python side of the same vectors is asserted
+  by `tests/test_vectors.py`.
+
+## Regenerating the vectors
+
+- **`session-fixture.json`** — a fixed Auth.js cookie. Regenerate with
+  VectorFlow's script (from the repo root):
+
+  ```sh
+  node scripts/mint-test-session.mjs > packages/suite-auth-py/src/veltro_suite_auth/vectors/session-fixture.json
+  ```
+
+- **`service-token-vectors.json`** — the four suite-service token vectors
+  (`settings:read`, `settings:write` with actor; `external:read`,
+  `external:write` without actor), captured from the real TS minters under a
+  frozen clock. Regenerate with (from the repo root):
+
+  ```sh
+  EMIT_CONTRACT_VECTORS=1 pnpm vitest run src/server/services/suite/__tests__/contract-vectors.test.ts
+  ```
+
+## Local development
+
+```sh
+# from packages/suite-auth-py/
+python3.11 -m venv .venv && . .venv/bin/activate
+pip install -e . pytest
+pytest -v            # conformance test needs `node` + a repo checkout, else it skips
+```
+
+## Manual publish (after merge to main)
+
+There is no publish workflow — publishing is a manual step by the maintainer
+(matching the design system's manual-npm-publish precedent). From a clean
+checkout of `main`:
+
+```sh
+cd packages/suite-auth-py
+uv build            # or: python -m build
+uv publish          # or: twine upload dist/*   (needs a PyPI token)
+```
+
+Never republish an existing version — ship a new `0.1.x` for any fix.

veltro_suite_auth-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "veltro-suite-auth"
+version = "0.1.0"
+description = "Canonical Veltro suite auth contract: Auth.js session decode + suite-service token mint/verify."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "AGPL-3.0-or-later" }
+authors = [{ name = "Veltro Security" }]
+keywords = ["veltro", "auth", "authjs", "jwe", "suite-service-token"]
+classifiers = [
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "python-jose[cryptography]>=3.5.0",
+    "cryptography>=43.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/veltrosecurity/vectorflow/tree/main/packages/suite-auth-py"
+Repository = "https://github.com/veltrosecurity/vectorflow"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/veltro_suite_auth"]

veltro_suite_auth-0.1.0/src/veltro_suite_auth/__init__.py

@@ -0,0 +1,60 @@
+"""veltro-suite-auth — the canonical Veltro suite auth contract.
+
+One source of truth for the two cross-service security primitives shared by the
+Veltro suite apps (VectorFlow, CHAD, WARDEN):
+
+- ``session`` — decode VectorFlow's Auth.js v5 session JWE for delegated login.
+- ``service_token`` — mint + verify the short-lived, scoped suite-service JWS
+  used for machine-to-machine calls between suite apps.
+
+CHAD and WARDEN import from here instead of carrying their own copies; the
+golden vectors under ``vectors/`` (surfaced by ``veltro_suite_auth.testing``)
+pin cross-language conformance with VectorFlow's TypeScript minters.
+"""
+
+from .service_token import (
+    SUITE_SERVICE_AUDIENCE,
+    SUITE_SERVICE_ISSUER,
+    SUITE_SERVICE_MINTERS,
+    SUITE_SERVICE_TOKEN_TTL_SECONDS,
+    ServiceTokenClaims,
+    ServiceTokenError,
+    ServiceTokenExpired,
+    ServiceTokenInvalid,
+    mint_service_token,
+    verify_service_token,
+)
+from .session import (
+    SESSION_COOKIE_NAMES,
+    SessionClaims,
+    SessionError,
+    SessionExpired,
+    SessionInvalid,
+    decode_session,
+    derive_encryption_key,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # session decode
+    "SESSION_COOKIE_NAMES",
+    "SessionClaims",
+    "SessionError",
+    "SessionExpired",
+    "SessionInvalid",
+    "decode_session",
+    "derive_encryption_key",
+    # suite-service token mint/verify
+    "SUITE_SERVICE_AUDIENCE",
+    "SUITE_SERVICE_ISSUER",
+    "SUITE_SERVICE_MINTERS",
+    "SUITE_SERVICE_TOKEN_TTL_SECONDS",
+    "ServiceTokenClaims",
+    "ServiceTokenError",
+    "ServiceTokenExpired",
+    "ServiceTokenInvalid",
+    "mint_service_token",
+    "verify_service_token",
+]

veltro_suite_auth-0.1.0/src/veltro_suite_auth/service_token.py

@@ -0,0 +1,234 @@
+"""Mint and verify suite-service tokens for scoped service-to-service calls.
+
+Cross-service token plane (Veltro suite): a suite app (VectorFlow, WARDEN, or
+CHAD) sometimes needs to make an AUTHORIZED machine call into a small set of
+another suite app's endpoints. This is a *separate, narrower* mechanism from
+``session.py``:
+
+- ``session.py`` decodes the suite's full Auth.js *user session* cookie (a
+  JWE) — it authenticates an interactive human sitting in a browser with that
+  cookie, for delegated login.
+- This module verifies (and mints) a short-lived, purpose-built JWT that a
+  suite app's *server* mints per outbound call (never a cookie, never handed to
+  a browser). It carries no session state — just an audience, the minting
+  service (``svc``), an explicit scope, and (optionally) the acting admin's
+  identity for audit attribution. A leaked/replayed token is useless outside
+  its ~60s TTL and cannot reach anything beyond the scope it names: there is no
+  general trust bridge between the apps.
+
+All suite tokens are signed with the shared suite secret (VF's NEXTAUTH_SECRET,
+fanned out to every suite app as VELTRO_SESSION_SECRET — see docker-compose.yml)
+because the delegated-login slice already established that as the suite's one
+shared secret. The ``suite-service`` audience keeps these machine tokens from
+being confused with the Auth.js cookie even though they share a signing key.
+
+See ``docs/adr/004`` (in the veltro umbrella) for the full spec: issuer
+``veltro-suite``, the ``svc`` minter claim, and the settings:* / external:*
+scope table.
+"""
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import time
+import uuid
+from dataclasses import dataclass
+
+SUITE_SERVICE_AUDIENCE = "suite-service"
+SUITE_SERVICE_ISSUER = "veltro-suite"
+
+# Suite apps that may mint a suite-service token (the ``svc`` claim). Purely
+# informational for audit attribution — verification does not authorize by
+# minter, only by scope.
+SUITE_SERVICE_MINTERS = ("vectorflow", "warden", "chad")
+
+# Minted-token lifetime. Deliberately short: a suite-service token is minted
+# immediately before use and consumed within the same outbound request — there
+# is no legitimate reason for one to outlive a single HTTP round trip by much.
+# Generous enough to absorb network latency/retries, tight enough that a
+# captured token is useless shortly after.
+SUITE_SERVICE_TOKEN_TTL_SECONDS = 60
+
+# Coupled to VectorFlow's suite_role contract (suite-role.ts), same tuple
+# session.py uses for the interactive-session claim.
+_SUITE_ROLES = ("admin", "editor", "viewer")
+
+# Scope model: two independent families, each ordered weakest -> strongest.
+# "<family>:write" implies "<family>:read" (a caller authorized to write is
+# trivially authorized to read), but the families are NOT interchangeable — an
+# "external:*" token can never satisfy a "settings:*" requirement and vice
+# versa. Each entry maps a scope to its (family, rank).
+_SCOPE_RANK: dict[str, tuple[str, int]] = {
+    "settings:read": ("settings", 0),
+    "settings:write": ("settings", 1),
+    "external:read": ("external", 0),
+    "external:write": ("external", 1),
+}
+
+
+@dataclass
+class ServiceTokenClaims:
+    scope: str
+    svc: str | None
+    actor_email: str | None
+    actor_suite_role: str | None
+    exp: int
+    jti: str
+
+
+class ServiceTokenError(Exception):
+    """Base error for suite-service token verification."""
+
+
+class ServiceTokenInvalid(ServiceTokenError):
+    """Token present but undecryptable, malformed, or not authorized."""
+
+
+class ServiceTokenExpired(ServiceTokenError):
+    """Token verified fine but its exp is in the past."""
+
+
+def _b64url(raw: bytes) -> str:
+    """base64url without padding — matches the minters and the verifier's decode."""
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(segment: str) -> bytes:
+    padding = "=" * (-len(segment) % 4)
+    try:
+        return base64.urlsafe_b64decode(segment + padding)
+    except (binascii.Error, ValueError) as exc:
+        raise ServiceTokenInvalid(f"malformed base64url segment: {exc}") from exc
+
+
+def mint_service_token(
+    secret: str,
+    *,
+    scope: str,
+    svc: str,
+    actor_email: str | None = None,
+    actor_suite_role: str | None = None,
+) -> str:
+    """Mint a 60s HS256 suite-service token authorizing one scoped call.
+
+    ``secret`` is the shared suite secret (VF's NEXTAUTH_SECRET, fanned out to
+    every suite app as VELTRO_SESSION_SECRET). ``scope`` is the scope the
+    outbound call needs (e.g. ``external:read`` for a GET, ``external:write``
+    for a writeback POST). ``svc`` is the minting service identity carried in
+    the ``svc`` claim (for audit). ``actor_email`` / ``actor_suite_role`` are
+    OPTIONAL interactive-admin attribution: when both are None (a
+    machine-to-machine call with no human in the loop) neither claim is
+    emitted. Compact HS256 serialization, unpadded base64url — the exact format
+    ``verify_service_token`` accepts. Authorization of the actor against the
+    requested scope is the caller's job; this function only signs.
+    """
+    now = int(time.time())
+    header = {"alg": "HS256", "typ": "JWT"}
+    payload: dict[str, object] = {
+        "iss": SUITE_SERVICE_ISSUER,
+        "aud": SUITE_SERVICE_AUDIENCE,
+        "svc": svc,
+        "scope": scope,
+        "iat": now,
+        "exp": now + SUITE_SERVICE_TOKEN_TTL_SECONDS,
+        "jti": str(uuid.uuid4()),
+    }
+    if actor_email is not None:
+        payload["actor_email"] = actor_email
+    if actor_suite_role is not None:
+        payload["actor_suite_role"] = actor_suite_role
+    encoded_header = _b64url(json.dumps(header, separators=(",", ":")).encode())
+    encoded_payload = _b64url(json.dumps(payload, separators=(",", ":")).encode())
+    signing_input = f"{encoded_header}.{encoded_payload}".encode()
+    signature = hmac.new(secret.encode(), signing_input, hashlib.sha256).digest()
+    return f"{encoded_header}.{encoded_payload}.{_b64url(signature)}"
+
+
+def verify_service_token(
+    token: str, secret: str, required_scope: str
+) -> ServiceTokenClaims:
+    """Verify a suite-minted service token (HS256, compact serialization).
+
+    Raises ``ServiceTokenInvalid`` for any structural/signature/claim failure
+    and ``ServiceTokenExpired`` when the signature checks out but ``exp`` has
+    passed. Callers should treat both as "reject the request" — the split
+    exists only so logging/metrics can distinguish expiry from tampering.
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ServiceTokenInvalid("malformed token: expected 3 segments")
+    encoded_header, encoded_payload, encoded_signature = parts
+
+    signing_input = f"{encoded_header}.{encoded_payload}".encode()
+    expected_sig = hmac.new(secret.encode(), signing_input, hashlib.sha256).digest()
+    actual_sig = _b64url_decode(encoded_signature)
+    if not hmac.compare_digest(expected_sig, actual_sig):
+        raise ServiceTokenInvalid("signature mismatch")
+
+    try:
+        header = json.loads(_b64url_decode(encoded_header))
+        payload = json.loads(_b64url_decode(encoded_payload))
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise ServiceTokenInvalid(f"malformed payload: {exc}") from exc
+
+    if not isinstance(header, dict) or header.get("alg") != "HS256":
+        raise ServiceTokenInvalid("unsupported or missing alg")
+    if not isinstance(payload, dict):
+        raise ServiceTokenInvalid("payload is not a JSON object")
+
+    if payload.get("iss") != SUITE_SERVICE_ISSUER:
+        raise ServiceTokenInvalid("bad issuer")
+    if payload.get("aud") != SUITE_SERVICE_AUDIENCE:
+        raise ServiceTokenInvalid("bad audience")
+
+    exp = payload.get("exp")
+    if not isinstance(exp, int):
+        raise ServiceTokenInvalid("missing integer 'exp' claim")
+    if exp <= int(time.time()):
+        raise ServiceTokenExpired(f"suite-service token expired at {exp}")
+
+    scope = payload.get("scope")
+    if scope not in _SCOPE_RANK:
+        raise ServiceTokenInvalid(f"unknown scope {scope!r}")
+    if required_scope not in _SCOPE_RANK:
+        raise ServiceTokenInvalid(f"unknown required_scope {required_scope!r}")
+    token_family, token_rank = _SCOPE_RANK[scope]
+    req_family, req_rank = _SCOPE_RANK[required_scope]
+    if token_family != req_family or token_rank < req_rank:
+        raise ServiceTokenInvalid(
+            f"insufficient scope: token has {scope!r}, endpoint requires {required_scope!r}"
+        )
+
+    # Minting service (``svc``) — exposed for audit. Optional so a token minted
+    # before the claim existed still verifies; when present it must be a
+    # non-empty string.
+    svc = payload.get("svc")
+    if svc is not None and (not isinstance(svc, str) or not svc):
+        raise ServiceTokenInvalid("svc claim present but not a non-empty string")
+
+    # Actor attribution is OPTIONAL: interactive suite-admin calls carry it,
+    # automated service-to-service calls (no human in the loop) omit it.
+    actor_email = payload.get("actor_email")
+    if actor_email is not None and (not isinstance(actor_email, str) or not actor_email):
+        raise ServiceTokenInvalid("actor_email present but not a non-empty string")
+
+    actor_suite_role = payload.get("actor_suite_role")
+    if actor_suite_role is not None and actor_suite_role not in _SUITE_ROLES:
+        raise ServiceTokenInvalid(
+            f"actor_suite_role {actor_suite_role!r} not in {_SUITE_ROLES}"
+        )
+
+    jti = payload.get("jti")
+    if not isinstance(jti, str) or not jti:
+        raise ServiceTokenInvalid("missing jti claim")
+
+    return ServiceTokenClaims(
+        scope=scope,
+        svc=svc,
+        actor_email=actor_email,
+        actor_suite_role=actor_suite_role,
+        exp=exp,
+        jti=jti,
+    )