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

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",
+]

svc_infra/security/permissions.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any, Awaitable, Callable, Dict, Iterable, Set
+
+from fastapi import Depends, HTTPException
+
+from svc_infra.api.fastapi.auth.security import Identity
+
+# Central role -> permissions mapping. Projects can extend at startup.
+PERMISSION_REGISTRY: Dict[str, Set[str]] = {
+    "admin": {
+        "user.read",
+        "user.write",
+        "billing.read",
+        "billing.write",
+        "security.session.revoke",
+        "security.session.list",
+    },
+    "support": {"user.read", "billing.read"},
+    "auditor": {"user.read", "billing.read", "audit.read"},
+}
+
+
+def get_permissions_for_roles(roles: Iterable[str]) -> Set[str]:
+    perms: Set[str] = set()
+    for r in roles:
+        perms |= PERMISSION_REGISTRY.get(r, set())
+    return perms
+
+
+def principal_permissions(principal: Identity) -> Set[str]:
+    roles = getattr(principal.user, "roles", []) or []
+    return get_permissions_for_roles(roles)
+
+
+def has_permission(principal: Identity, permission: str) -> bool:
+    return permission in principal_permissions(principal)
+
+
+def RequirePermission(*needed: str):
+    """FastAPI dependency enforcing all listed permissions are present."""
+
+    async def _guard(principal: Identity):
+        perms = principal_permissions(principal)
+        missing = [p for p in needed if p not in perms]
+        if missing:
+            raise HTTPException(403, f"missing_permissions:{','.join(missing)}")
+        return principal
+
+    return Depends(_guard)
+
+
+def RequireAnyPermission(*candidates: str):
+    async def _guard(principal: Identity):
+        perms = principal_permissions(principal)
+        if not (perms & set(candidates)):
+            raise HTTPException(403, "insufficient_permissions")
+        return principal
+
+    return Depends(_guard)
+
+
+# ------- ABAC (Attribute-Based Access Control) helpers -------
+ABACPredicate = Callable[[Identity, Any], bool | Awaitable[bool]]
+
+
+def owns_resource(attr: str = "owner_id") -> ABACPredicate:
+    def _predicate(principal: Identity, resource: Any) -> bool:
+        user = getattr(principal, "user", None)
+        uid = getattr(user, "id", None)
+        rid = getattr(resource, attr, None) or getattr(resource, "user_id", None)
+        return bool(uid is not None and rid is not None and str(uid) == str(rid))
+
+    return _predicate
+
+
+async def _maybe_await(v):
+    if inspect.isawaitable(v):
+        return await v
+    return v
+
+
+def enforce_abac(
+    principal: Identity,
+    *,
+    permission: str,
+    resource: Any,
+    predicate: ABACPredicate,
+):
+    perms = principal_permissions(principal)
+    if permission not in perms:
+        raise HTTPException(403, f"missing_permissions:{permission}")
+    ok = False
+    # allow sync or async predicate
+    res = predicate(principal, resource)
+    if inspect.isawaitable(res):
+        # Fast path for sync contexts: raise clear guidance
+        raise RuntimeError(
+            "enforce_abac received an async predicate in a sync context; use RequireABAC for FastAPI dependencies."
+        )
+    else:
+        ok = bool(res)
+    if not ok:
+        raise HTTPException(403, "forbidden")
+    return principal
+
+
+def RequireABAC(
+    *,
+    permission: str,
+    predicate: ABACPredicate,
+    resource_getter: Callable[..., Any],
+):
+    """FastAPI dependency: enforce permission and attribute check using a resource provider.
+
+    Example:
+        def load_doc(): ...
+        @router.get("/docs/{doc_id}", dependencies=[RequireABAC(permission="doc.read", predicate=owns_resource(), resource_getter=load_doc)])
+        async def get_doc(identity: Identity, doc = Depends(load_doc)):
+            ...
+    Note: Using the provider in both the dependency and endpoint will call it twice. For heavy
+    providers, wire only in the dependency and re-fetch via the dependency override or request.state.
+    """
+
+    async def _guard(principal: Identity, resource: Any = Depends(resource_getter)):
+        perms = principal_permissions(principal)
+        if permission not in perms:
+            raise HTTPException(403, f"missing_permissions:{permission}")
+        ok = await _maybe_await(predicate(principal, resource))
+        if not ok:
+            raise HTTPException(403, "forbidden")
+        return principal
+
+    return Depends(_guard)
+
+
+__all__ = [
+    "PERMISSION_REGISTRY",
+    "get_permissions_for_roles",
+    "principal_permissions",
+    "has_permission",
+    "RequirePermission",
+    "RequireAnyPermission",
+    "RequireABAC",
+    "enforce_abac",
+    "owns_resource",
+]

