""" Invitation links — the hub's half (docs/MESHBAY_DESIGN.md §3.4, §7.3). A link carries two secrets with two jobs. The node's code decides who gets the group key, and it is shown to the hub only when the inviter asks the hub to mail the link. The ticket here decides who may *reach* the node — membership, which is all the hub has to give (§7.1) — and it gives it to one account only: the one whose verified address the inviter named. A ticket that leaks, through a messaging service that previews links or a forwarded mail, is therefore useless without that mailbox. Stated per the design's convention: that binding holds against third parties and not against this hub, which verifies the addresses it compares. An active hub could already be anybody. No route here answers without an account, and nothing tells the inviter whether an address has an account (M1): creating a link looks the same either way. """ import hashlib import re import secrets from datetime import UTC, datetime, timedelta from fastapi import APIRouter, Depends, HTTPException, Request from pydantic import BaseModel, field_validator from sqlalchemy import delete, func, select, update from sqlalchemy.ext.asyncio import AsyncSession from meshbay_hub import mail from meshbay_hub.api.deps import _decode_token, get_current_user, require_user_scope from meshbay_hub.api.middleware import limiter from meshbay_hub.auth import hash_email_blind from meshbay_hub.db.engine import get_db from meshbay_hub.db.models import Group, GroupInviteLink, GroupMember, User router = APIRouter(prefix="/v1/groups", tags=["invite-links"]) redeem_router = APIRouter(prefix="/v1/invite-links", tags=["invite-links"]) # The node holds at most as many unredeemed link codes per group; one more # ticket here than codes there would be a link that cannot work. MAX_OUTSTANDING_PER_GROUP = 20 # A node's invitation lifetime is the operator's setting (7 days by default); # the ticket follows it, up to this. MAX_LIFETIME = timedelta(days=30) # How long a spent link is kept before it is forgotten. The owner is not shown # it — the person is in the group — but while the row is here, a reload or a # second tab of the invitation page still answers the account that used it. KEEP_REDEEMED = timedelta(days=30) _TICKET = re.compile(r"^[A-Za-z0-9_-]{22}$") # secrets.token_urlsafe(16) _NODE_INVITE_ID = re.compile(r"^[0-9a-f]{32}$") # roster.create_link_invite _CODE = re.compile(r"^[0-9A-Za-z]{4}-[0-9A-Za-z]{4}$") # roster.generate_code _B64URL_KEY = re.compile(r"^[A-Za-z0-9_-]{43}$") # 32 bytes, unpadded def ticket_hash(ticket: str) -> str: return hashlib.sha256(ticket.encode()).hexdigest() def invite_url(group_id: str, ticket: str, node_pk: str, code: str) -> str: """ The one shape an invitation link has (docs/MESHBAY_DESIGN.md §3.4). Everything after `#`, so none of it is sent to this hub in a request — it reaches the page and the page alone, which parses this same shape. """ return (f"{mail.hub_url()}/#/invite?v=1&g={group_id}&t={ticket}" f"&n={node_pk}&c={code}") def _mask(email: str) -> str: """`al***@ex***.com` — enough for the owner to recognise, not to reuse.""" local, _, domain = email.strip().lower().partition("@") name, _, tld = domain.rpartition(".") return f"{local[:2]}***@{name[:2]}***.{tld}" def _aware(when: datetime) -> datetime: # SQLite hands a timezone-aware column back naive. return when if when.tzinfo else when.replace(tzinfo=UTC) def _valid_email(v: str) -> str: v = v.strip() local, sep, domain = v.partition("@") if (not sep or not local or not domain or "." not in domain.strip(".") or len(v) > 254 or any(c.isspace() or ord(c) < 32 for c in v)): raise ValueError("invalid email address") return v class CreateLinkRequest(BaseModel): email: str expires_at: str node_invite_id: str # Only when the hub is to mail the link, since only then must it write it: # the node key in its URL-safe form, and the node's code — which the hub # therefore reads. Unchecked in the interface, neither is sent. send_email: bool = False node_pk: str = "" code: str = "" @field_validator("email") @classmethod def email_valid(cls, v: str) -> str: return _valid_email(v) class TicketRequest(BaseModel): ticket: str async def _owned_group(db: AsyncSession, group_id: str, user: User) -> Group: group = await db.get(Group, group_id) if not group: raise HTTPException(status_code=404, detail="Group not found") if group.admin_id != user.id: raise HTTPException(status_code=403, detail="Only the group owner can manage its invitation links") return group @router.post("/{group_id}/invite-links", status_code=201) @limiter.limit("20/hour") async def create_invite_link( group_id: str, body: CreateLinkRequest, request: Request, payload: dict = Depends(_decode_token), current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db), ): """ Mint the ticket for a link whose node half already exists. `get_current_user`, not `require_user_scope`: `meshbay-node member invite --link` asks with the node's token, as the CLI invitation already does, and the owner check is the guard — a node can only act for its own operator's groups. The CLI mails nothing (`USERGUIDE.md` §7), so a node token asking for mail is refused rather than quietly obeyed. """ group = await _owned_group(db, group_id, current_user) if group.status != "active": raise HTTPException(status_code=409, detail="This group is not active") if group.join_policy == "open": raise HTTPException(status_code=409, detail="An open group admits anyone; it needs no invitation") if not _NODE_INVITE_ID.match(body.node_invite_id): raise HTTPException(status_code=422, detail="Not a node invitation id") if body.send_email: if payload.get("scope") == "node": raise HTTPException(status_code=403, detail="Invitation mail is sent from the interface only") if not (_CODE.match(body.code) and _B64URL_KEY.match(body.node_pk)): raise HTTPException(status_code=422, detail="Mailing a link needs its code and node key") now = datetime.now(UTC) try: expires = _aware(datetime.fromisoformat(body.expires_at)) except ValueError: raise HTTPException(status_code=422, detail="Not a date") from None if expires <= now: raise HTTPException(status_code=422, detail="That invitation has already expired") expires = min(expires, now + MAX_LIFETIME) await _purge(db, group_id, now) outstanding = (await db.execute( select(func.count()).select_from(GroupInviteLink).where( GroupInviteLink.group_id == group_id, GroupInviteLink.redeemed_by.is_(None), GroupInviteLink.expires_at > now))).scalar() or 0 if outstanding >= MAX_OUTSTANDING_PER_GROUP: raise HTTPException( status_code=429, detail=f"This group already has {outstanding} unused invitation links") ticket = secrets.token_urlsafe(16) row = GroupInviteLink( group_id=group_id, created_by=current_user.id, ticket_hash=ticket_hash(ticket), email_hash=hash_email_blind(body.email), email_masked=_mask(body.email), node_invite_id=body.node_invite_id, expires_at=expires) db.add(row) await db.flush() email_status = "not_requested" if body.send_email: try: sent = await mail.send_off_loop( db, mail.send_invite_link, body.email, invite_url(group_id, ticket, body.node_pk, body.code.upper()), current_user.username, group.name, purpose="invite_link", sender=current_user.id) email_status = "sent" if sent else "refused" except Exception: email_status = "send_failed" await db.commit() return {"link_id": row.id, "ticket": ticket, "expires_at": expires.isoformat(), "email_status": email_status} @router.get("/{group_id}/invite-links") async def list_invite_links( group_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db), ): """ The owner's view: the links nobody has used yet, masked. A redeemed one is left out. The person it let in has a row of their own in the members list, so keeping the link there too says the same thing twice and pushes down the links that still wait for somebody — which are the ones the owner can act on, by cancelling them. """ await _owned_group(db, group_id, current_user) rows = (await db.execute( select(GroupInviteLink) .where(GroupInviteLink.group_id == group_id, GroupInviteLink.redeemed_by.is_(None)) .order_by(GroupInviteLink.created_at.desc()) .limit(200))).scalars().all() now = datetime.now(UTC) return {"links": [{ "link_id": r.id, "email": r.email_masked, "node_invite_id": r.node_invite_id, "created_at": _aware(r.created_at).isoformat(), "expires_at": _aware(r.expires_at).isoformat(), "status": "expired" if _aware(r.expires_at) <= now else "pending", } for r in rows]} @router.delete("/{group_id}/invite-links/{link_id}") async def delete_invite_link( group_id: str, link_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db), ): """Take the ticket back. The node's code is the client's half to cancel, first, with a signed `invite_cancel` — this only closes the door here.""" await _owned_group(db, group_id, current_user) row = await db.get(GroupInviteLink, link_id) if not row or row.group_id != group_id: raise HTTPException(status_code=404, detail="No such invitation link") if row.redeemed_by: raise HTTPException(status_code=409, detail="This link has been used; remove the member instead") await db.delete(row) await db.commit() return {"status": "deleted", "link_id": link_id} async def _resolve(db: AsyncSession, ticket: str, user: User ) -> tuple[GroupInviteLink, Group]: """ The link this ticket names, if this account may use it. One uniform refusal for everything that says nothing about the account — unknown, spent by someone else, expired, a group no longer active — and one distinct answer, `invite_other_account`, for the case the person can act on: signed in as somebody other than the address it was sent to. That answer names no address, and it is given only to someone holding the ticket, who already knows a link exists. """ invalid = HTTPException(status_code=404, detail="invite_not_valid") if not _TICKET.match(ticket or ""): raise invalid row = (await db.execute(select(GroupInviteLink).where( GroupInviteLink.ticket_hash == ticket_hash(ticket)))).scalar_one_or_none() if row is None: raise invalid group = await db.get(Group, row.group_id) if group is None or group.status != "active": raise invalid if row.redeemed_by and row.redeemed_by != user.id: raise invalid if not row.redeemed_by and _aware(row.expires_at) <= datetime.now(UTC): raise invalid if not user.email_hash or user.email_hash != row.email_hash: raise HTTPException(status_code=403, detail="invite_other_account") return row, group @redeem_router.post("/preview") @limiter.limit("30/minute") async def preview_invite_link( body: TicketRequest, request: Request, current_user: User = Depends(require_user_scope), db: AsyncSession = Depends(get_db), ): """What the confirmation screen shows before anyone joins anything.""" row, group = await _resolve(db, body.ticket, current_user) inviter = await db.get(User, row.created_by) member = await db.get(GroupMember, (group.id, current_user.id)) return {"group_id": group.id, "group_name": group.name, "inviter": inviter.username if inviter else "", "expires_at": _aware(row.expires_at).isoformat(), "already_member": member is not None} @redeem_router.post("/redeem") @limiter.limit("30/minute") async def redeem_invite_link( body: TicketRequest, request: Request, current_user: User = Depends(require_user_scope), db: AsyncSession = Depends(get_db), ): """ Membership for the addressed account, once — and the same answer again for that account, because a second tab or a reload is the same person. """ row, group = await _resolve(db, body.ticket, current_user) if not row.redeemed_by: claimed = await db.execute( update(GroupInviteLink) .where(GroupInviteLink.id == row.id, GroupInviteLink.redeemed_by.is_(None)) .values(redeemed_by=current_user.id, redeemed_at=datetime.now(UTC))) if claimed.rowcount == 0: raise HTTPException(status_code=404, detail="invite_not_valid") if not await db.get(GroupMember, (group.id, current_user.id)): db.add(GroupMember(group_id=group.id, user_id=current_user.id)) from meshbay_hub.api.notifications import create_notification await create_notification( db, row.created_by, "invite_link_redeemed", f"{current_user.username} joined {group.name} through your invitation link", link=f"#/group/{group.id}", group_id=group.id) await db.commit() return {"group_id": group.id, "group_name": group.name} async def _purge(db: AsyncSession, group_id: str, now: datetime) -> None: """Forget this group's dead links: unused ones once expired, used ones after `KEEP_REDEEMED`. Done on the way in, so the table cannot outgrow its use.""" await db.execute(delete(GroupInviteLink).where( GroupInviteLink.group_id == group_id, ((GroupInviteLink.redeemed_by.is_(None) & (GroupInviteLink.expires_at <= now)) | (GroupInviteLink.redeemed_at < now - KEEP_REDEEMED))))