veltro-suite-auth 1.3.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
  • strict organization-contract decoding:
    • v1: unversioned org_id="default", normalized to session_contract_version=1 and suite_org_id="default"
    • v2: session_contract_version=2 plus a validated suite_org_id; a transitional org_id, when present, must match exactly
    • missing, malformed, unsupported, conflicting, and non-default-v1 claims raise SessionInvalid
• 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().

Old settings:* and external:* families keep optional actor claims. Product-scoped chad:* and warden:* tokens require actor_email and the transitional actor_suite_role. During the bounded consumers-first rollout, a legacy token may omit the entire Veltro-owned actor-role v2 tuple. Once any v2 field is present, all are mandatory: actor_role_contract_version=2, product-bound actor_app, and exact native actor_app_role; the native and coarse roles must agree. Verification exposes the authenticated tuple on ServiceTokenClaims and rejects partial, wrong-product, unknown-role, wrong-type, or conflicting claims before consumer JIT side effects. The final producer release always emits v2; CHAD and Warden remain authoritative for what their native roles permit.

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.

The fresh-cookie gate mints v1 default, v2 default, v2 non-default, and a conflicting v2 legacy/new pair. Accepting a signed v2 claim identifies the suite Organization but does not authorize it by itself: CHAD and Warden must resolve SessionClaims.suite_org_id to local Organization state before side effects.

• 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 — ten suite-service vectors covering the legacy scopes, every actor-required MCP family, svc=veltro, and rejection of an actorless MCP token. 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

Publish (after merge to main)

The Publish suite auth to PyPI workflow builds and publishes with PyPI Trusted Publishing. Its PyPI publisher must match:

• owner: veltrosecurity
• repository: vectorflow
• workflow: publish-suite-auth.yml
• environment: pypi

Dispatch the workflow from main. Never republish an existing version — bump both pyproject.toml and veltro_suite_auth.__version__ for every release.