kit: harden the Amazon RVS lane — sandbox bypass, expiry assumption, state staleness

[hyochan]

Companion to #310, from the same internal audit. The Amazon (Fire OS RVS) verify lane is wired end to end (store:"amazon" intake → verifyAmazonReceiptInternalV1 → RVS → persistence with store:"amazon"), but it has never been manually verified against a real RVS sandbox and carries the following issues.

Major

1. Client-controlled sandbox:true bypasses the shared secret and is invisible in the response

When the request sets sandbox:true, the AmazonSharedSecretNotConfiguredError gate is skipped and the RVS Cloud Sandbox URL is built with the placeholder secret "iapkit-sandbox" — no developer-held credential involved. The public verify response carries no environment field, so a consumer cannot distinguish a sandbox verification from production. A holder of the shipped client API key can generate an App Tester pseudo-receipt on a Fire device and obtain {isValid:true, state:"ENTITLED"}.

• packages/kit/convex/purchases/amazon.ts:159-183
• packages/kit/server/api/v1/route-response-schemas.ts (no environment field)

Fix direction: echo an environment field in the amazon verify response and store it as a first-class column; gate sandbox verification behind an explicit project setting so production projects can disable it.

2. Subscription expiry rests on an unverified cancelDate assumption

mapAmazonReceiptState returns CANCELED only when cancelDate is set; otherwise SUBSCRIPTION maps unconditionally to ENTITLED. renewalDate, gracePeriodEndDate, and term are parsed but never consulted (a test locks in "renewalDate in the past → ENTITLED"). This is correct only if RVS reliably sets cancelDate at natural expiry — never confirmed against a real receipt. If wrong, expired Amazon subscriptions verify as ENTITLED forever.

• packages/kit/convex/purchases/amazon.ts:94-112, amazon.test.ts:53-60

3. No lifecycle source at all — unbounded state staleness

Apple has ASN v2, Google has RTDN, Horizon has a 6-hour reconciler cron; Amazon has neither a webhook receiver nor a reconciler. Post-verification state never updates.

• packages/kit/server/api/v1/webhooks.ts:40-77, packages/kit/convex/crons.ts:69-79

Test coverage (see also #312)

verifyAmazonReceiptInternalV1 has zero test coverage (23% file stmts; the 7 existing tests cover only the three pure helpers). Untested: the RVS status-code ladder (400/497→INAUTHENTIC, 410→CANCELED, 496→verification error), retry predicate, 10s timeout, sandbox URL segment, saveFailedReceipt persistence, happy-path save wiring. Suggested: fetch-stubbed suite + a store:"amazon" save-path integration test mirroring save-purchase-idempotency.test.ts; also assert route→action argument forwarding (incl. sandbox passthrough) in routes.test.ts.

Minor

• No app-identity binding: RVS authenticates developer-level secret + (userId, receiptId); any receipt from the same Amazon developer account verifies. expectedProductId is not accepted for the amazon variant.
• Amazon purchases count only toward total/valid/invalid in purchaseStats (no per-store counter) and never appear in the /v1/subscription status/entitlements lane.

Manual E2E checklist (requires Fire device + Amazon developer account)

• Run a real RVS sandbox verification end to end (App Tester)
• Capture real receipt JSON for an expired and a grace-period subscription; confirm whether cancelDate is set at natural expiry; convert captures into fixtures
• Confirm production RVS behavior with the real shared secret

🤖 Findings from an internal multi-agent audit; file:line references verified against main at the time of filing.

[hyochan]

Resolved by #313.

Amazon Cloud Sandbox now requires an explicit project setting and always uses an IAPKit placeholder instead of the production shared secret. Handled results and stored rows carry Sandbox / Production provenance, Amazon accepts expectedProductId, and a strict 200 response must include a matching non-empty receiptId, a valid productId / productType, and cancelDate as null or a finite number.

Active purchase snapshots become due after 48 hours for a bounded RVS recheck. Deterministic 400/497/410 verdicts update the row; configuration, timeout, network, throttling, 5xx, and malformed-response failures preserve the last authoritative state and reschedule through a compare-and-set lease. The worker handles at most 20 rows per five-minute tick, so 48 hours is a due cadence rather than a completion guarantee.

Amazon expectedProductId and the optional environment result are wired through the GraphQL SSOT, Apple, Google, React Native, Expo, Flutter, Godot, KMP, and MAUI. Published Kotlin constructor compatibility is preserved. Package metadata is intentionally unchanged in this feature PR; the fields are annotated for future OpenIAP Spec 3.2.0, openiap-apple 3.2.0, and openiap-google 3.3.0 releases, with framework releases handled by their own workflows.

The Purchases dashboard now includes Amazon store counts, and a bounded idempotent migration is documented for self-hosted deployments with existing rows. Action, persistence, status, retry, timeout, CAS, SDK parity, dashboard, and route-forwarding tests were added. Live App Tester and production RVS E2E still require an Amazon developer account/device fixture.