feat: add security module

src/fastapi_toolsets/security/oauth.py

@@ -0,0 +1,24 @@
+"""OAuth 2.0 / OIDC helper utilities."""
+
+import base64
+
+
+def encode_oauth_state(url: str) -> str:
+    """Base64url-encode a URL to embed as an OAuth ``state`` parameter."""
+    return base64.urlsafe_b64encode(url.encode()).decode()
+
+
+def decode_oauth_state(state: str | None, *, fallback: str) -> str:
+    """Decode a base64url OAuth ``state`` parameter.
+
+    Handles missing padding (some providers strip ``=``).
+    Returns *fallback* if *state* is absent, the literal string ``"null"``,
+    or cannot be decoded.
+    """
+    if not state or state == "null":
+        return fallback
+    try:
+        padded = state + "=" * (4 - len(state) % 4)
+        return base64.urlsafe_b64decode(padded).decode()
+    except Exception:
+        return fallback