@kilnjs/payments-appstore

App Store Server Notifications V2 for KilnJS, verified against Apple's own certificate chain. No SDK.

yarn add @kilnjs/payments @kilnjs/payments-appstore

// app.config.ts
import { payments } from "@kilnjs/payments";
import "@kilnjs/payments-appstore";

| option | environment | | | --- | --- | --- | | bundleId | APPSTORE_BUNDLE_ID | required. Checked against every notification | | root | | Apple's G3 root, overridable for a test or a future one | | keyId | APPSTORE_KEY_ID | for looking a subscription up | | issuerId | APPSTORE_ISSUER_ID | as above | | privateKey | APPSTORE_PRIVATE_KEY | as above | | environment | APPSTORE_ENVIRONMENT | production, or sandbox | | timeout | APPSTORE_TIMEOUT_MS | 10000 |

Verifying a notification needs no secret at all, which is the interesting part: a notification proves itself with Apple's chain. The key above is only for asking Apple questions, so a server that merely listens holds no credential.

What verification checks

A notification is a JWS whose header carries the chain that signed it, leaf first. That is convenient and dangerous in equal measure: anybody can put a chain in a header, so a verifier that checks the signature against the leaf it was handed accepts a payload anybody can mint. All four of these are checked, and each has a forgery of its own in the tests:

• the leaf's signature over the payload, with ES256 read as raw r || s, which is the one incompatibility nobody finds by reading;
• each certificate signed by the next one up;
• the top of the chain being the root this server pins;
• every certificate being inside its own validity window.

The transaction inside a notification is signed separately and verified the same way: the payload carrying it does not vouch for it, Apple's chain does.

A notification about another bundle is refused even though Apple signed it: acting on one would grant an entitlement here for a purchase made in a different app.

What it maps

| Apple | kind | | --- | --- | | SUBSCRIBED, ONE_TIME_CHARGE | purchased | | DID_RENEW | renewed | | DID_FAIL_TO_RENEW | billing_failed | | EXPIRED, GRACE_PERIOD_EXPIRED | expired | | REFUND, REVOKE | refunded | | DID_CHANGE_RENEWAL_STATUS + subtype | cancelled or recovered | | anything else | other, with both payloads whole in raw |

The type and the subtype together are what mean something, which is why the pair is mapped rather than the type.

externalId is the original transaction id, the one identifier that survives every renewal: the per-renewal id would make each renewal look like a new purchase and every subscription look a month old.

Who bought it is appAccountToken and nothing else. Apple deliberately tells a server nothing about the person behind an Apple ID, so an application that wants to know must set that token when it starts the purchase.

Verifying

yarn verify   # ts:check, lint, build, exports:check, test

Apple is never reached. The suite builds its own root, intermediate and leaf with openssl, signs payloads with the leaf, and forges each part a forger would - including a chain that holds together perfectly and ends at the wrong root, which is the forgery that matters.