Stage 194: multi-user tenants (invite flow)

delivery/emails/__init__.py

@@ -16,6 +16,7 @@ the engine into email-shape coupling.
 """
 from .renderer import (
     render_daily_digest,
+    render_invitation,
     render_trial_expiring,
     render_welcome,
     render_weekly_executive,
@@ -23,6 +24,7 @@ from .renderer import (
 
 __all__ = [
     "render_daily_digest",
+    "render_invitation",
     "render_trial_expiring",
     "render_welcome",
     "render_weekly_executive",

delivery/emails/renderer.py

@@ -108,6 +108,41 @@ def _shell(*, title: str, tenant_name: str, body_html: str,
 
 # --- A. Welcome ---------------------------------------------------------
 
+def render_invitation(*, tenant_name: str,
+                          invite_link: str,
+                          role: str = "operator",
+                          ttl_days: int = 7) -> str:
+    """Stage 194 — invite-to-tenant email. Single CTA to the accept
+    page; secondary text shows the raw URL for the rare email
+    client that strips button links."""
+    body = (
+        '<tr><td style="padding:22px 32px 0">'
+        f'<div style="font-size:22px;font-weight:700">'
+        f'הוזמנת ל‑{_e(tenant_name)} ב‑OrgState</div>'
+        f'<p style="font-size:15px;line-height:1.6;color:#566073;'
+        f'margin:12px 0 0">הוזמנת להצטרף לארגון '
+        f'<b>{_e(tenant_name)}</b> ב‑OrgState בתפקיד '
+        f'<b>{_e(role)}</b>. לחץ על הקישור למטה כדי לקבל מפתח גישה '
+        f'ולהיכנס. הקישור תקף ל‑{_e(ttl_days)} ימים.</p></td></tr>'
+        f'<tr><td style="padding:22px 32px 0">'
+        f'<a href="{_e(invite_link)}" style="display:inline-block;'
+        f'background:#C97860;color:#fff;text-decoration:none;'
+        f'font-weight:600;font-size:15px;padding:12px 26px;'
+        f'border-radius:8px">קבל גישה</a></td></tr>'
+        f'<tr><td style="padding:18px 32px 0;font-size:13px;'
+        f'color:#6E7A82;line-height:1.6">או העתק את הקישור: '
+        f'<span style="font-family:monospace" dir="ltr">'
+        f'{_e(invite_link)}</span></td></tr>'
+    )
+    pre_footer = (
+        "אם לא ציפית להזמנה הזו, אפשר להתעלם — הקישור יפוג מעצמו."
+    )
+    return _shell(title=f"OrgState — הזמנה ל‑{tenant_name}",
+                   tenant_name=tenant_name,
+                   body_html=body,
+                   footer_pre_html=pre_footer)
+
+
 def render_welcome(*, tenant_name: str,
                     connect_cta_url: str = "#") -> str:
     """Sent right after tenant creation. One-CTA email pushing the

infra/api/app.py

@@ -2520,6 +2520,156 @@ def create_app(db_path: Optional[str] = None,
         )
         return Response(status_code=204)
 
