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>

2 files changed, 80 insertions, 0 deletions

diff --git a/packages/meshbay-hub/src/meshbay_hub/db/migrations/versions/b2c3d4e5f6a7_add_group_invite_links.py b/packages/meshbay-hub/src/meshbay_hub/db/migrations/versions/b2c3d4e5f6a7_add_group_invite_links.py
new file mode 100644
index 0000000..75b4d49
--- /dev/null
+++ b/packages/meshbay-hub/src/meshbay_hub/db/migrations/versions/b2c3d4e5f6a7_add_group_invite_links.py
@@ -0,0 +1,46 @@
+"""add group_invite_links
+
+The hub's half of an invitation link: a ticket, stored hashed, that grants
+membership of one group to the one account whose verified address matches.
+
+Revision ID: b2c3d4e5f6a7
+Revises: a9b8c7d6e5f4
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "b2c3d4e5f6a7"
+down_revision: str | Sequence[str] | None = "a9b8c7d6e5f4"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "group_invite_links",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("group_id", sa.String(36), sa.ForeignKey("groups.id"), nullable=False),
+        sa.Column("created_by", sa.String(36), sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("ticket_hash", sa.String(64), nullable=False),
+        sa.Column("email_hash", sa.String(64), nullable=False),
+        sa.Column("email_masked", sa.String(128), nullable=False),
+        sa.Column("node_invite_id", sa.String(32), nullable=False, server_default=""),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.func.now()),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("redeemed_by", sa.String(36), sa.ForeignKey("users.id")),
+        sa.Column("redeemed_at", sa.DateTime(timezone=True)),
+    )
+    op.create_index("uq_invite_links_ticket", "group_invite_links", ["ticket_hash"],
+                    unique=True)
+    op.create_index("ix_invite_links_group", "group_invite_links", ["group_id"])
+
+
+def downgrade() -> None:
+    # Outstanding links stop working; the node halves stay until they expire.
+    op.drop_index("ix_invite_links_group", table_name="group_invite_links")
+    op.drop_index("uq_invite_links_ticket", table_name="group_invite_links")
+    op.drop_table("group_invite_links")
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):