feat(iap): POC Apple in-app purchase module for backend functions

[eyalizhaki]

Proof of concept — not for merge. Both halves of this feature are exploratory: the
native mobile shell that would drive it, and this server side. Opened to make the
approach reviewable and to surface the decisions it forces, not because it is ready to
ship.

Problem

The mobile shell speaks StoreKit 2 on the device, so a purchase can be made there. But
nothing on the server proves a purchase happened, and nothing tracks a subscription over
time — renewals, billing grace periods, billing retry, refunds, revocations and plan
changes have no server side at all. Without that, a paid feature can only be gated on
what the client claims, which is not evidence of anything.

What this explores

An iap module covering the server half end to end: certificate-chain and signature
verification of Apple's signed tokens, the App Store Server Notifications v2 webhook,
the two device paths (recordTransaction, syncEntitlements), entitlement reads derived
from stored tokens, and three App Store Server API calls. 17 public methods; the one a
feature gate would use is hasActiveSubscription(userId), which never throws.

Three decisions worth a reviewer's attention, because they are the ones that would be
expensive to revisit later:

• Verification is Apple's own app-store-server-library. An earlier revision carried a
  second, dependency-free WebCrypto implementation as a fallback, on the theory that Apple's
  library might not survive the Cloudflare Workers bundler. It does — verified end to end on
  a production Base44 app against a real sandbox notification — so the fallback and its
  ~1 300 lines of hand-rolled DER, X.509, chain and JWS code have been removed. Apple's
  library is also stricter than what it replaced: it checks the intermediate's CA basic
  constraint, which the hand-rolled version did not.
• The runtime sits behind a new @base44/sdk/iap subpath export, so browsers and
  React Native never download certificate code. The types are re-exported from the main
  entry as export type only, so dist/index.js is byte-identical and the docs pipeline
  still sees the surface.
• The exports map keeps deep dist/ paths resolving. App templates import
  @base44/sdk/dist/utils/axios-client without an extension, and exports resolution does
  no extension guessing — verified by packing the tarball and importing every path from a
  throwaway consumer.

Storage note: Base44 entities have no upsert, unique constraint or compare-and-swap, so
newest-wins writes are built on updateMany's server-evaluated query as a guard, and
reads tolerate duplicate rows. Every workaround is isolated in src/iap/store/ behind one
interface, so a real upsert would be a one-file change.

What would have to be settled before any of this ships

• Sandbox versus production. testMode is a single global boolean, so an app cannot
  accept both at once. App Review testers buy with sandbox accounts against the production
  build, so with it off their purchase is rejected and with it on anyone can unlock paid
  features for free. This needs a design decision, not a code change.
• Entity provisioning. An SDK cannot create a Base44 entity, so an app would have to
  create four of them from the exported IAP_ENTITY_SCHEMAS before anything can be
  stored. Platform-provided entities would be better than asking generated code to do it.
• An upsert on updateMany. One flag would delete most of src/iap/store/ and the
  only race that remains open.

Testing

npm run test:types, npm run test:unit, eslint src and npm run build all pass. The
unit suite goes from 273 tests to 574; 301 of them are new.

Notable coverage:

• Apple Root CA G3's own signature verified end to end through the new parser, using the
  real certificate bytes downloaded from apple.com, with all three embedded roots checked
  byte-exact.
• Verification rejection cases against chains minted at test time — wrong root, wrong
  chain length, missing Apple marker extensions, wrong algorithm, tampered signature,
  tampered payload, expired certificate, mismatched curve. The test chain is deliberately
  cross-curve (P-384 root, P-256 intermediate) to mirror Apple's real shape.
• All 33 notification type and subtype combinations, plus duplicate delivery, out-of-order
  delivery, and a type invented after this code was written.
• A full sandbox subscription lifecycle: initial buy, accelerated renewal, grace period,
  expiry.
• npm pack plus install into a throwaway consumer, importing all four resolution paths.
• A real captured sandbox notification verified against Apple's actual trust chain — real
  Apple Root CA G3, real WWDR G6 intermediate, real receipt-signing leaf — plus its
  rejection cases (wrong bundle id, test mode off, one signature byte flipped).

Verified on a production Base44 app: a real Apple sandbox TEST notification was
delivered to a backend function running this code and handled correctly, which is what
settled the Workers question. Still untested: an actual purchase or renewal, which needs
App Store Connect products and a TestFlight build.

Known gaps

• OCSP (onlineChecks) is off. Apple's library supports it, but enabling it also switches
  certificate validity from the payload's own signedDate to the current time, which would
  make stored tokens stop verifying over time.
• Telemetry is deliberately omitted — the normalized event catalog and the per-notification
  audit trail ship, but nothing points at a sink that does not exist yet.
• Whether the backend honours a caller-supplied record id is undetermined, so the store
  defaults to the mode that is correct either way. Confirming it would remove a round trip
  per insert.

Sources

• Apple: App Store Server Notifications v2,
  App Store Server API,
  StoreKit 2, and WWDC23 session
  10143 for the verification steps.
• Root certificates from Apple PKI.
• The deep-dist/ import hazard is recorded in commit 4ab4f9a's own message.

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.48-pr.276.4f760f9

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.48-pr.276.4f760f9"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.48-pr.276.4f760f9"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.48-pr.276.4f760f9
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}