+    # --- Stage 194: tenant invitations ---------------------------------
+    # An admin invites a coworker by email. The invitee follows a
+    # one-shot link, picks a display name, and the backend hands
+    # them an API key bound to their name + the invited role.
+    # The flow uses the Stage 185/191 email infra to deliver the link.
+
+    def _invite_link(token: str) -> str:
+        """Construct the accept URL. The frontend renders
+        /invite/<token> which posts to /invitations/accept."""
+        base = (os.environ.get("ORGSTATE_DASHBOARD_URL", "").strip()
+                or "https://orgstate.1bigfam.com")
+        base = base.rstrip("/")
+        return f"{base}/invite/{token}"
+
+    @app.post("/tenants/{tenant_id}/invitations",
+                tags=["invitations"], status_code=201)
+    async def create_invitation_route(
+        tenant_id: str,
+        body: dict,
+        authorization: Optional[str] = Header(default=None),
+    ):
+        import os as _os
+        from delivery.emails import render_invitation
+        from infra.email_transport import EmailSendError
+        key = require_tenant_or_admin(svc, authorization, tenant_id)
+        if key is not None:
+            require_role(key, ROLE_ADMIN)
+        email = body.get("email")
+        role = body.get("role", "operator")
+        if not isinstance(email, str) or not email:
+            raise ApiError("bad_request",
+                             "body must include 'email' (string)",
+                             status=400)
+        try:
+            invite = svc.invite_user(
+                tenant_id, email, role=role,
+                invited_by=_tenant_or_admin_actor(authorization, tenant_id),
+                actor=_tenant_or_admin_actor(authorization, tenant_id),
+            )
+        except ValueError as e:
+            raise ApiError("bad_request", str(e), status=400) from e
+
+        # Attempt to send the invite email. Failure does NOT roll back
+        # the invitation — the admin can copy the URL manually.
+        # `email_sent` flags the outcome so the dashboard can show
+        # the right message.
+        link = _invite_link(invite["raw_token"])
+        t = svc.get_tenant(tenant_id)
+        tenant_name = t["name"] if t else tenant_id
+        html = render_invitation(
+            tenant_name=tenant_name,
+            invite_link=link,
+            role=invite["role"],
+        )
+        email_sent = False
+        email_error = None
+        try:
+            svc.send_tenant_email(
+                tenant_id, to=email,
+                subject=f"הזמנה ל‑{tenant_name} ב‑OrgState",
+                html=html, template="invitation",
+                actor=_tenant_or_admin_actor(authorization, tenant_id),
+            )
+            email_sent = True
+        except EmailSendError as e:
+            email_error = str(e)
+        # Strip the raw token from the returned row — the email path
+        # already received it. The accept URL is the only way to use
+        # the token; we don't echo it back via the API response so an
+        # admin watching network logs doesn't accidentally see it
+        # twice.
+        result = {k: v for k, v in invite.items()
+                  if k not in ("token_hash", "raw_token")}
+        result["email_sent"] = email_sent
+        if email_error:
+            result["email_error"] = email_error
+            result["accept_url"] = link  # let the admin copy manually
+        return result
+
+    @app.get("/tenants/{tenant_id}/invitations",
+              tags=["invitations"])
+    async def list_invitations_route(
+        tenant_id: str,
+        authorization: Optional[str] = Header(default=None),
+    ):
+        key = require_tenant_or_admin(svc, authorization, tenant_id)
+        if key is not None:
+            require_role(key, ROLE_ADMIN)
+        rows = svc.list_pending_invitations(tenant_id)
+        # Don't leak token_hash to the dashboard.
+        return {
+            "invitations": [
+                {k: v for k, v in r.items() if k != "token_hash"}
+                for r in rows
+            ],
+        }
+
+    @app.delete("/tenants/{tenant_id}/invitations/{invite_id}",
+                  tags=["invitations"], status_code=204)
+    async def revoke_invitation_route(
+        tenant_id: str,
+        invite_id: str,
+        authorization: Optional[str] = Header(default=None),
+    ):
+        key = require_tenant_or_admin(svc, authorization, tenant_id)
+        if key is not None:
+            require_role(key, ROLE_ADMIN)
+        try:
+            out = svc.revoke_invitation(
+                invite_id,
+                actor=_tenant_or_admin_actor(authorization, tenant_id),
+            )
+        except ValueError as e:
+            raise ApiError("bad_request", str(e), status=400) from e
+        if out is None:
+            raise ApiError("not_found",
+                             f"invitation {invite_id!r} not found",
+                             status=404)
+        return Response(status_code=204)
+
+    @app.post("/invitations/accept", tags=["invitations"])
+    async def accept_invitation_route(body: dict):
+        """Public — no auth header required. The token is the
+        credential. Returns the minted API key + tenant + role.
+        Same one-shot semantics as api_key creation: raw key is
+        returned ONCE."""
+        token = body.get("token")
+        display_name = body.get("display_name", "")
+        if not isinstance(token, str) or not token:
+            raise ApiError("bad_request",
+                             "body must include 'token' (string)",
+                             status=400)
+        if (not isinstance(display_name, str)
+                or not display_name.strip()):
+            raise ApiError("bad_request",
+                             "body must include 'display_name' (string)",
+                             status=400)
+        try:
+            return svc.accept_invitation(
+                token, display_name=display_name)
+        except ValueError as e:
+            msg = str(e).lower()
+            status = (404 if "not found" in msg
+                      else 410 if ("expired" in msg
+                                    or "revoked" in msg
+                                    or "already accepted" in msg)
+                      else 400)
+            raise ApiError("bad_request", str(e),
+                             status=status) from e
+
     @app.post("/tenants/{tenant_id}/api_keys", tags=["api_keys"], status_code=201)
     async def mint_api_key(
         tenant_id: str,

infra/service.py

@@ -53,6 +53,7 @@ from .storage import (
     RunRepository,
     ScimGroupRepository,
     ScimUserRepository,
+    TenantInvitationRepository,
     TenantOverridesRepository,
     TenantPlanOverrideRepository,
     TenantQuotaRepository,
@@ -160,6 +161,7 @@ class OrgStateService:
         self.invoices = InvoiceRepository(self.db)         # Stage 92
         self.scim_users = ScimUserRepository(self.db)      # Stage 103
         self.scim_groups = ScimGroupRepository(self.db)    # Stage 108
+        self.invitations = TenantInvitationRepository(self.db)  # Stage 194
         self.tenant_plan_overrides = TenantPlanOverrideRepository(
             self.db,
         )                                                    # Stage 109
@@ -1328,6 +1330,163 @@ class OrgStateService:
             )
         return ok
 
+    # --- Stage 194 — tenant invitations ---------------------------------
+
+    _VALID_INVITE_ROLES = ("readonly", "operator", "admin")
+    _INVITATION_TTL_DAYS = 7
+
+    @staticmethod
+    def _hash_token(token: str) -> str:
+        import hashlib
+        return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+    def invite_user(self, tenant_id: str, email: str, *,
+                          role: str = "operator",
+                          invited_by: str = "operator",
+                          actor: str = "operator") -> dict:
+        """Stage 194 — create an invitation for ``email`` to join the
+        tenant with the given role. Returns the row + a ``raw_token``
+        field that the caller (API route) hands to the email send
+        flow. The raw token is NEVER persisted; only sha256(token)
+        sits in the row. A future revoke / expire / accept can re-
+        identify the row via get_by_token(sha256(presented_token)).
+
+        Roles: readonly / operator / admin. Default operator —
+        the most common "give a coworker access to triage" tier.
+
+        TTL: 7 days. Re-invite to refresh. After accept/revoke the
+        row is retained for audit but excluded from list_pending.
+        """
+        from datetime import datetime as _dt
+        from datetime import timedelta as _td
+        from datetime import timezone as _tz
+        import secrets
+
+        self._require_tenant(tenant_id)
+        email = (email or "").strip().lower()
+        if not email or "@" not in email:
+            raise ValueError(
+                f"email must be a non-empty 'user@domain' string, "
+                f"got {email!r}",
+            )
+        if role not in self._VALID_INVITE_ROLES:
+            raise ValueError(
+                f"role must be one of {self._VALID_INVITE_ROLES}, "
+                f"got {role!r}",
+            )
+        token = secrets.token_urlsafe(32)
+        token_hash = self._hash_token(token)
+        expires_at = (
+            _dt.now(_tz.utc) + _td(days=self._INVITATION_TTL_DAYS)
+        ).isoformat()
+        row = self.invitations.create(
+            tenant_id=tenant_id, email=email, role=role,
+            token_hash=token_hash, invited_by=invited_by,
+            expires_at=expires_at,
+        )
+        self.audit.log(
+            actor, "invite_user",
+            target_id=row["invite_id"],
+            tenant_id=tenant_id,
+            payload={"email": email, "role": role,
+                     "expires_at": expires_at},
+        )
+        # The raw token is returned to the caller — they need it for
+        # the link in the email — but it does NOT live in the row we
+        # return on subsequent reads.
+        return {**row, "raw_token": token}
+
+    def list_pending_invitations(self, tenant_id: str) -> List[dict]:
+        """Stage 194 — pending invitations for the tenant (not yet
+        accepted, not revoked, not expired). Sorted oldest first."""
+        self._require_tenant(tenant_id)
+        return self.invitations.list_pending(tenant_id)
+
+    def revoke_invitation(self, invite_id: str, *,
+                                  actor: str = "operator",
+                                  ) -> Optional[dict]:
+        """Stage 194 — admin pulls back a pending invitation. The
+        row remains for audit but the token can no longer be
+        redeemed."""
+        existing = self.invitations.get(invite_id)
+        if existing is None:
+            return None
+        if existing.get("accepted_at"):
+            raise ValueError(
+                f"invitation {invite_id!r} was already accepted; "
+                "revoking has no effect (revoke the resulting api key "
+                "instead)",
+            )
+        row = self.invitations.mark_revoked(invite_id)
+        self.audit.log(
+            actor, "revoke_invitation",
+            target_id=invite_id,
+            tenant_id=existing["tenant_id"],
+            payload={"email": existing.get("email")},
+        )
+        return row
+
+    def accept_invitation(self, token: str, *,
+                                display_name: str,
+                                ) -> dict:
+        """Stage 194 — the invitee redeems their one-shot link.
+        Validates the token, mints an API key bound to their
+        display_name + the invited role, marks the invite accepted.
+        Returns ``{tenant_id, role, api_key, key_id, name}`` —
+        the raw API key in ``api_key`` is shown EXACTLY ONCE per
+        the existing api_key contract.
+
+        Raises ValueError on: unknown token / already accepted /
+        already revoked / expired.
+        """
+        from datetime import datetime as _dt
+        from datetime import timezone as _tz
+
+        display_name = (display_name or "").strip()
+        if not display_name:
+            raise ValueError("display_name is required")
+        if not token:
+            raise ValueError("token is required")
+        row = self.invitations.get_by_token(self._hash_token(token))
+        if row is None:
+            raise ValueError("invitation not found")
+        if row.get("accepted_at"):
+            raise ValueError("invitation already accepted")
+        if row.get("revoked_at"):
+            raise ValueError("invitation revoked")
+        try:
+            exp = _dt.fromisoformat(row["expires_at"])
+        except (TypeError, ValueError):
+            exp = None
+        if exp is None or exp < _dt.now(_tz.utc):
+            raise ValueError("invitation expired")
+        # Mint the api key first; if anything fails AFTER the mint we
+        # still want the user to have a usable credential.
+        api_key = self.create_api_key(
+            row["tenant_id"], name=display_name,
+            role=row["role"], actor=f"invite:{row['invite_id']}",
+        )
+        self.invitations.mark_accepted(
+            row["invite_id"], key_id=api_key.key_id,
+        )
+        self.audit.log(
+            f"invite:{row['invite_id']}", "accept_invitation",
+            target_id=api_key.key_id,
+            tenant_id=row["tenant_id"],
+            payload={
+                "email": row.get("email"),
+                "display_name": display_name,
+                "role": row["role"],
+            },
+        )
+        return {
+            "tenant_id": row["tenant_id"],
+            "role": row["role"],
+            "key_id": api_key.key_id,
+            "api_key": api_key.raw,
+            "name": display_name,
+        }
+
     # --- auth / api keys (Stage 5a) -------------------------------------
     def create_api_key(self, tenant_id: str, name: str = "",
                        expires_at: Optional[str] = None,

infra/storage/__init__.py

@@ -35,6 +35,7 @@ from .repositories import (
     ScimGroupRepository,
     ScimUserConflict,
     ScimUserRepository,
+    TenantInvitationRepository,
     TenantOverridesRepository,
     TenantPlanOverrideRepository,
     TenantQuotaRepository,
@@ -71,6 +72,7 @@ __all__ = [
     "ScimGroupRepository",
     "ScimUserConflict",
     "ScimUserRepository",
+    "TenantInvitationRepository",
     "TenantPlanOverrideRepository",
     "TenantQuotaRepository",
     "UsageRepository",

infra/storage/repositories.py

@@ -2634,3 +2634,93 @@ class EntityMuteRepository:
             (mute_id,),
         )
         return True
+
+
+# --- Stage 194 — tenant invitations ----------------------------------
+
+class TenantInvitationRepository:
+    """Persists pending + completed invitations. The raw token is
+    NEVER stored — only ``sha256(token)``, mirroring the api_keys
+    discipline. The same row carries lifecycle timestamps
+    (accepted_at, revoked_at) so the table doubles as an audit
+    trail of who joined when."""
+
+    def __init__(self, db: Database):
+        self.db = db
+
+    def create(self, tenant_id: str, email: str, role: str,
+                   token_hash: str, invited_by: str,
+                   expires_at: str,
+                   invite_id: Optional[str] = None,
+                   ) -> dict:
+        import uuid
+        invite_id = invite_id or "inv_" + uuid.uuid4().hex[:12]
+        ts = _now()
+        self.db.execute(
+            "INSERT INTO tenant_invitations "
+            "(invite_id, tenant_id, email, role, token_hash, "
+            " invited_by, created_at, expires_at) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (invite_id, tenant_id, email, role, token_hash,
+             invited_by, ts, expires_at),
+        )
+        return self.get(invite_id)
+
+    def get(self, invite_id: str) -> Optional[dict]:
+        return self.db.query_one(
+            "SELECT * FROM tenant_invitations WHERE invite_id=?",
+            (invite_id,),
+        )
+
+    def get_by_token(self, token_hash: str) -> Optional[dict]:
+        return self.db.query_one(
+            "SELECT * FROM tenant_invitations WHERE token_hash=?",
+            (token_hash,),
+        )
+
+    def list_pending(self, tenant_id: str) -> List[dict]:
+        """Pending = not accepted AND not revoked AND not expired.
+        Sorted oldest-first so the operator sees the longest-waiting
+        first."""
+        return self.db.query_all(
+            "SELECT * FROM tenant_invitations "
+            "WHERE tenant_id=? "
+            "  AND accepted_at IS NULL "
+            "  AND revoked_at IS NULL "
+            "  AND expires_at > ? "
+            "ORDER BY created_at ASC",
+            (tenant_id, _now()),
+        )
+
+    def list_all(self, tenant_id: str,
+                  *, limit: int = 100) -> List[dict]:
+        """Every invitation row — pending + accepted + revoked +
+        expired. Used by audit / compliance queries."""
+        return self.db.query_all(
+            "SELECT * FROM tenant_invitations "
+            "WHERE tenant_id=? "
+            "ORDER BY created_at DESC LIMIT ?",
+            (tenant_id, limit),
+        )
+
+    def mark_accepted(self, invite_id: str, *,
+                              key_id: str) -> Optional[dict]:
+        if self.get(invite_id) is None:
+            return None
+        self.db.execute(
+            "UPDATE tenant_invitations "
+            "SET accepted_at=?, accepted_key_id=? "
+            "WHERE invite_id=?",
+            (_now(), key_id, invite_id),
+        )
+        return self.get(invite_id)
+
+    def mark_revoked(self, invite_id: str) -> Optional[dict]:
+        if self.get(invite_id) is None:
+            return None
+        self.db.execute(
+            "UPDATE tenant_invitations SET revoked_at=? "
+            "WHERE invite_id=?",
+            (_now(), invite_id),
+        )
+        return self.get(invite_id)

infra/storage/schema.py

@@ -686,6 +686,32 @@ CREATE TABLE IF NOT EXISTS entity_mutes (
 CREATE INDEX IF NOT EXISTS idx_entity_mutes_tenant_until
     ON entity_mutes (tenant_id, muted_until);
 
+-- v34 (Stage 194) — tenant invitations. An admin invites a coworker
+-- by email; the row carries a one-time token that the invitee
+-- redeems on the public /invite/accept page in exchange for an API
+-- key bound to their display name + the chosen role. accepted_at /
+-- revoked_at are timestamps that retire the row from the "pending"
+-- list. token is hash-only (sha256) so a leaked DB doesn't hand
+-- attackers a usable acceptance link.
+CREATE TABLE IF NOT EXISTS tenant_invitations (
+    invite_id     TEXT PRIMARY KEY,
+    tenant_id     TEXT NOT NULL,
+    email         TEXT NOT NULL,
+    role          TEXT NOT NULL DEFAULT 'operator',
+    token_hash    TEXT NOT NULL UNIQUE,
+    invited_by    TEXT NOT NULL,
+    created_at    TEXT NOT NULL,
+    expires_at    TEXT NOT NULL,
+    accepted_at   TEXT,
+    accepted_key_id TEXT,
+    revoked_at    TEXT,
+    FOREIGN KEY (tenant_id) REFERENCES tenants (tenant_id)
+);
+CREATE INDEX IF NOT EXISTS idx_tenant_invitations_tenant
+    ON tenant_invitations (tenant_id);
+CREATE INDEX IF NOT EXISTS idx_tenant_invitations_token
+    ON tenant_invitations (token_hash);
+
 -- init_db() AFTER the forward migrations, so a stale v2 DB upgrades cleanly.
 CREATE INDEX IF NOT EXISTS idx_schedules_tenant ON schedules (tenant_id);
 CREATE INDEX IF NOT EXISTS idx_api_keys_tenant   ON api_keys (tenant_id);