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
- The claim secret travels only in our email. Partner responses never contain a
claim URL, token or expiry; the partner sees only
claimedand may ask for a rate-limited resend. A successful Claim setsemailVerified = true, because it proves ownership of the inbox. - 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).
- 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.
- 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. - 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_existsstill confirms an email is registered; bounded by admin-issued keys and rate limits.- Better Auth’s
resetPasswordcreates 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
sandboxaccounts row, so the landlord reads as claimed. It does not setemailVerified, 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
simulatedtoken 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.