Invitations & Referrals

​

Motivation

​

Theory — where the coupling lives

• TenantResolver — current(): string. Every invite table carries tenant_id; every query is scoped through this resolver. A plain app gets the package’s single-tenant default; a multi-tenant host binds its own.
• InvitedAccount — getInviteEmail(): ?string + getInviteGuardName(): string. The engine reads only these two account attributes (email for abuse-correlation hashing, guard for role provisioning) so it never couples to a concrete user class.
• Provisioner (tagged invitations.provisioners) — provision(Model $account, TenantGrant $grant): void. The package ships SpatiePermissionProvisioner (grants the role); a host adds more under the same tag. Two invariants the contract mandates: GRANT-never-REVOKE (only ever raise access) and best-effort (a fault is swallowed + logged, never thrown — the redemption is already committed when provisioning runs).

​

Design

1. TenantResolver → App\Support\TenantContext. An anonymous class adapts the host context’s current() to the package contract. The package binds its single-tenant default with bindIf(); an explicit bind() in boot() overrides it definitively. Result: every invite read/write is scoped to the tenant the request resolved (R30).
2. App\Invitations\ProjectMembershipProvisioner → the invitations.provisioners tag. Appended to the tag alongside the package’s SpatiePermissionProvisioner. The package’s contextual giveTagged('invitations.provisioners') for AccountProvisioningService resolves the tag lazily at redemption time, so both provisioners run: the Spatie one raises the global role, ours raises per-project access.
3. manageInvitations gate + config/invitations.php. The package routes carry no internal authorization — admin gating is entirely the host admin_middleware config (R32). AskMyDocs sets it to its standard admin stack plus can:manageInvitations.

​

Data model

​

Decision rationale

• Reuse the standalone engine, bind the seams — don’t fork it inline. The invite engine is general-purpose and battle-tested; AskMyDocs is one consumer. Keeping it a package means its concurrency-safety and anti-abuse logic improve for every consumer at once, and AskMyDocs only owns the ~70-line provisioner + the bindings.
• Atomic redemption is the engine’s, and it is not negotiable. Seat-count safety comes from a single conditional UPDATE … WHERE current_uses < max_uses plus UNIQUE(code_id, redeemer_id) — never a read-then-write. Two concurrent redemptions of the last seat cannot both win (mirrors AskMyDocs’s own R21 “security invariants are atomic or absent”).
• GRANT-never-REVOKE provisioning. ProjectMembershipProvisioner uses firstOrCreate on (tenant_id, user_id, project_key). A pre-existing membership at a higher role is never downgraded; an invite can only raise access. This makes redemption safe to replay and safe to over-grant.
• Best-effort provisioning. The redemption commits first; provisioning runs after. A provisioning fault is logged (with the exception class for triage) and swallowed — a transient DB hiccup while writing a membership must not roll back a redemption the user already sees as successful.
• INVITE_REQUIRED defaults OFF (R43 both-states). Installing the package does not silently turn AskMyDocs into a closed beta. The signup gate is strict opt-in; both the OFF path (registration unchanged) and the ON path (code required) are covered by tests.
• The 9 invite tables stay package-owned. They are not added to the host TenantIdMandatoryTest enumeration (which only iterates App\Models\*) — the package enforces R30/R31 on its own models in its own CI, exactly as the askmydocs-connector-base tables do.

​

Worked example — a launch-wave campaign that grants editor + two projects

// 1. A campaign whose codes grant the 'editor' role + membership in two projects,
//    in the current tenant.
$campaign = app(\Padosoft\Invitations\Services\CampaignService::class)->create([
    'name'  => 'Launch wave',
    'grant' => [
        'role'         => 'editor',
        'projects'     => ['hr-portal', 'engineering'],
        'project_role' => 'member',
    ],
]);

// 2. Generate 100 single-use codes for it (PHP surface; same as
//    POST /api/admin/invitations/codes and the InviteGenerateCodesTool MCP tool).
$codes = app(\Padosoft\Invitations\Services\CodeGenerator::class)
    ->generate($campaign->id, count: 100, maxUses: 1);

​

Admin UI — native, in-app

• Truncation is visible. The core read surfaces cap at 500 rows with no pagination; when a table hits the cap it shows a “first 500 rows — refine the filters” notice rather than pretending the list is complete (R3/R14).
• The “Advanced” panel link is gated on a server-truthful flag. The standalone padosoft/laravel-invitations-admin panel (campaign builder + multi-tenant grant editor — the parts not yet native) is offered as an “Advanced” launcher only when INVITATIONS_ADMIN_ENABLED=true. The SPA learns this from the additive features.invitations_admin field on /api/auth/me (R27); when the mount is OFF the package route is unregistered and the link is hidden, so it never dead-ends on the /admin/invitations 404 (R14/R43).

​

Invite-only sign-up (SPA registration)

1. Pre-validate the code with CodeValidator before touching users — an invalid / expired / exhausted code never mints an orphan account.
2. Create the account (no role yet).
3. Redeem authoritatively with RedemptionService (the atomic conditional UPDATE … WHERE current_uses < max_uses + the tagged Spatie-role / project provisioners). Redeem runs outside any DB transaction by design: on PostgreSQL a UNIQUE-violation aborts the connection for the rest of a transaction, which would poison the package’s compensation follow-ups. On an exhausted-between-checks race the brand-new account is force-deleted.
4. Floor the account at viewer (layered on any grant role redeem already provisioned — GRANT-never-revoke), open the SPA session, fire Registered.

​

Gotchas

• manageInvitations is super-admin + admin. Issuing access-granting codes is an administrative act; dpo / editor / viewer are excluded. The user redeem surface (/api/invitations/*) only requires authentication — any logged-in account may redeem a code it holds.
• Provisioning runs in the redemption tenant and any explicit grant tenants. A grant’s tenantId is authoritative for that slice — a single code can seed memberships in several tenants at once. The host provisioner writes each membership in its grant’s tenant, not the request’s active tenant.
• A provisioning failure never fails the redemption. If you don’t see a membership after a successful redeem, check the logs for invitations.provision.project_membership_failed (it carries the exception class) — the redemption itself still succeeded by design.
• Flipping INVITE_REQUIRED=true is a product decision, not a deploy detail. With it on, registration requires a valid code. Verify your invite-issuing flow is live before enabling it, or new signups are blocked.
• Campaign creation writes a grant — mind super-admin + immutability. The campaign builder’s grant editor provisions a Spatie role + KB projects across one or more tenants on redemption; super-admin is rejected (client and server) and a campaign’s key + type are immutable after creation (the update rules don’t accept them). The standalone padosoft/laravel-invitations-admin panel remains reachable via the gated “Advanced” launcher (INVITATIONS_ADMIN_ENABLED=true) for parity, but the native tabs now cover the full create/edit/send surface.