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 ordinary roles); AskMyDocs replaces its service binding with ProtectedRoleProvisioner so neither super-admin nor system-admin can be minted by redemption, and adds more provisioners 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. Protected role binding + ProjectMembershipProvisioner. The package’s SpatiePermissionProvisioner service key resolves to App\Invitations\ProtectedRoleProvisioner, which preserves grant-never-revoke for ordinary roles while rejecting both protected admin boundaries. App\Invitations\ProjectMembershipProvisioner is added to the invitations.provisioners tag alongside the replaced package provisioner service key. The package’s contextual giveTagged('invitations.provisioners') for AccountProvisioningService resolves the tag lazily at redemption time, so both provisioners run: the protected adapter raises an ordinary application role, while the membership adapter 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

• invite_codes.code has the global unique index uq_invite_codes_code_global, because a guest has no tenant context from which to begin lookup;
• the existing tenants registry gains is_system (boolean, default false) and an idempotently seeded system-registration row with is_system=true.

​

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) at package level. Installing the package does not force its generic redemption middleware into closed-beta mode. AskMyDocs’s host POST /api/auth/register contract is separately and always invite-only; this flag cannot open public signup.
• 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.
• A reserved slug, not a reserved numeric ID range. Tenant-aware foreign keys use the string slug as tenant_id; the optional registry’s numeric primary key carries no authorization meaning. system-registration therefore provides a stable technical namespace without moving operational tenant IDs or introducing a second invitation table. See ADR 0025.

​

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);

​

Worked example — public registration with or without an existing company

php artisan registration-invite:create --uses=1

POST /api/auth/onboarding/company
Content-Type: application/json

{
  "company_name": "Acme S.p.A.",
  "tenant_slug": "acme",
  "project_key": "acme-kb"
}

php artisan registration-invite:create \
  --tenant=acme \
  --project=acme-kb \
  --role=viewer \
  --membership-role=member \
  --uses=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. Resolve and pre-validate the globally unique opaque code with RegistrationCodeResolver, which delegates state/capacity validation to 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.

• tenant_join must contain exactly one explicit grant to an active operational tenant and real projects. Redemption provisions the membership, so /app opens the tenant directly.
• company_bootstrap must contain an empty grant. The account remains without memberships and /app forces resumable company onboarding.

​

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.
• INVITE_REQUIRED does not control host registration. The host /api/auth/register request always requires invite_code; the flag only changes package-level generic invitation middleware.
• Do not issue public registration codes from default. Use registration-invite:create; its codes live in system-registration, carry a validated intent and cannot accidentally grant access to the technical namespace.
• Campaign creation writes a grant — protected admins stay out. The campaign builder’s grant editor provisions a Spatie role + KB projects across one or more tenants on redemption; super-admin and system-admin are rejected 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.