svc-infra 0.1.593__py3-none-any.whl → 0.1.594__py3-none-any.whl

svc_infra/security/hibp.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import hashlib
+import time
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+import httpx
+
+
+def sha1_hex(data: str) -> str:
+    return hashlib.sha1(data.encode("utf-8")).hexdigest().upper()
+
+
+@dataclass
+class CacheEntry:
+    body: str
+    expires_at: float
+
+
+class HIBPClient:
+    """Minimal HaveIBeenPwned range API client with simple in-memory cache.
+
+    - Uses k-anonymity range query: send first 5 chars of SHA1 hash, receive suffix list.
+    - Caches prefix responses for TTL to avoid repeated network calls.
+    - Synchronous implementation to allow use in sync validators.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "https://api.pwnedpasswords.com",
+        ttl_seconds: int = 3600,
+        timeout: float = 5.0,
+        user_agent: str = "svc-infra/hibp",
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.ttl_seconds = ttl_seconds
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self._cache: Dict[str, CacheEntry] = {}
+        self._http = httpx.Client(timeout=self.timeout, headers={"User-Agent": self.user_agent})
+
+    def _get_cached(self, prefix: str) -> Optional[str]:
+        now = time.time()
+        ent = self._cache.get(prefix)
+        if ent and ent.expires_at > now:
+            return ent.body
+        return None
+
+    def _set_cache(self, prefix: str, body: str) -> None:
+        self._cache[prefix] = CacheEntry(body=body, expires_at=time.time() + self.ttl_seconds)
+
+    def range_query(self, prefix: str) -> str:
+        cached = self._get_cached(prefix)
+        if cached is not None:
+            return cached
+        url = f"{self.base_url}/range/{prefix}"
+        resp = self._http.get(url)
+        resp.raise_for_status()
+        body = resp.text
+        self._set_cache(prefix, body)
+        return body
+
+    def is_breached(self, password: str) -> bool:
+        full = sha1_hex(password)
+        prefix, suffix = full[:5], full[5:]
+        try:
+            body = self.range_query(prefix)
+        except Exception:
+            # Fail-open: if HIBP unavailable, do not block users.
+            return False
+
+        for line in body.splitlines():
+            # Lines formatted as "SUFFIX:COUNT"
+            if not line:
+                continue
+            parts = line.split(":")
+            if len(parts) != 2:
+                continue
+            sfx = parts[0].strip().upper()
+            if sfx == suffix:
+                # Count > 0 implies breached
+                try:
+                    return int(parts[1].strip()) > 0
+                except ValueError:
+                    return True
+        return False
+
+
+__all__ = ["HIBPClient", "sha1_hex"]

svc_infra/security/jwt_rotation.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Iterable, List, Optional, Union
+
+import jwt as pyjwt
+from fastapi_users.authentication.strategy.jwt import JWTStrategy
+
+
+class RotatingJWTStrategy(JWTStrategy):
+    """JWTStrategy that can verify tokens against multiple secrets.
+
+    Signing uses the primary secret (as in base class). Verification accepts any of
+    the provided secrets: [primary] + old_secrets.
+    """
+
+    def __init__(
+        self,
+        *,
+        secret: str,
+        lifetime_seconds: int,
+        old_secrets: Optional[Iterable[str]] = None,
+        token_audience: Optional[Union[str, List[str]]] = None,
+    ):
+        super().__init__(
+            secret=secret, lifetime_seconds=lifetime_seconds, token_audience=token_audience
+        )
+        self._verify_secrets: List[str] = [secret] + list(old_secrets or [])
+
+    async def read_token(self, token: str, audience: Optional[str] = None):  # type: ignore[override]
+        # Try with current strategy's configured secret first
+        eff_aud = audience or self.token_audience
+        try:
+            return await super().read_token(token, audience=eff_aud)
+        except Exception:
+            pass
+        # Try older secrets
+        for s in self._verify_secrets[1:]:
+            try:
+                data = pyjwt.decode(
+                    token,
+                    s,
+                    algorithms=["HS256"],
+                    audience=eff_aud,
+                )
+                if data is not None:
+                    return data
+            except Exception:
+                pass
+        # If none of the secrets validated the token, raise a generic error
+        raise ValueError("Invalid token for all configured secrets")
+
+
+__all__ = ["RotatingJWTStrategy"]

svc_infra/security/lockout.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional, Sequence
+
+try:
+    from sqlalchemy import select
+    from sqlalchemy.ext.asyncio import AsyncSession
+except Exception:  # pragma: no cover - optional import for type hints
+    AsyncSession = Any  # type: ignore[misc]
+    select = None  # type: ignore
+
+from svc_infra.security.models import FailedAuthAttempt
+
+
+@dataclass
+class LockoutConfig:
+    threshold: int = 5  # failures before cooldown starts
+    window_minutes: int = 15  # look-back window for counting failures
+    base_cooldown_seconds: int = 30  # initial cooldown once threshold reached
+    max_cooldown_seconds: int = 3600  # cap exponential growth at 1 hour
+
+
+@dataclass
+class LockoutStatus:
+    locked: bool
+    next_allowed_at: Optional[datetime]
+    failure_count: int
+
+
+# ---------------- Pure calculation -----------------
+
+
+def compute_lockout(
+    fail_count: int, *, cfg: LockoutConfig, now: Optional[datetime] = None
+) -> LockoutStatus:
+    now = now or datetime.now(timezone.utc)
+    if fail_count < cfg.threshold:
+        return LockoutStatus(False, None, fail_count)
+    # cooldown factor exponent = fail_count - threshold
+    exponent = fail_count - cfg.threshold
+    cooldown = cfg.base_cooldown_seconds * (2**exponent)
+    if cooldown > cfg.max_cooldown_seconds:
+        cooldown = cfg.max_cooldown_seconds
+    return LockoutStatus(True, now + timedelta(seconds=cooldown), fail_count)
+
+
+# ---------------- Persistence helpers (async) ---------------
+
+
+async def record_attempt(
+    session: AsyncSession,
+    *,
+    user_id: Optional[uuid.UUID],
+    ip_hash: Optional[str],
+    success: bool,
+) -> None:
+    attempt = FailedAuthAttempt(user_id=user_id, ip_hash=ip_hash, success=success)
+    session.add(attempt)
+    await session.flush()
+
+
+async def get_lockout_status(
+    session: AsyncSession,
+    *,
+    user_id: Optional[uuid.UUID],
+    ip_hash: Optional[str],
+    cfg: Optional[LockoutConfig] = None,
+) -> LockoutStatus:
+    cfg = cfg or LockoutConfig()
+    now = datetime.now(timezone.utc)
+    window_start = now - timedelta(minutes=cfg.window_minutes)
+
+    q = select(FailedAuthAttempt).where(
+        FailedAuthAttempt.ts >= window_start,
+        FailedAuthAttempt.success == False,  # noqa: E712
+    )
+    if user_id:
+        q = q.where(FailedAuthAttempt.user_id == user_id)
+    if ip_hash:
+        q = q.where(FailedAuthAttempt.ip_hash == ip_hash)
+
+    rows: Sequence[FailedAuthAttempt] = (await session.execute(q)).scalars().all()
+    fail_count = len(rows)
+    return compute_lockout(fail_count, cfg=cfg, now=now)
+
+
+__all__ = [
+    "LockoutConfig",
+    "LockoutStatus",
+    "compute_lockout",
+    "record_attempt",
+    "get_lockout_status",
+]

svc_infra/security/models.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, Index, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from svc_infra.db.sql.base import ModelBase
+from svc_infra.db.sql.types import GUID
+
+# ----------------------------- Models -----------------------------------------
+
+
+class AuthSession(ModelBase):
+    __tablename__ = "auth_sessions"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("users.id", ondelete="CASCADE"), index=True
+    )
+    tenant_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    user_agent: Mapped[Optional[str]] = mapped_column(String(512))
+    ip_hash: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    last_seen_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    revoke_reason: Mapped[Optional[str]] = mapped_column(Text)
+
+    refresh_tokens: Mapped[list["RefreshToken"]] = relationship(
+        back_populates="session", cascade="all, delete-orphan", lazy="selectin"
+    )
+
+    created_at = mapped_column(
+        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+    )
+
+
+class RefreshToken(ModelBase):
+    __tablename__ = "refresh_tokens"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    session_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("auth_sessions.id", ondelete="CASCADE"), index=True
+    )
+    session: Mapped[AuthSession] = relationship(back_populates="refresh_tokens")
+
+    token_hash: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    rotated_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    revoke_reason: Mapped[Optional[str]] = mapped_column(Text)
+    expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), index=True)
+
+    created_at = mapped_column(
+        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+    )
+
+    __table_args__ = (UniqueConstraint("token_hash", name="uq_refresh_token_hash"),)
+
+
+class RefreshTokenRevocation(ModelBase):
+    __tablename__ = "refresh_token_revocations"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    token_hash: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    revoked_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    reason: Mapped[Optional[str]] = mapped_column(Text)
+
+
+class FailedAuthAttempt(ModelBase):
+    __tablename__ = "failed_auth_attempts"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        GUID(), ForeignKey("users.id", ondelete="CASCADE"), index=True, nullable=True
+    )
+    ip_hash: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    ts: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=lambda: datetime.now(timezone.utc)
+    )
+    success: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+
+    __table_args__ = (Index("ix_failed_attempt_user_time", "user_id", "ts"),)
+
+
+class RolePermission(ModelBase):
+    __tablename__ = "role_permissions"
+
+    role: Mapped[str] = mapped_column(String(64), primary_key=True)
+    permission: Mapped[str] = mapped_column(String(128), primary_key=True)
+
+
+class AuditLog(ModelBase):
+    __tablename__ = "audit_logs"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    ts: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        index=True,
+    )
+    actor_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        GUID(), ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    tenant_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    event_type: Mapped[str] = mapped_column(String(128), nullable=False, index=True)
+    resource_ref: Mapped[Optional[str]] = mapped_column(String(255), index=True)
+    event_metadata: Mapped[dict] = mapped_column("metadata", JSON, default=dict)
+    prev_hash: Mapped[Optional[str]] = mapped_column(String(64))
+    hash: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+
+    __table_args__ = (Index("ix_audit_chain", "tenant_id", "id"),)
+
+
+# ------------------------ Org / Teams ----------------------------------------
+
+
+class Organization(ModelBase):
+    __tablename__ = "organizations"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    slug: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    tenant_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    created_at = mapped_column(
+        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+    )
+
+
+class Team(ModelBase):
+    __tablename__ = "teams"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    org_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("organizations.id", ondelete="CASCADE"), index=True
+    )
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    created_at = mapped_column(
+        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+    )
+
+
+class OrganizationMembership(ModelBase):
+    __tablename__ = "organization_memberships"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    org_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("organizations.id", ondelete="CASCADE"), index=True
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("users.id", ondelete="CASCADE"), index=True
+    )
+    role: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    created_at = mapped_column(
+        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+    )
+    deactivated_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+
+    __table_args__ = (UniqueConstraint("org_id", "user_id", name="uq_org_user_membership"),)
+
+
+class OrganizationInvitation(ModelBase):
+    __tablename__ = "organization_invitations"
+
+    id: Mapped[uuid.UUID] = mapped_column(GUID(), primary_key=True, default=uuid.uuid4)
+    org_id: Mapped[uuid.UUID] = mapped_column(
+        GUID(), ForeignKey("organizations.id", ondelete="CASCADE"), index=True
+    )
+    email: Mapped[str] = mapped_column(String(255), index=True)
+    role: Mapped[str] = mapped_column(String(64), nullable=False)
+    token_hash: Mapped[str] = mapped_column(String(64), index=True)
+    expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), index=True)
+    created_by: Mapped[Optional[uuid.UUID]] = mapped_column(
+        GUID(), ForeignKey("users.id", ondelete="SET NULL"), index=True
+    )
+    created_at = mapped_column(
+        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+    )
+    last_sent_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    resend_count: Mapped[int] = mapped_column(default=0)
+    used_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+
+
+# ------------------------ Utilities -------------------------------------------
+
+
+def generate_refresh_token() -> str:
+    """Generate a random refresh token (opaque)."""
+    return uuid.uuid4().hex + uuid.uuid4().hex  # 64 hex chars
+
+
+def hash_refresh_token(raw: str) -> str:
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+def compute_audit_hash(
+    prev_hash: Optional[str],
+    *,
+    ts: datetime,
+    actor_id: Optional[uuid.UUID],
+    tenant_id: Optional[str],
+    event_type: str,
+    resource_ref: Optional[str],
+    metadata: dict,
+) -> str:
+    """Compute SHA256 hash chaining previous hash + canonical event payload."""
+    prev = prev_hash or "0" * 64
+    payload = {
+        "ts": ts.isoformat(),
+        "actor_id": str(actor_id) if actor_id else None,
+        "tenant_id": tenant_id,
+        "event_type": event_type,
+        "resource_ref": resource_ref,
+        "metadata": metadata,
+    }
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256((prev + canonical).encode()).hexdigest()
+
+
+def rotate_refresh_token(
+    current_hash: str, *, ttl_minutes: int = 10080
+) -> tuple[str, str, datetime]:
+    """Rotate: returns (new_raw, new_hash, expires_at)."""
+    new_raw = generate_refresh_token()
+    new_hash = hash_refresh_token(new_raw)
+    expires_at = datetime.now(timezone.utc) + timedelta(minutes=ttl_minutes)
+    return new_raw, new_hash, expires_at
+
+
+__all__ = [
+    "AuthSession",
+    "RefreshToken",
+    "RefreshTokenRevocation",
+    "FailedAuthAttempt",
+    "RolePermission",
+    "AuditLog",
+    "generate_refresh_token",
+    "hash_refresh_token",
+    "compute_audit_hash",
+    "rotate_refresh_token",
+]

svc_infra/security/org_invites.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import hashlib
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+
+try:
+    from sqlalchemy import select
+    from sqlalchemy.ext.asyncio import AsyncSession
+except Exception:  # pragma: no cover
+    AsyncSession = object  # type: ignore
+    select = None  # type: ignore
+
+from .models import OrganizationInvitation, OrganizationMembership
+
+
+def _hash_token(raw: str) -> str:
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+def _new_token() -> str:
+    return uuid.uuid4().hex + uuid.uuid4().hex
+
+
+async def issue_invitation(
+    db: Any,
+    *,
+    org_id: uuid.UUID,
+    email: str,
+    role: str,
+    created_by: Optional[uuid.UUID] = None,
+    ttl_hours: int = 72,
+) -> tuple[str, OrganizationInvitation]:
+    """Create a new invitation; revoke any existing active invites for the same email+org."""
+    # Revoke existing active invites
+    if select is not None and hasattr(db, "execute"):
+        try:
+            rows = (
+                (
+                    await db.execute(
+                        select(OrganizationInvitation).where(
+                            OrganizationInvitation.org_id == org_id,
+                            OrganizationInvitation.email == email,
+                            OrganizationInvitation.used_at.is_(None),
+                            OrganizationInvitation.revoked_at.is_(None),
+                        )
+                    )
+                )
+                .scalars()
+                .all()
+            )
+            now = datetime.now(timezone.utc)
+            for r in rows:
+                r.revoked_at = now
+        except Exception:  # pragma: no cover
+            pass
+    else:
+        # FakeDB path: revoke in-memory invites
+        if hasattr(db, "added"):
+            now = datetime.now(timezone.utc)
+            for r in list(getattr(db, "added")):
+                if (
+                    isinstance(r, OrganizationInvitation)
+                    and r.org_id == org_id
+                    and r.email == email.lower().strip()
+                    and r.used_at is None
+                    and r.revoked_at is None
+                ):
+                    r.revoked_at = now
+
+    raw = _new_token()
+    inv = OrganizationInvitation(
+        org_id=org_id,
+        email=email.lower().strip(),
+        role=role,
+        token_hash=_hash_token(raw),
+        expires_at=datetime.now(timezone.utc) + timedelta(hours=ttl_hours),
+        created_by=created_by,
+        last_sent_at=datetime.now(timezone.utc),
+        resend_count=0,
+    )
+    if hasattr(db, "add"):
+        db.add(inv)
+        if hasattr(db, "flush"):
+            await db.flush()
+    return raw, inv
+
+
+async def resend_invitation(db: Any, *, invitation: OrganizationInvitation) -> str:
+    raw = _new_token()
+    invitation.token_hash = _hash_token(raw)
+    invitation.last_sent_at = datetime.now(timezone.utc)
+    invitation.resend_count = (invitation.resend_count or 0) + 1
+    if hasattr(db, "flush"):
+        await db.flush()
+    return raw
+
+
+async def accept_invitation(
+    db: Any,
+    *,
+    invitation: OrganizationInvitation,
+    user_id: uuid.UUID,
+) -> OrganizationMembership:
+    now = datetime.now(timezone.utc)
+    if invitation.revoked_at or invitation.used_at:
+        raise ValueError("invitation_unusable")
+    if invitation.expires_at and invitation.expires_at < now:
+        raise ValueError("invitation_expired")
+
+    # mark used
+    invitation.used_at = now
+
+    # create membership (upsert-like enforced by DB unique constraint)
+    mem = OrganizationMembership(org_id=invitation.org_id, user_id=user_id, role=invitation.role)
+    if hasattr(db, "add"):
+        db.add(mem)
+        if hasattr(db, "flush"):
+            await db.flush()
+    return mem
+
+
+__all__ = [
+    "issue_invitation",
+    "resend_invitation",
+    "accept_invitation",
+]

svc_infra/security/passwords.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Callable, Iterable, Optional
+
+COMMON_PASSWORDS = {"password", "123456", "qwerty", "letmein", "admin"}
+
+HIBP_DISABLED = False  # default enabled; can be toggled via settings at startup
+
+
+@dataclass
+class PasswordPolicy:
+    min_length: int = 12
+    require_upper: bool = True
+    require_lower: bool = True
+    require_digit: bool = True
+    require_symbol: bool = True
+    forbid_common: bool = True
+    forbid_breached: bool = True  # will toggle off if HIBP integration not configured
+    symbols_regex: str = r"[!@#$%^&*()_+=\-{}\[\]:;,.?/]"
+
+
+class PasswordValidationError(Exception):
+    def __init__(self, reasons: Iterable[str]):
+        super().__init__("Password validation failed")
+        self.reasons = list(reasons)
+
+
+UPPER = re.compile(r"[A-Z]")
+LOWER = re.compile(r"[a-z]")
+DIGIT = re.compile(r"[0-9]")
+SYMBOL = re.compile(r"[!@#$%^&*()_+=\-{}\[\]:;,.?/]")
+
+
+BreachedChecker = Callable[[str], bool]
+
+
+_breached_checker: Optional[BreachedChecker] = None
+
+
+def configure_breached_checker(checker: Optional[BreachedChecker]) -> None:
+    global _breached_checker
+    _breached_checker = checker
+
+
+def validate_password(pw: str, policy: PasswordPolicy | None = None) -> None:
+    policy = policy or PasswordPolicy()
+    reasons: list[str] = []
+    if len(pw) < policy.min_length:
+        reasons.append(f"min_length({policy.min_length})")
+    if policy.require_upper and not UPPER.search(pw):
+        reasons.append("missing_upper")
+    if policy.require_lower and not LOWER.search(pw):
+        reasons.append("missing_lower")
+    if policy.require_digit and not DIGIT.search(pw):
+        reasons.append("missing_digit")
+    if policy.require_symbol and not SYMBOL.search(pw):
+        reasons.append("missing_symbol")
+    if policy.forbid_common:
+        lowered = pw.lower()
+        # Reject if whole password matches a common one or contains it as a substring
+        if lowered in COMMON_PASSWORDS or any(term in lowered for term in COMMON_PASSWORDS):
+            reasons.append("common_password")
+    if policy.forbid_breached and not HIBP_DISABLED:
+        if _breached_checker and _breached_checker(pw):
+            reasons.append("breached_password")
+    if reasons:
+        raise PasswordValidationError(reasons)
+
+
+__all__ = [
+    "PasswordPolicy",
+    "validate_password",
+    "PasswordValidationError",
+    "configure_breached_checker",
+]