svc-infra 0.1.589__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/security/jwt_rotation.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import Any, Iterable, List, Optional, Union
+
+import jwt
+from fastapi_users.authentication.strategy.jwt import JWTStrategy
+from fastapi_users.jwt import decode_jwt
+
+
+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,
+    ):
+        # Normalize token_audience to list as required by parent JWTStrategy
+        aud_list: list[str] = (
+            [token_audience]
+            if isinstance(token_audience, str)
+            else list(token_audience)
+            if token_audience
+            else []
+        ) or ["fastapi-users:auth"]
+        super().__init__(
+            secret=secret, lifetime_seconds=lifetime_seconds, token_audience=aud_list
+        )
+        self._verify_secrets: List[str] = [secret] + list(old_secrets or [])
+        self._lifetime_seconds = lifetime_seconds
+
+    async def read_token(
+        self,
+        token: str | None,
+        user_manager: Any = None,
+        *,
+        audience: str | list[str] | None = None,
+    ) -> Any:
+        """Read/verify a token against the active + rotated secrets.
+
+        Compatibility:
+        - fastapi-users signature: (token, user_manager) -> user | None
+        - legacy/test helper usage: (token, *, audience=...) -> claims | None
+        """
+
+        if token is None:
+            return None
+
+        if user_manager is None:
+            aud_list: list[str]
+            if audience is None:
+                aud_list = self.token_audience
+            elif isinstance(audience, str):
+                aud_list = [audience]
+            else:
+                aud_list = audience
+            try:
+                return decode_jwt(
+                    token, self.decode_key, aud_list, algorithms=[self.algorithm]
+                )
+            except jwt.PyJWTError:
+                pass
+
+            for secret in self._verify_secrets[1:]:
+                candidate: JWTStrategy[Any, Any] = JWTStrategy(
+                    secret=secret,
+                    lifetime_seconds=self._lifetime_seconds,
+                    token_audience=self.token_audience,
+                )
+                try:
+                    return decode_jwt(
+                        token,
+                        candidate.decode_key,
+                        aud_list,
+                        algorithms=[candidate.algorithm],
+                    )
+                except jwt.PyJWTError:
+                    continue
+            raise ValueError("Invalid token for all configured secrets")
+
+        user = await super().read_token(token, user_manager)
+        if user is not None:
+            return user
+
+        for secret in self._verify_secrets[1:]:
+            candidate = JWTStrategy(
+                secret=secret,
+                lifetime_seconds=self._lifetime_seconds,
+                token_audience=self.token_audience,
+            )
+            user = await candidate.read_token(token, user_manager)
+            if user is not None:
+                return user
+
+        return None
+
+
+__all__ = ["RotatingJWTStrategy"]

svc_infra/security/lockout.py

@@ -0,0 +1,102 @@
+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 or_, select
+    from sqlalchemy.ext.asyncio import AsyncSession
+except Exception:  # pragma: no cover - optional import for type hints
+    AsyncSession = Any  # type: ignore[misc,assignment]
+    select = None  # type: ignore[assignment]
+    or_ = None  # type: ignore[assignment]
+
+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
+    )
+    # Use OR logic: lock out if EITHER user_id OR ip_hash has too many failures
+    # This prevents attackers from rotating IPs to bypass lockout
+    filters = []
+    if user_id:
+        filters.append(FailedAuthAttempt.user_id == user_id)
+    if ip_hash:
+        filters.append(FailedAuthAttempt.ip_hash == ip_hash)
+    if filters:
+        q = q.where(or_(*filters))
+
+    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,287 @@
+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,
+    text,
+)
+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=text("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=text("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=text("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=text("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=text("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=text("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))
+
+
+# ------------------------ OAuth Provider Accounts -----------------------------
+# MOVED to svc_infra.security.oauth_models for opt-in OAuth support
+# Projects that enable OAuth should import ProviderAccount from there
+
+
+# ------------------------ 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",
+    "Organization",
+    "Team",
+    "OrganizationMembership",
+    "OrganizationInvitation",
+    # ProviderAccount moved to svc_infra.security.oauth_models (opt-in)
+    "generate_refresh_token",
+    "hash_refresh_token",
+    "compute_audit_hash",
+    "rotate_refresh_token",
+]

svc_infra/security/oauth_models.py

@@ -0,0 +1,73 @@
+"""
+OAuth provider account models (opt-in).
+
+These models are only registered when a project explicitly enables OAuth.
+Import this module only when enable_oauth=True is passed to add_auth_users.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional
+
+from sqlalchemy import (
+    JSON,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    UniqueConstraint,
+    text,
+)
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from svc_infra.db.sql.base import ModelBase
+from svc_infra.db.sql.types import GUID
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    # User model is application-specific; this is a forward reference for type hints
+    User = Any
+
+
+class ProviderAccount(ModelBase):
+    """OAuth provider account linking (Google, GitHub, etc.)."""
+
+    __tablename__ = "provider_accounts"
+
+    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, nullable=False
+    )
+    provider: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    provider_account_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    access_token: Mapped[Optional[str]] = mapped_column(Text)
+    refresh_token: Mapped[Optional[str]] = mapped_column(Text)
+    expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    raw_claims: Mapped[Optional[dict]] = mapped_column(JSON)
+
+    # Bidirectional relationship to User model
+    user: Mapped["User"] = relationship(back_populates="provider_accounts")
+
+    created_at = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        nullable=False,
+    )
+    updated_at = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("CURRENT_TIMESTAMP"),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        UniqueConstraint("provider", "provider_account_id", name="uq_provider_account"),
+        Index("ix_provider_accounts_user_provider", "user_id", "provider"),
+    )
+
+
+__all__ = ["ProviderAccount"]

svc_infra/security/org_invites.py

@@ -0,0 +1,130 @@
+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[misc,assignment]
+    select = None  # type: ignore[assignment]
+
+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",
+]