flip_api.auth.dependencies

Attributes

security

Functions

_decode_cognito_jwt(→ dict[str, Any])	Verify a Cognito-issued access token and return its claims.
_decode_verified_claims(→ dict[str, Any])	Validate a Cognito JWT and return its verified claims.
_extract_user_id(→ uuid.UUID)	Return the sub claim as a UUID, raising 401 on failure.
_extract_username(→ str)	Return the Cognito Username claim (email in our pool) from an access token.
verify_token() → uuid.UUID)	Verify a Cognito JWT and enforce that the caller has TOTP MFA enabled.
verify_token_no_mfa() → uuid.UUID)	Verify a Cognito JWT without requiring TOTP MFA.

Module Contents

flip_api.auth.dependencies.security

flip_api.auth.dependencies._decode_cognito_jwt(token: str) → dict[str, Any]

Verify a Cognito-issued access token and return its claims.

Performs the verification steps documented by AWS for Cognito user pool tokens: signature, expiry, issuer, token_use == "access", and client_id binding to this app client. ID tokens (and any other token_use) are rejected — see issue #344 for the rationale.

Raises jwt.InvalidTokenError (or a subclass) on any validation failure.

flip_api.auth.dependencies._decode_verified_claims(token: str) → dict[str, Any]

Validate a Cognito JWT and return its verified claims.

Parameters:

token (str) – The raw bearer token.

Returns:

The decoded JWT payload.

Return type:

dict[str, Any]

Raises:

HTTPException – If token is invalid, expired, or wrong type.

flip_api.auth.dependencies._extract_user_id(payload: dict[str, Any]) → uuid.UUID

Return the sub claim as a UUID, raising 401 on failure.

flip_api.auth.dependencies._extract_username(payload: dict[str, Any]) → str

Return the Cognito Username claim (email in our pool) from an access token.

Raises:

HTTPException – If the claim is missing (401).

flip_api.auth.dependencies.verify_token(credentials: fastapi.security.HTTPAuthorizationCredentials = Depends(security)) → uuid.UUID

Verify a Cognito JWT and enforce that the caller has TOTP MFA enabled.

The MFA requirement is checked at the application boundary (rather than at the Cognito pool) so admin resets take effect immediately — see the comment on aws_cognito_user_pool.flip_user_pool in the cognito module for the full rationale. MFA-bootstrap endpoints use verify_token_no_mfa() instead.

Parameters:

credentials (HTTPAuthorizationCredentials) – Bearer credentials from the incoming request.

Returns:

The user ID (sub claim) from the verified token.

Return type:

UUID

Raises:

HTTPException – 401 if the token is invalid, expired, or missing claims; 403 if the caller has not enrolled TOTP.

flip_api.auth.dependencies.verify_token_no_mfa(credentials: fastapi.security.HTTPAuthorizationCredentials = Depends(security)) → uuid.UUID

Verify a Cognito JWT without requiring TOTP MFA.

Reserved for the MFA bootstrap endpoints (status check, enrolment helpers) that a freshly-reset or newly-invited user needs to reach before they have an active authenticator. Every other route must use verify_token().

Parameters:

credentials (HTTPAuthorizationCredentials) – Bearer credentials from the incoming request.

Returns:

The user ID (sub claim) from the verified token.

Return type:

UUID

Raises:

HTTPException – 401 if the token is invalid, expired, or missing claims.