veltro-suite-auth 0.1.0

Canonical Veltro suite auth contract: Auth.js session decode + suite-service token mint/verify.

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):

  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):

  EMIT_CONTRACT_VECTORS=1 pnpm vitest run src/server/services/suite/__tests__/contract-vectors.test.ts
  

Local development

# 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:

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.