snoozeml.auth — Authentication, RBAC & JWT Minting#

Authentication helpers, RBAC role definitions, and HMAC JWT minting/verification for SnoozeML.

Provides zero-dependency RFC 7519 JSON Web Token (JWT) creation and verification compatible with SnoozeML’s Rust authentication service (src/auth.rs).

class snoozeml.auth.Role(*values)[source]#

Bases: str, Enum

Role-Based Access Control (RBAC) tier matching SnoozeML’s src/auth.rs hierarchy.

Hierarchy: READ_ONLY (1) < INFERENCE (2) < ADMIN (3).

READ_ONLY = 'read_only'#

Read-only access to GET /v1/models.

INFERENCE = 'inference'#

Permission to execute model inference (REST & gRPC) and read model metadata.

ADMIN = 'admin'#

Full administrative access (load, unload, pin, unpin, upload, refresh, protected metrics).

classmethod from_str(value)[source]#

Normalizes a role string or Role enum into a canonical Role.

Accepts aliases supported by the Rust daemon ("admin", "administrator", "infer", "inference", "user", "read", "readonly", "read_only", "ro").

Parameters:

value (Role | str)

Return type:

Role

class snoozeml.auth.JwtAlgorithm(*values)[source]#

Bases: str, Enum

Supported HMAC signature algorithms for SnoozeML JWT authentication.

HS256 = 'HS256'#
HS384 = 'HS384'#
HS512 = 'HS512'#
classmethod from_str(value)[source]#

Parses a case-insensitive algorithm identifier into a JwtAlgorithm.

Parameters:

value (JwtAlgorithm | str)

Return type:

JwtAlgorithm

snoozeml.auth.create_jwt_token(secret=None, *, subject='snoozeml-client', role=Role.INFERENCE, roles=None, expires_in_secs=3600, exp=None, iat=None, nbf=None, issuer=None, audience=None, algorithm=JwtAlgorithm.HS256, extra_claims=None)[source]#

Mints a signed HMAC JSON Web Token (JWT) compatible with the SnoozeML daemon.

Both the shared secret and the generated JWT are automatically registered with SnoozeML’s log redaction filter so they never leak in client telemetry.

Parameters:

  • secret (str | None) – Shared HMAC secret key. If None, reads SNOOZE_JWT_SECRET from the environment.

  • subject (str) – Subject identifier claim (sub).

  • role (Role | str | None) – Primary RBAC role claim ("read_only", "inference", or "admin").

  • roles (Sequence[Role | str] | None) – Optional list of RBAC roles assigned to the token (roles claim).

  • expires_in_secs (int) – Token lifetime in seconds from now when exp is not explicitly provided.

  • exp (int | None) – Explicit expiration epoch timestamp in seconds. Overrides expires_in_secs.

  • iat (int | None) – Optional issued-at epoch timestamp in seconds (defaults to current UTC epoch time).

  • nbf (int | None) – Optional not-before epoch timestamp in seconds.

  • issuer (str | None) – Optional issuer claim (iss).

  • audience (str | None) – Optional audience claim (aud).

  • algorithm (JwtAlgorithm | str) – HMAC algorithm (JwtAlgorithm.HS256, HS384, or HS512).

  • extra_claims (Mapping[str, Any] | None) – Optional additional custom JSON claims to include in the payload.

Returns:

Compact header.payload.signature JWT string ready for SnoozeClient(token=...).

Raises:

InvalidInputError – If the secret, subject, role, or expiration parameters are invalid.

Return type:

str

snoozeml.auth.mint_jwt_token(secret=None, *, subject='snoozeml-client', role=Role.INFERENCE, roles=None, expires_in_secs=3600, exp=None, iat=None, nbf=None, issuer=None, audience=None, algorithm=JwtAlgorithm.HS256, extra_claims=None)#

Mints a signed HMAC JSON Web Token (JWT) compatible with the SnoozeML daemon.

Both the shared secret and the generated JWT are automatically registered with SnoozeML’s log redaction filter so they never leak in client telemetry.

Parameters:

  • secret (str | None) – Shared HMAC secret key. If None, reads SNOOZE_JWT_SECRET from the environment.

  • subject (str) – Subject identifier claim (sub).

  • role (Role | str | None) – Primary RBAC role claim ("read_only", "inference", or "admin").

  • roles (Sequence[Role | str] | None) – Optional list of RBAC roles assigned to the token (roles claim).

  • expires_in_secs (int) – Token lifetime in seconds from now when exp is not explicitly provided.

  • exp (int | None) – Explicit expiration epoch timestamp in seconds. Overrides expires_in_secs.

  • iat (int | None) – Optional issued-at epoch timestamp in seconds (defaults to current UTC epoch time).

  • nbf (int | None) – Optional not-before epoch timestamp in seconds.

  • issuer (str | None) – Optional issuer claim (iss).

  • audience (str | None) – Optional audience claim (aud).

  • algorithm (JwtAlgorithm | str) – HMAC algorithm (JwtAlgorithm.HS256, HS384, or HS512).

  • extra_claims (Mapping[str, Any] | None) – Optional additional custom JSON claims to include in the payload.

Returns:

Compact header.payload.signature JWT string ready for SnoozeClient(token=...).

Raises:

InvalidInputError – If the secret, subject, role, or expiration parameters are invalid.

Return type:

str

snoozeml.auth.decode_jwt_token(token, secret=None, *, verify=True, algorithm=JwtAlgorithm.HS256, leeway_secs=60, issuer=None, audience=None)[source]#

Decodes and optionally verifies a SnoozeML HMAC JSON Web Token.

Parameters:

  • token (str) – Compact header.payload.signature JWT string.

  • secret (str | None) – Shared HMAC secret key (required when verify=True; falls back to SNOOZE_JWT_SECRET).

  • verify (bool) – Whether to verify the HMAC signature and temporal/issuer/audience claims.

  • algorithm (JwtAlgorithm | str) – Expected HMAC algorithm (default HS256).

  • leeway_secs (int) – Clock skew tolerance in seconds for exp and nbf checks (default 60).

  • issuer (str | None) – Expected iss claim value if issuer validation is desired.

  • audience (str | None) – Expected aud claim value if audience validation is desired.

Returns:

Decoded JWT claims dictionary.

Raises:
Return type:

Dict[str, Any]