identity-membership

Identity, User, Membership

A person who signs in is an Identity. A workspace they can enter is a Tenant (or Account). The join is Membership. Sessions hang on Identity, never on the tenant-scoped User.

This sits on top of magic-link-auth. In SQLite-per-tenant apps it also sits on activerecord-tenanted. Fizzy uses the same split in a single database.

Philosophy

1. Identity authenticates. Membership authorizes. User is the in-tenant person. Mixing these is how you leak one customer's users into another shard.
2. One email, many workspaces. Don't create a second Identity when someone joins a second tenant.
3. Create Membership globally, then the tenanted User inside with_tenant. Order matters; a User without a Membership is an orphan.
4. Join codes are shareable, not emailed magic links. Different secret, different table.

The records

Identity  (global)  email, sessions, magic links, access tokens
   │
   ├── Membership (global)  identity_id + tenant_id + role
   │
   └── User (tenanted, Cortex/Innkeeper)  identity_id + name + in-tenant role

Herald skips the tenanted User: AccountMembership on the global DB is enough because account members can see every project. Cortex/Innkeeper need a User inside the tenant DB for project assignments, comments, and audit actor.

Fizzy's User is the membership row in the same database (users.identity_id + account_id). Same idea, no shard.

Step 1: Identity stays global

class Identity < GlobalRecord
  has_many :sessions

Sign-in creates a Session for this Identity (magic-link-auth). It does not pick a tenant.

Step 2: Membership is the join

Roles live here for "can they enter this workspace at all." Finer ACL (board access, project assignments) lives on tenanted records.

Herald: AccountMembership with owner / member. Innkeeper adds viewer.

Step 3: Tenanted User (when the workspace has a person record)

No FK to identities — different database. Copy role from Membership at join time; don't treat the two roles as independent sources of truth.

Step 4: Join in one method

Rescue RecordNotUnique and re-find — two tabs will race. Herald's Account#add_member! is the same idea without a tenanted User.

After magic-link verify, if identity.tenants.none?, send them to create-tenant / new-project. If they have tenants, send them to the last one or a picker.

Step 5: Current

Current.user is nil when the Identity is signed in but has no Membership in this tenant. That's a 403, not a sign-in loop.

Don't set Current.user from the session. The session doesn't know which tenant the URL selected.

Step 6: Join codes

Shareable XXXX-XXXX-XXXX (Base58, no 0/O/I/l). Global table. One active code per tenant/project.

Redeem:

1. Load JoinCode by code (global).
2. If not signed in, stash the code in the session and send them through magic-link.
3. identity.join(tenant) then redeem_if.
4. Rate-limit the redeem endpoint.

Don't use a magic-link code as an invite. Don't increment usage until join succeeds.

Anti-Patterns

1. has_many :sessions on User — logout/login is per person, not per workspace.
2. find_or_create_by(email:) inside a tenant — creates duplicate people; Identity is the uniqueness boundary.
3. Authorizing with Current.identity only — they might not be a member of this tenant.
4. Creating User before Membership — User in a shard with no global join row.
5. Nebula Member on workspace — different tenancy; don't copy that into an activerecord-tenanted app.
6. Emailing the join code in the magic-link mailer — two flows, two templates.

Related

• Sign-in codes and session cookies: magic-link-auth
• Shard switching: activerecord-tenanted

See reference.md for Herald vs Cortex/Innkeeper vs Fizzy, and test helpers.