svc_infra/security/session.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+try:
+    from sqlalchemy.ext.asyncio import AsyncSession
+except Exception:  # pragma: no cover
+    AsyncSession = object  # type: ignore
+
+from svc_infra.security.models import (
+    AuthSession,
+    RefreshToken,
+    RefreshTokenRevocation,
+    generate_refresh_token,
+    hash_refresh_token,
+    rotate_refresh_token,
+)
+
+DEFAULT_REFRESH_TTL_MINUTES = 60 * 24 * 7  # 7 days
+
+
+async def issue_session_and_refresh(
+    db: AsyncSession,
+    *,
+    user_id: uuid.UUID,
+    tenant_id: Optional[str] = None,
+    user_agent: Optional[str] = None,
+    ip_hash: Optional[str] = None,
+    ttl_minutes: int = DEFAULT_REFRESH_TTL_MINUTES,
+) -> tuple[str, RefreshToken]:
+    """Persist a new AuthSession + initial RefreshToken and return raw refresh token.
+
+    Returns: (raw_refresh_token, RefreshToken model instance)
+    """
+    session_row = AuthSession(
+        user_id=user_id,
+        tenant_id=tenant_id,
+        user_agent=user_agent,
+        ip_hash=ip_hash,
+    )
+    db.add(session_row)
+    raw = generate_refresh_token()
+    token_hash = hash_refresh_token(raw)
+    expires_at = datetime.now(timezone.utc) + timedelta(minutes=ttl_minutes)
+    rt = RefreshToken(
+        session=session_row,
+        token_hash=token_hash,
+        expires_at=expires_at,
+    )
+    db.add(rt)
+    await db.flush()
+    return raw, rt
+
+
+async def rotate_session_refresh(
+    db: AsyncSession,
+    *,
+    current: RefreshToken,
+    ttl_minutes: int = DEFAULT_REFRESH_TTL_MINUTES,
+) -> tuple[str, RefreshToken]:
+    """Rotate a session's refresh token: mark current rotated, create new, add revocation record.
+
+    Returns: (new_raw_refresh_token, new_refresh_token_model)
+    """
+    rotation_ts = datetime.now(timezone.utc)
+    if current.revoked_at:
+        raise ValueError("refresh token already revoked")
+    if current.expires_at and current.expires_at <= rotation_ts:
+        raise ValueError("refresh token expired")
+    new_raw, new_hash, expires_at = rotate_refresh_token(
+        current.token_hash, ttl_minutes=ttl_minutes
+    )
+    current.rotated_at = rotation_ts
+    current.revoked_at = rotation_ts
+    current.revoke_reason = "rotated"
+    if current.expires_at is None or current.expires_at > rotation_ts:
+        current.expires_at = rotation_ts
+    # create revocation entry for old hash
+    db.add(
+        RefreshTokenRevocation(
+            token_hash=current.token_hash,
+            revoked_at=rotation_ts,
+            reason="rotated",
+        )
+    )
+    new_row = RefreshToken(
+        session=current.session,
+        token_hash=new_hash,
+        expires_at=expires_at,
+    )
+    db.add(new_row)
+    await db.flush()
+    return new_raw, new_row
+
+
+__all__ = ["issue_session_and_refresh", "rotate_session_refresh"]