In-app purchases for a Codex-built web app: RevenueCat, WebViewGold and a pull request you can trust

# server/billing/AGENTS.md

## Invariants
- Entitlements live in Firestore at entitlements/{uid} and are written ONLY by
  webhooks: /webhooks/stripe (source "stripe") and /webhooks/revenuecat
  (source "revenuecat"). No client code, callable function or admin page sets premium.
- Every access check reads entitlements/{uid} on the server. Never trust a flag,
  cookie or localStorage value from the device.
- The RevenueCat app user ID is the Firebase uid, passed as external_id in
  revenuecat://purchase?external_id=...&product=... (never the email address).
- Webhooks: compare the Authorization header with REVENUECAT_WEBHOOK_AUTH, dedupe by
  event.id in billingEvents/{eventId}, answer 200 quickly. Tests use fixtures in
  server/billing/__fixtures__, never live RevenueCat or Stripe APIs.
- Inside the native app (isNativeApp()), digital goods use the bridge only:
  revenuecat://purchase, revenuecat://launchPaywall (iOS only),
  restoreinapppurchases://, cancelinapppurchase://.
  No Stripe links, no card forms, no "cheaper on the web" copy.
- Product IDs come from src/config/products.ts, never hardcoded in components.

## Review guidelines
- P0: any code path that grants or extends premium outside the two webhooks.
- P0: a webhook handler that does not check the Authorization header.
- P1: a Stripe checkout, price link or external payment URL for a digital product
  that is reachable when isNativeApp() is true.
- P1: a paywall without price, billing period, renewal terms, Terms and Privacy
  links, or without a Restore Purchases control.

// server/billing/revenuecat.js (Express + firebase-admin)
import express from "express";
import { getFirestore, FieldValue } from "firebase-admin/firestore";

const db = getFirestore();
export const revenuecatRouter = express.Router();
const GRANT = new Set(["INITIAL_PURCHASE", "RENEWAL", "UNCANCELLATION",
  "PRODUCT_CHANGE", "NON_RENEWING_PURCHASE", "SUBSCRIPTION_EXTENDED"]);

revenuecatRouter.post("/webhooks/revenuecat", express.json(), async (req, res) => {
  if (req.get("Authorization") !== process.env.REVENUECAT_WEBHOOK_AUTH) {
    return res.status(401).end();
  }
  const event = req.body && req.body.event;
  if (!event || !event.id) return res.status(400).end();
  if (event.type === "TEST") return res.status(200).end();

  const seen = db.collection("billingEvents").doc(event.id);
  if ((await seen.get()).exists) return res.status(200).end(); // duplicate delivery

  const uid = event.app_user_id; // = external_id from revenuecat://purchase
  if (uid) {
    const expiresAt = event.expiration_at_ms ? new Date(event.expiration_at_ms) : null;
    const ref = db.collection("entitlements").doc(uid);
    if (GRANT.has(event.type)) {
      await ref.set({ premium: true, source: "revenuecat", store: event.store,
        productId: event.product_id, expiresAt, sandbox: event.environment === "SANDBOX",
        updatedAt: FieldValue.serverTimestamp() }, { merge: true });
    } else if (event.type === "EXPIRATION") {
      await ref.set({ premium: false, expiresAt, updatedAt: FieldValue.serverTimestamp() }, { merge: true });
    }
    // CANCELLATION and BILLING_ISSUE: access usually runs until EXPIRATION.
  }
  await seen.set({ type: event.type, uid: uid || null, at: FieldValue.serverTimestamp() });
  res.status(200).end();
});