feat(hub): invitation-link tickets bound to a verified address

group_invite_links holds sha256(ticket) and the invitee's address blind
index; redeeming grants membership to that account only. Owner-only
create/list/cancel (a node token may create, never mail), 20 outstanding
per group, optional mail written by the hub itself and capped at 10 per
sender per day (mail.invite_link_daily_cap). MESHBAY_DESIGN.md §3.4 now
carries the whole link design.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 34 insertions, 0 deletions

diff --git a/packages/meshbay-hub/src/meshbay_hub/db/models.py b/packages/meshbay-hub/src/meshbay_hub/db/models.py
index ac1828f..51a3d47 100644
--- a/packages/meshbay-hub/src/meshbay_hub/db/models.py
+++ b/packages/meshbay-hub/src/meshbay_hub/db/models.py
@@ -145,6 +145,40 @@ class GroupMember(Base):
     user:  Mapped["User"]  = relationship(back_populates="group_memberships")
 
 
+class GroupInviteLink(Base):
+    """
+    The hub's half of an invitation link (docs/MESHBAY_DESIGN.md §7.3).
+
+    A link carries two secrets. The node's code decides whether someone gets the
+    group key, and the hub never sees it. This row decides whether someone may
+    *reach* the node at all — membership, which is all the hub has to give — and
+    only for the account whose verified address matches `email_hash`. The ticket
+    is stored as `sha256(ticket)`, so a copy of this table opens nothing.
+
+    No address in the clear: `email_hash` is the same blind index `users` has,
+    and `email_masked` is what the owner's list shows (`al***@ex***.com`).
+    """
+    __tablename__ = "group_invite_links"
+
+    id:             Mapped[str] = mapped_column(String(36), primary_key=True, default=_uuid)
+    group_id:       Mapped[str] = mapped_column(ForeignKey("groups.id"), nullable=False)
+    created_by:     Mapped[str] = mapped_column(ForeignKey("users.id"), nullable=False)
+    ticket_hash:    Mapped[str] = mapped_column(String(64), nullable=False)
+    email_hash:     Mapped[str] = mapped_column(String(64), nullable=False)
+    email_masked:   Mapped[str] = mapped_column(String(128), nullable=False)
+    # The node's handle for its half, so cancelling can take back both.
+    node_invite_id: Mapped[str] = mapped_column(String(32), nullable=False, default="")
+    created_at:     Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
+    expires_at:     Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    redeemed_by:    Mapped[str | None] = mapped_column(ForeignKey("users.id"))
+    redeemed_at:    Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    __table_args__ = (
+        Index("uq_invite_links_ticket", "ticket_hash", unique=True),
+        Index("ix_invite_links_group", "group_id"),
+    )
+
+
 # ── Refresh tokens ────────────────────────────────────────────────────────────
 
 class RefreshToken(Base):