Partner API — Test Mode Foundation (Sub-project 1)
Partner API keys gain a fixed test or live mode on the same host, Stripe-style, so partners can build and verify their supply-side integration against isolated, partner-scoped test data before switching to a live key. Synthetic test landlords, simulated claim, consent and listing review, and a full reset replace the old 'integrate against UAT' rule without changing live-key or landlord grm_ key behaviour.
- Predecessor Partner API P1 design (replaces decision D8)
- ADRs 0072
- Status Approved
Summary
Partner API keys gain a fixed test or live mode, Stripe-style, on the same host. Test keys work against isolated, partner-scoped test data: synthetic test landlords, simulated claim and consent, simulated listing review and a full reset. Live-key and landlord grm_ key behaviour do not change.
- Go
- Partner API in
backend/go/internal/modules/rental - Bun
- Partner keys, key verification and test landlord identity in
backend/bun - Contract
backend/go/openapi/partner-v1.yaml- Frontend
- Consent page in
frontend/solidstart/apps/rental; partner key form infrontend/solidstart/apps/panel - Predecessor
- P1 design (decision D8 replaced)
Intent and success
Every partner needs two environments: Testing, to build and verify its integration, and Production, which it moves to once testing passes. Production does not exist yet, but the environment model should be in place before it does.
The chosen model is Stripe-style test mode inside each platform deployment. A partner holds test and live keys on the same API host. Test keys only ever see isolated test data. The model works in UAT today and carries into production unchanged.
Decomposition
The full Testing environment is split into three sub-projects, each with its own spec, plan and implementation. Sub-project 1 is sequenced internally by its implementation plan. The decomposition and approval gates stay as approved.
| # | Sub-project | Depends on |
|---|---|---|
| 1 | Test-mode foundation (this spec): key modes, mode propagation, partner-scoped isolation, test landlords with simulated claim/consent, simulated listing review, reset. | — |
| 2 | Demand-side simulation: test viewing requests, messages, offers, tenancies, payments, handover; test webhook endpoints and events. | 1 |
| 3 | Self-serve and docs: test/live key choice in the self-serve portal; Testing vs Production in the developer docs. | 1, plus the in-progress portal and docs work |
Approved conversational decisions
Environment model
Test mode inside each deployment; same host, the key decides the environment.
Rejected: a separate sandbox deployment (second stack, separate registration, drift) and UAT-as-Testing (unstable, shared, real emails).
Test landlords and human steps
Test keys use the normal endpoints, which create or target synthetic non-interactive test landlords. Claim and consent are completed through test-only simulation endpoints.
Rejected: preset fixtures (cannot exercise onboarding code) and real human test accounts (slow, real email, not automatable).
Listing review
Test submit returns pending_review; a simulation endpoint approves or rejects.
Rejected: auto-approve (cannot test review states) and timed auto-decision (non-deterministic, no rejection).
Credentials
Each key has a fixed mode shown in its prefix: grp_test_… or grp_live_….
Rejected: one key plus a mode header (one credential reaches both environments; a missing header means live) and separate partner records per mode (two identities to keep in sync).
Clean slate
Test-only POST /test/reset deletes all of the partner's test data.
Rejected: normal cleanup only (data piles up; some items cannot be deleted) and automatic expiry (data vanishes mid-test).
Review resolutions
Each row is a decision from the written-spec review; the sections named hold the detail. W1 and W2 are write-back verification corrections. They restore the accepted reset and identical-integration invariants and do not narrow scope.
| ID | Resolution | Rejected alternative | § |
|---|---|---|---|
| Q1 | "Partner means live" is reversed in every writer and reader, not just the middleware pin. | Rely on existing use cases (they hard-code partner rows to live). | 4.2 |
| Q2 | A claimed test landlord has a sandbox accounts row with no password: claimed, but no usable credential. All sign-in, reset and credential-linking paths refuse test landlords. | "No accounts row" (cannot be claimed); a random hidden password (still a credential). | 5.1, 5.3 |
| Q3 | Simulated approve grants all requested scopes. Body is {landlord_id} only. | Subset scopes (production cannot produce them). | 5.4 |
| Q4 | Test landlords get no mail and no redeemable claim tokens, on every send path. | Rely on .invalid mail bouncing. | 5.5 |
| Q5 | A same-partner test email label lets partners exercise 409 landlord_exists. | Ignore the email (fallback branch untestable); look up real accounts (probing). | 5.2 |
| Q6 | /test/* is public in the contract, not secret. Live keys get 404 after auth, before Go's rate limiter. | "Invisible" surface. | 5.6 |
| Q7 | Simulated review changes state only. No notices, outbox, webhooks or AI listing check for partner test data. | Reuse admin review side effects. | 6.1 |
| Q8 / C1 / W1 | Reset deletes objects first, then rows, then users, under an exclusive per-partner lock. Idempotency rows are found by a persisted partner_id + is_test stamp. Success means full cleanup; any failure is 503 and safe to repeat. | Best-effort media; accepting orphan objects; a new saga framework; prefetching key IDs from Bun (revoked keys are physically deleted); leaving rows to the age sweep. | 3, 6.2 |
| Q9 | Real consent endpoints refuse test connect requests server-side. | Page-only message. | 5.4 |
| Q10 | Bun verify fails closed on partner key mode/prefix; PartnerKeyAuth sets mode on every route; PartnerLandlordScope is deleted. | Default to live; keep the pin. | 4.1, 4.2 |
| Q11 | Test creates skip the global email reservation; reservation lookups and cleanup see live rows only. | Shared email index across modes. | 4.3 |
| Q12 | Admin route plus panel caller change now; the in-flight owner route must reuse the shared validator. | Implement the owner route here. | 4.1, 7.2 |
| Q13 | 100-landlord cap counted atomically in Bun under a per-partner lock. | Count grants in Go (misses standalone landlords; racy). | 6.3 |
| C2 | Automatic test purge skips partner-origin properties. | Let partner test data expire. | 4.4 |
| C3 | Ref index per mode; connect upsert never changes a grant's mode; reset removes revoked test grants. | Mode-blind upsert. | 4.3, 6.2 |
| C4 | Simulated approve/decline use the current redirect allowlist; expire stamps status and expiry; terminal requests answer 409 connect_request_status_conflict. | Unconditional redirect; 200 no-op on replay. | 5.4 |
| C5 | Simulated claim and review use the same grant chains as their real twins. | "Owned by caller" only. | 5.6 |
| C6 | Only Go's limiter is skipped for live keys on /test/*; Better Auth still records usage. | "No usage at all". | 5.6 |
| W2 | Contact phone guard applies to landlord test keys only; partner test keys write synthetic landlords' contacts. | Extend the guard to partner test keys (supply code would differ by mode); defer to sub-project 2. | 4.2 |
| C7 | Demand-side concealment is tested with seeded pg-test fixtures only. | Add demand-side test APIs now. | 10 |
| R1 | Claim rate-limit accounting uses simulated issuance rows in the existing token table. | A separate attempts table (second query); no accounting (different 429 timing). | 5.5 |
Existing foundations
Observed in the repository. The second card lists the reasons this design must change existing code (marked ⚠ in the source).
Reusable as-is
exists- Landlord API keys carry a required
metadata.modewithgrm_live_/grm_test_prefixes; absent or invalid mode fails closed (landlord-keys.routes.ts); Bun verify checks mode and exact prefix (internal.routes.ts:669-677). - Go's API key middleware sets
key_modefrommetadata.mode(api_key_auth_middleware.go:158-163); use cases compare it tois_test(e.g.usecase/listing.go:94). is_testexists onrental_properties,rental_listings,rental_property_external_refs; downstream readers follow the property's mode vialandlord_scope.go:18.- The listing state machine sends test submits straight to
live(entity/listing.go:151-152). - Admin review queue excludes test listings (
listing_repository.go:292); duplicate-address sweep skips test properties (usecase/duplicate_check_sweep.go:233-243); webhook capture skips test listings (usecase/webhook_capture.go:117). - Partner landlords are Bun
usersrows; Bun stampspartner_provisioning_id(internal.routes.ts:244-310,packages/auth-adapter/drizzle/0008_add_partner_provisioning_id.sql).
Must change
⚠- Partner keys carry no mode:
admin-partner-keys.routes.ts:170-175deletesmetadata.mode; Bun verify only checks agrp_prefix (internal.routes.ts:679-683);PartnerKeyAuthnever setskey_mode(partner_key_auth.go:80-89);PartnerLandlordScopepinsliveon per-landlord routes only (partner_scope.go:60-69). - Partner rows are hard-coded live:
usecase/property.go:144-145(IsTest = !origin.IsPartner && …),hiddenFromPartner(usecase/origin.go:75-80, 7 callers),|| prop.IsTestinusecase/property_lifecycle.go:106,324,495, and partner-only live filters inPropertyRepository.ListByOwnerandProofUseCase. rental_partner_grantsandrental_partner_connect_requestshave no mode.uq_rental_partner_grants_partner_refis(partner_id, partner_landlord_ref) WHERE status <> 'revoked';uq_rental_partner_grants_requested_email_provisioningis global across partners; another partner's abandoned reservation may be deleted (partner_provisioning.goinsertReservation).- "Claimed" means the user has any
accountsrow (landlord_claim_checker.go:22). - Real consent grants all requested scopes (
partner_consent.go:157), redirects only to a URI in the current allowlist (partner_consent.go:183), and sendsNotifyPartnerConnected. - Claim rate limits are counted from
rental_partner_claim_tokensrows (partner_claim_token_repository.go:53-54);token_hashisNOT NULL UNIQUE. - Photos and proofs keep
storage_keydirectly onrental_property_photos/rental_ownership_proofs(photo.go:292,proof.go:125), cascade with the property, and do not use the shareduploadstable. Removal APIs:PhotoStore.Remove(application/port/ports.go:277-278),ProofStore.Delete(proof_store.go:97). ListTestPurgeCandidatespurges every agedis_testproperty (property_repository.go:489-507).- Submit and review-forcing property edits queue the AI listing check with no test filter (
usecase/listing.go:349,usecase/lifecycle.go:89). - Partner key revoke physically deletes the Better Auth
apikeyrow (admin-partner-keys.routes.ts:354-368).rental_idempotencyis keyed only by(api_key_id, idempotency_key), with no partner or mode, written only byusecase/idempotent_executor.go. PUT …/contact/phonerefuses every test key with409 test_key_read_only(v1_contact_handler.go:46); written for landlordgrm_test_keys, never reached by partners because they were pinned live.
Mode model and request flow
Keys (Bun)
- Partner key creation requires
modeoftestorlive, stored asmetadata.mode. The prefix is computed per call asgrp_${mode}_, as landlord keys do. An absent or invalid mode fails closed with400. The strip-mode line is removed. - The validation lives in one shared Bun helper. Today only the admin route issues partner keys (
admin-partner-keys.routes.ts); the in-flight owner route (§7.2) must call the same helper. - A key's mode never changes after issuance.
- The panel admin key form and its client send
mode. Self-serve test keys are sub-project 3. - The per-key hourly allowance is unchanged; test and live keys each have their own.
Pipeline (Go)
PartnerKeyAuthsetskey_modeon the Echo context and request context for every partner route from the verified key's mode. There is no default.PartnerLandlordScopebecomes empty and is deleted. Its callers and tests move to the new behaviour.- Reversals, each in scope:
usecase/property.go:144-145: partner properties takeis_testfrom the key mode.hiddenFromPartner(usecase/origin.go) becomes "the property's mode differs from the key mode". All 7 callers keep calling it.usecase/property_lifecycle.go:106,324,495: replace|| prop.IsTestwith the mode comparison.PropertyRepository.ListByOwnerandProofUseCasepartner filters: filter by the key's mode, not "live only".- Implementation also audits external refs, gallery sync, photo, listing upsert, listing check form and downstream readers (tenancies, agreements, payment records, handover, contacts, enquiries, offers) for any other "partner ⇒ live" assumption.
- A cross-mode ID returns the resource's usual concealed
404. - Authentication, suspension (
403 partner_suspended), permissions, key ceiling, grant checks and rate limiting apply identically in both modes. GET /meaddsmode: "test" | "live".
Partner-scoped data
rental_partner_grantsandrental_partner_connect_requestsgainis_test BOOLEAN NOT NULL DEFAULT FALSE, set from the key mode at creation.uq_rental_partner_grants_partner_refbecomes(partner_id, is_test, partner_landlord_ref) WHERE status <> 'revoked'.- Grant resolution (
RequireGrant), landlord lists and connect-request reads filter by the caller's mode. A test key never sees a live grant, landlord or connect request, and vice versa. - Grant mode equals landlord kind. Test grants only reference test landlords of the same partner; live grants only reference non-test users. Enforced where grants are activated and connected.
- Mode is immutable.
Grants.Connect'sON CONFLICT (partner_id, landlord_user_id) DO UPDATE(partner_grant_repository.go:393) updates only whenis_testmatches, including when it reactivates a revoked row. A mismatch is an error, never a mode flip. - Email reservation is live-only.
uq_rental_partner_grants_requested_email_provisioninggainsAND is_test = FALSE.GetProvisioningByEmailandDeleteAbandonedReservationread and delete live rows only. Test creates skip the global email reservation step. They keep the partner/mode/ref reservation and the provisioning-ID stamp, so crash recovery and same-ref retry work as in production. - A test grant keeps the partner's real
requested_emailas information only. It never takes part in reservation, lookup, account creation or mail.
Isolation outside the Partner API
- Test data never reaches the public site, search, tenant apps, notices or the webhook pipeline.
- The admin review queue already hides test listings. Admin panels show test data only where they already show landlord test data, labelled as test.
- Automatic purge excludes partner data.
ListTestPurgeCandidatesaddsAND p.origin_partner_id IS NULL. Landlordgrm_testrows keep their 30-day expiry. Partner test data leaves only through reset. - Live partner requests behave exactly as today.
Test landlords, claim and consent
Test landlord identity (Bun)
A test landlord is a real users row so all landlord code paths work. One Bun Drizzle SQL migration adds:
test_landlordBOOLEAN NOT NULL DEFAULT FALSEtest_partner_idTEXT NULL, the creating partner, withCHECK (test_landlord = (test_partner_id IS NOT NULL))test_email_labelTEXT NULL, only whentest_landlord, with a unique partial index on(test_partner_id, test_email_label) WHERE test_landlord
- Reserved email
landlord+<uuid>@sandbox.invalid. It is never derived from partner input and can never receive mail. - No usable credential. A test landlord never has a password, OAuth link or token. When claimed it has one
accountsrow with providersandbox.sandboxis not a registered Better Auth provider, so nothing can sign in with it. - Auth guard on every path. Bun refuses test landlords at every sign-in method (one session-creation guard covers email, OAuth and any later method), at password reset and forgot-password, and at the real credential-link route (
/api/internal/partner/landlords/:id/credential). Go's real claim path also refuses them (claimEligible). - Go reads
test_landlordandtest_partner_idthrough the identity reads it already makes (ClaimTokens.LockIdentity,ConsentUsers.LockConsentIdentity).
New landlord with a test key
POST /landlordshas the same request, response,201/200andpartner_landlord_refidempotency as production.- Bun's internal landlord route takes a
testflag and the partner ID. In test mode it creates a test landlord and stores the normalizedemail(production normalization) astest_email_label. It never setsusers.emailfrom partner input and never looks up real accounts. - Exercising
landlord_exists. In test mode, if the label is already held by another test landlord of the same partner, Bun reports the existing user and Go answers409 landlord_exists, as production does for a registered email. A same-ref replay is checked first and never reaches the label check. A provisioning-ID stamp match is crash recovery, as in production. - The label namespace is per partner and test-only. It cannot reveal real accounts or other partners' data.
- The partner's real
emailis also kept on the grant asrequested_email, information only.
Simulated claim
POST /api/partner/v1/test/landlords/{landlord_id}/claimasks Bun to add thesandboxaccounts row. Bun takes the same per-landlord lock as real credential linking (ADR-0072).- The landlord now reads as claimed everywhere
claimedis read. Before it, submit returns409 landlord_unclaimed, as in production. Repeating returns409 already_claimed.
Existing landlord and consent
POST /api/partner/v1/test/landlordscreates a standalone, already-claimed test landlord (with thesandboxrow) and no grant. Optionalemailsets itstest_email_label. It stands in for "a landlord who already has an account".POST /connect-requestsbehaves as in production and returnsapprove_url.- Real consent refuses test requests. The real
Get,Decide(approve and decline) andSetupEmailreturn a typed error for a test connect request, before any state change, mail or grant. The consent page (routes/connect/[token].tsx) shows "This is a test request. Use the simulation endpoint." A real signed-in user can never approve or decline a test request. - Simulation endpoints:
POST /test/connect-requests/{id}/approvewith{landlord_id}. The landlord must be a test landlord of the same partner. The grant gets all requested scopes, as in production.POST /test/connect-requests/{id}/decline.POST /test/connect-requests/{id}/expiresetsstatus = 'expired'andexpires_atto database time.
- Approve and decline require the request to be pending and unexpired. Any terminal request — approved, declined or expired, including a replay of the same action — returns
409 connect_request_status_conflict. - Approve and decline return
redirect_uriwith production's query parameters (connect_request_id,status) only when the URI is in the partner's current allowlist, as production does. Otherwise no redirect is returned. - Re-approval replaces the grant's complete scope set, as in production. It never changes the grant's mode.
No mail, no redeemable claim tokens
Test landlords never receive mail or a redeemable claim token. The rule is enforced at each send path by the landlord's kind, not by mail bouncing:
| Path | Test-mode behaviour |
|---|---|
POST /landlords → claims.issueInTx + deliver | Records a simulated issuance row; no secret, no mail. |
POST /landlords/{id}/claim-email → ResendClaim | Same response and rate limits as production; records a simulated issuance row; no secret, no mail. |
Consent approve → NotifyPartnerConnected | Unreachable for test requests; simulated approve sends nothing. |
Consent SetupEmail | Refused for test requests. |
| Any generic auth mail (verification, reset, magic link) | Refused for test landlords. |
Guard on simulation endpoints
- Better Auth's
verifyApiKeystill records a live-key request, as for any authenticated call; only Go's hourly limiter is skipped. - The routes are documented in the contract. They are not secret, only unusable with a live key.
- Simulation acts only on the calling partner's test landlords, test grants and test connect requests; anything else is the resource's concealed
404. - Permissions and chains match the real twin:
| Endpoint | Key permission | Grant |
|---|---|---|
POST /test/landlords/{landlord_id}/claim | landlords:write | Any active test grant (same chain as claim-email) |
POST /test/landlords | landlords:write | — |
POST /test/connect-requests/{id}/approve|decline|expire | landlords:write | — |
POST /test/landlords/{landlord_id}/listings/{id}/review | listings:write | listings:write |
POST /test/reset | landlords:write | — |
Listing review simulation and reset
Listing submit and review
- Partner-channel test listings go to
pending_reviewon submit, after the same checks as production: declaration, ownership proof and claimed landlord. Landlordgrm_test_submits keep going straight tolive. - No AI listing check for partner test data. Every enqueue path skips partner-owned test listings: submit, resubmit, and review-forcing property edits (
usecase/listing.go:349,usecase/lifecycle.go:89). Landlordgrm_testbehaviour is unchanged. The contract says the listing check does not run in Testing. - Simulation:
POST /test/landlords/{landlord_id}/listings/{id}/reviewwith{decision: "approve" | "reject", reason?}.approvesetsliveand assigns the slug as production does. The listing is visible to the partner, never public.rejectsetsrejectedand storesreasonasreview_reason(reasonrequired for reject).- Reviewer metadata (reviewed time, reviewer) and the audit row record the partner service user as actor. No admin reviewer is invented.
- No approval notice, outbox row or webhook is created.
- Any status other than
pending_reviewreturns409 listing_status_conflict.
- Test properties stay excluded from the duplicate-address sweep, so test keys cannot probe real addresses.
duplicate_under_reviewcannot be exercised in Testing; the contract says so.
Reset
POST /api/partner/v1/test/reset deletes all of the calling partner's test data:
- test landlords whose
test_partner_idis the partner, including standalone ones and leftovers; - the partner's test grants (all statuses, including revoked) and test connect requests;
- test properties owned by those landlords, with their cascaded listings, photos, proofs, external refs, duplicate hints/flags and listing checks;
- stored photo and proof objects;
rental_contactsand claim-token rows (real or simulated) of those landlords;- every
rental_idempotencyrow stampedpartner_id = caller AND is_test = true, including claim/in-progress rows and rows of keys that were revoked and physically deleted.
Test keys, live data, audit history and other partners' data are untouched. Shared uploads rows are not touched: rental photos and proofs do not use them.
- Take the exclusive lock.
- Read storage keys
Read the storage keys of the partner's test photos and proofs.
- Remove objects
PhotoStore.Remove,ProofStore.Delete. A missing object counts as success. Any other storage failure returns503 media_unavailable; rows and keys stay, so a repeat finds them. - Delete rental rows
One Go transaction deletes the rental rows listed above.
- Delete test landlords
Bun deletes them through an internal route that only deletes users with
test_landlord = trueand the namedtest_partner_id. - Release the lock.
A Go failure in step 4 or a Bun failure in step 5 returns 503. Every step is safe to repeat. Success returns 200 with counts of what was removed, and means everything listed is gone.
Bounds
-
test_landlord_capcount(users WHERE test_landlord AND test_partner_id = $partner)under a per-partner advisory lock, same transaction as create 100
- The count includes standalone landlords and leftovers from an incomplete reset, until a reset succeeds.
- A same-ref replay or a label conflict creates no user and is not refused by the cap.
- Further creation through
POST /landlordsorPOST /test/landlordsreturns409 test_landlord_limit_reacheduntil the partner resets. - All other limits match production.
Contract and dependencies
Contract (backend/go/openapi/partner-v1.yaml)
- Adds the seven test-only operations (claim, test landlord creation, connect approve/decline/expire, listing review, reset), each marked
x-test-only: true, with the live-key404 route_not_foundand the permissions above. - Documents key
mode, thegrp_test_/grp_live_prefixes and per-mode isolation; addsmodetoGET /me. - States: test properties skip duplicate checks; the listing check does not run in Testing; partner test data is never purged automatically, only by reset; test landlords receive no email.
| Code | Status | Where |
|---|---|---|
test_landlord_limit_reached | 409 | New. POST /landlords, POST /test/landlords |
connect_request_status_conflict | 409 | New. Simulated approve, decline, expire |
route_not_found | 404 | Existing. Live key on /test/* |
already_claimed, landlord_unclaimed, landlord_exists, listing_status_conflict, rate_limited | 409/429 | Existing. Documented on the test operations that return them |
invalid_api_key | 401 | Existing. Now also a partner key with missing/invalid mode or mismatched prefix |
auth_unavailable, media_unavailable | 503 | Existing. Reset when Bun or storage fails |
New codes go into x-error-codes and the ErrorCode enum. Backend contract-drift tests cover the new operations. The browser-only consent error is part of the rental session API, not the partner contract. The landlord API contract and docs are unchanged.
Dependencies on in-flight work
- Self-serve owner keys. The owner issuer is planned in
backend/bun/openspec/changes/partner-self-serve-keys; the portal design plansPOST /api/partner-portal/keysand currently omitsmode(frontend/solidstart/openspec/changes/partner-self-serve-portal/design.md:27-29,39). Prerequisite: that work must call the shared mode validator and sendmode: "live"until sub-project 3 adds a selector. This spec does not implement it. - Developer docs. The approved developer integration spec says partners test in UAT with no test/live key mode. Sub-project 3 amends it after this ships; this spec does not edit it.
- Webhooks. Stay live-only. Capture already skips test listings; this sub-project adds a regression check that test activity captures nothing. Test webhook endpoints are sub-project 2.
Rejected for the whole design
- Separate sandbox deployment, mode header, separate partner records per mode, auto-approve, timed decisions, automatic expiry of partner test data.
- A generic saga or cleanup framework for reset.
- Implementing the self-serve owner key route or demand-side simulation here.
Affected files
Go (backend/go/internal/…)
| File | Change |
|---|---|
api/http/middleware/partner_key_auth.go | Set key_mode on every partner route; no default. |
modules/rental/adapter/inbound/http/partner_scope.go | Delete PartnerLandlordScope. |
modules/rental/adapter/inbound/http/partner_routes.go | Remove the scope; add mode guard and /test/* routes in the guard order. |
modules/rental/adapter/inbound/http/partner_landlord_handler.go, partner_connect_handler.go, new test simulation handler | Simulation endpoints; GET /me mode. |
modules/rental/adapter/inbound/http/partner_consent_handler.go | Typed test-request refusal. |
modules/rental/adapter/inbound/http/v1_contact_handler.go | Scope the read-only guard to landlord API test keys. |
modules/rental/application/usecase/property.go, origin.go, property_lifecycle.go, proof.go, listing.go, lifecycle.go, listing_check_queue.go (or its callers), review.go (state helpers only) | Mode reversals; listing-check skip; simulated review. |
modules/rental/application/usecase/partner_provisioning.go, partner_claim.go, partner_consent.go, partner_connect.go, partner_grants.go | Test create, simulated issuance, consent refusal, allowlist redirect, expire. |
modules/rental/adapter/outbound/persistence/postgresql/partner_grant_repository.go, partner_connect_request_repository.go, partner_claim_token_repository.go, property_repository.go, idempotency_repository.go | Mode filters, immutable upsert, live-only reservation, simulated rows, purge exclusion, idempotency stamp columns, reset deletes. |
modules/rental/application/usecase/idempotent_executor.go, domain/entity/idempotency.go | Stamp partner_id and is_test on every created row. |
modules/rental/adapter/outbound/client/bun_partner_client.go | Test flag, simulated claim, test landlord delete. |
shared/infrastructure/database/postgresql/migrations/migrator_rental.go | is_test columns, index changes, claim-token simulated, rental_idempotency.partner_id + is_test. |
modules/rental/module.go | Wiring. |
Bun (backend/bun/…)
| File | Change |
|---|---|
apps/monolith/src/api-gateway/routes/admin-partner-keys.routes.ts + shared validator | Required mode, grp_${mode}_ prefix. |
apps/monolith/src/api-gateway/routes/internal.routes.ts | Verify fail-closed; test landlord create with label and cap lock; sandbox claim; test landlord delete; credential-link refusal. |
apps/monolith/src/config/di-container.ts | New user fields; session-creation and reset guards. |
packages/auth-adapter/schema.ts, packages/auth-adapter/drizzle/0009_*.sql | test_landlord, test_partner_id, test_email_label. |
Frontend and contract
| File | Change |
|---|---|
frontend/solidstart/apps/panel/src/features/rental-admin/partnerKeys.ts, routes/admin/rental/partners/[id].tsx | Send mode (admin issues test and live keys). |
frontend/solidstart/apps/rental/src/routes/connect/[token].tsx, features/rental/api/connect.ts, routes/api/rental/connect/[...path].ts | Show the test-request message. |
backend/go/openapi/partner-v1.yaml | Contract and its drift tests. |
Verification
Go integration tests (disposable pg-test, :55432)
- Cross-mode concealment for every partner resource family: landlords, grants, connect requests, properties, listings, photos, proofs, external refs, contacts. Tenancies, agreements, payment records, handover, viewing requests and offers use seeded fixtures owned by a test-mode property; no demand-side API is added.
- Every pipeline reversal: a partner test key creates
is_testrows and reads them; a live key reads them as404; landlord/api/v1and panel behaviour unchanged. - Per-mode
partner_landlord_refuniqueness;Grants.Connectrefuses a mode change, including on a revoked row. - A test create with email X does not affect a live create or reservation with email X, and never deletes a live reservation.
/test/*: no key401; live key404 route_not_foundwith Go's limiter not charged; suspended partner403; simulation rejects live landlords, live grants, other partners' test resources and revoked test grants.- Test create: same responses as production; label collision
409 landlord_exists; same-ref replay wins over the label; no mail; simulated issuance row written; immediateclaim-emailreturns the same429timing as live; simulated rows can never be claimed. - Simulated claim: submit
409 landlord_unclaimedbefore, success after; repeat409 already_claimed;emailVerifiedstays false. - Connect: simulated approve grants all requested scopes; decline; expire sets status and expiry; every terminal replay
409 connect_request_status_conflict; redirect only for a currently allowlisted URI; re-approval replaces scopes. Real sessionGet/Decide/SetupEmailrefuse a test request with no state change or mail. - Review: test submit reaches
pending_reviewand queues no listing check (also for resubmit and review-forcing edits); approve setslivewith a slug, partner actor, no notice/outbox/webhook; reject storesreview_reason; non-pending409 listing_status_conflict;grm_testsubmits still goliveand still queue the check. - Reset: removes only the caller's test data, including revoked test grants and leftover landlords; live data, audit history and other partners' data survive. Storage failure at step 3 keeps rows and returns
503; Go or Bun failure returns503; a repeat completes. A test write waits for a running reset. - Idempotency stamp: partner test requests stamp
partner_idandis_test = trueon claim/in-progress and completed rows; live partner rows stampis_test = false; landlord/api/v1rows havepartner_idnull. Reset removes the caller's test rows, including those of a revoked (deleted) key, and keeps live rows, other partners' rows and landlord rows. Replay and conflict behaviour is unchanged for live and/api/v1. - Purge: an aged partner test property survives
PurgeTestProperties; an agedgrm_testproperty is still purged. - The 100-landlord cap under parallel creates; leftovers count until reset.
- Test activity triggers no webhook capture.
- Partner test contact: with an active test grant,
PUT …/contact/phonesucceeds andGET …/contactreads it back for the synthetic landlord only; no real user's contact changes; a live key cannot read it; without an active same-mode grant the request is the concealed404. A landlordgrm_test_key still gets409 test_key_read_only.
Bun tests
- Partner key creation fails closed without
modeor with a mismatched prefix; prefix isgrp_${mode}_. - Verify returns
401 invalid_api_keyfor a partner key with missing/invalid mode or mismatched prefix. - Test landlords cannot sign in by any method, reset a password, trigger auth mail, or link a real credential. The
sandboxrow is not a usable provider. - The cap is atomic per partner; the label is unique per partner among test landlords.
- The internal delete route removes only test landlords of the named partner.
Frontend tests
Panel key form sends mode; the consent page shows the test-request message.
UAT smoke run
With real keys, after confirming GO_ENV=development and the UAT database host:
- Test key journey
With a
grp_test_key:GET /meshowstest→ create landlord → simulate claim → property, ownership proof, listing → submit (pending_review) → simulate approve (live, not on the public site) → create a standalone test landlord → connect request → simulate approve → reset. - Live key isolation
With a
grp_live_key:/test/*returns404; none of the test data is visible. - Clean up
Revoke the smoke-run keys afterwards.
Non-goals
- Demand-side simulation and test webhook endpoints (sub-project 2).
- Self-serve test key UI, the owner key route and docs (sub-project 3 and in-flight work).
- A separate sandbox deployment.
- Simulation of duplicate-address holds.
- Changes to landlord
grm_testbehaviour. - Admin tooling for partner test data beyond existing test labels.
Approval gate
The user approved the environment model (test mode in each deployment), the three-way decomposition, the test-landlord approach, simulated review, fixed-mode keys, reset, and all four conversational design sections. That approval permitted this written spec, not implementation.