0072. Partner-created landlords are claimed only through platform email, and every existing account needs consent

Status: Accepted (2026-10-03)

Context

The Partner API (design: docs/superpowers/specs/2026-10-03-partner-api-p1-design.md) lets a partner create landlord accounts and act for them within granted scopes. A partner-created landlord is a real platform account (D3) that the landlord later takes over by setting a password: the Claim. The first draft returned the claim link to the partner. Whoever opens that link sets the password, so a partner could hold a full landlord login — chats, offers, signing — far beyond its scopes, and the Claim would prove nothing about the email. The draft also let a partner silently take over any existing account that had no sign-in method and no grant, which matches partner service users, anonymous users, admin-created users, and other partners’ abandoned accounts.

Decision

  1. The claim secret travels only in our email. Partner responses never contain a claim URL, token or expiry; the partner sees only claimed and may ask for a rate-limited resend. A successful Claim sets emailVerified = true, because it proves ownership of the inbox.
  2. One claim path. Account creation, partner resend, and the setup email offered on a connect page all issue the same email token and go through the same serialized, one-time Claim. It never replaces an existing sign-in method. Expiry is checked under the claim lock immediately before authorizing the account write; a write authorized before expiry may commit just after it (design §7.2).
  3. A partner recovers only the account its own provisioning attempt created, proven by a stamp written on the user at creation. Every other existing account — including one abandoned by another partner — is linked only through the landlord’s consent.
  4. No submit before the Claim. A partner may prepare properties and listings for an unclaimed landlord, but submit returns 409 landlord_unclaimed. Publication stays admin review.
  5. The claim right belongs to the account: a revoked grant or suspended partner does not remove it. Partner service users can never claim, approve, or sign in.

Considered options

  • Partner delivers the claim link. Least friction for the partner’s site; makes grant scopes meaningless.
  • Partner delivers the link, landlord confirms with an emailed code. Keeps the claim inside the partner’s site; needs a code table, a second email and code-entry UI.
  • Denylist recovery (exclude service, anonymous, staff users). Every new kind of passwordless user is a new hole, and cross-partner takeover without consent remains.
  • Allow submit before the Claim and add a viewing-request email. Nobody can answer a Seeker until the landlord signs in, and a mistyped email would carry a live ownership declaration in a stranger’s name.
  • General forgot-password so unclaimed landlords can sign in to approve a connect request. A second claim path that skips the claim guard.

Consequences

  • External partners build against “we never see a claim secret” and “existing accounts need consent”. Reversing either breaks their integrations, which is why this is an ADR.
  • A partner’s onboarding has an email step it does not control; its site can only say “check your email”.
  • 409 landlord_exists still confirms an email is registered; bounded by admin-issued keys and rate limits.
  • Better Auth’s resetPassword creates a missing credential row. Any future reset feature must refuse unclaimed partner accounts or route them through the Claim.

Test-mode exception (2026-10-10)

Partner test keys (grp_test_) act only on Test Landlords: synthetic accounts that have no real email and can never sign in (design: docs/superpowers/specs/2026-10-10-partner-test-mode-foundation-design.md). For them only:
  • A Simulated Claim endpoint replaces the emailed claim. It adds a non-usable sandbox accounts row, so the landlord reads as claimed. It does not set emailVerified, because no inbox was proven. Decision 1’s verification rule still holds for every real Claim.
  • No claim secret is generated and no email is sent. Issue paths record a simulated token row with no hash, so the per-account rate limit counts exactly as above. Real claim lookup never accepts a simulated row.
  • A simulated consent approve stands in for the landlord’s consent page. Real consent endpoints refuse test connect requests, and live keys can never reach the simulation endpoints, so decisions 2–5 are unchanged for real accounts.

Token issuance implementation

PartnerClaimUseCase.Issue(ctx, IssueClaimInput) is account-based: partner/grant IDs provide optional attribution, not eligibility or authorization. The setup-email flow can call it without an active grant or partner; that flow conceals eligibility and rate-limit errors in its generic answer. Partner resend separately requires a landlords:write key and any active grant through the existing partner pipeline. Every issue uses the rental TxRunner connection and takes pg_advisory_xact_lock(hashtext(landlord_user_id)) before fresh users and accounts reads. Bun credential linking must share this exact lock key. Creation and stamp recovery issue inside the winning activation transaction, together with the contact update and business audits; active replay sends nothing. The emailed secret is unpadded base64url of 32 cryptographically random bytes; the persisted digest is lowercase SHA-256 hex of those decoded bytes. A later claim lookup must decode before hashing. Expiry is seven days from database clock_timestamp(), read after the lock. Only unused tokens are superseded. All token states and all issue paths count toward the per-account limit: one in the preceding ten minutes and five in the preceding 24 hours. The exact boundary timestamp is outside the rolling window. Delivery happens after commit with rental:partner-claim:{token_id}. Provider failure does not fail the successful API write; logs record the token ID and error type, never provider error text that may echo a link. Claim-token SQL tracing remains enabled but does not interpolate digest or expiry parameters.