A Gated Claude BFF at the Edge

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

/**
 * Env: the Worker's configuration surface.
 *
 * Two independent gates can be turned on by configuration:
 *
 *   StoreKit  (entitlement): set ALLOWED_BUNDLE_IDS + APPLE_ROOT_CA_SHA256.
 *   App Attest (authenticity): set APP_ATTEST_TEAM_ID + APP_ATTEST_BUNDLE_ID.
 *
 * If neither is configured the Worker refuses to run (500). If both are
 * configured a request must clear both.
 *
 * On top of the gates, spend controls decide what an entitled caller may
 * spend: a model allowlist, a per-request max_tokens cap, and a per-caller
 * daily token budget. Each is optional and configuration-driven too.
 */
export interface Env {
  /** Anthropic API key. Set as a secret: `wrangler secret put ANTHROPIC_API_KEY`. */
  ANTHROPIC_API_KEY: string;

  // --- StoreKit entitlement gate (active when both are set) ---

  /** Comma-separated allowlist of app bundle IDs, e.g. "com.example.app". */
  ALLOWED_BUNDLE_IDS?: string;
  /** Comma-separated allowlist of product IDs. Empty/unset = accept any product. */
  ALLOWED_PRODUCT_IDS?: string;
  /** Hex SHA-256 of the DER-encoded "Apple Root CA - G3" certificate.
   *  Obtain and verify from https://www.apple.com/certificateauthority/ */
  APPLE_ROOT_CA_SHA256?: string;

  // --- App Attest authenticity gate (active when both are set) ---

  /** Apple Developer Team ID the app ships under, e.g. "ABCDE12345". */
  APP_ATTEST_TEAM_ID?: string;
  /** Bundle ID the attestation must be bound to, e.g. "com.example.app". */
  APP_ATTEST_BUNDLE_ID?: string;
  /** The "Apple App Attestation Root CA" certificate (PEM or base64 DER).
   *  The attestation's x5c omits the root, so a fingerprint cannot anchor the
   *  chain; the verifier needs the certificate itself. Obtain and verify from
   *  https://www.apple.com/certificateauthority/ */
  APP_ATTEST_ROOT_CA?: string;

  // --- Spend controls (each optional) ---

  /** Comma-separated allowlist of model IDs the proxy will forward. */
  ALLOWED_MODELS?: string;
  /** Upper bound on max_tokens per request, e.g. "4096". */
  MAX_TOKENS_LIMIT?: string;
  /** Tokens each caller may request per UTC day, e.g. "200000". Debited with
   *  the request's max_tokens before forwarding. */
  DAILY_TOKEN_BUDGET?: string;

  // --- Proxy configuration ---

  /** Comma-separated allowlist of upstream paths. Defaults to "/v1/messages". */
  ALLOWED_UPSTREAM_PATHS?: string;
  /** Anthropic API version header. Defaults to "2023-06-01". */
  ANTHROPIC_VERSION?: string;

  // --- Durable Object bindings (declared in wrangler.toml) ---

  /** Per-caller daily token budget. */
  TOKEN_BUDGET?: DurableObjectNamespaceLike;
  /** Registered App Attest public keys and assertion counters, per keyId. */
  ATTEST_KEYS?: DurableObjectNamespaceLike;
  /** One-time App Attest registration challenges. */
  ATTEST_CHALLENGES?: DurableObjectNamespaceLike;
  /** Revocation record per originalTransactionId, written by the webhook. */
  REVOCATIONS?: DurableObjectNamespaceLike;
}

/**
 * Minimal structural type for a Durable Object namespace binding, so the
 * bundle type-checks and tests run with zero installs instead of depending on
 * `@cloudflare/workers-types`. The real binding satisfies this shape.
 */
export interface DurableObjectNamespaceLike {
  idFromName(name: string): unknown;
  get(id: unknown): {
    fetch(input: string, init?: RequestInit): Promise<Response>;
  };
}

export const ANTHROPIC_BASE = "https://api.anthropic.com";
export const DEFAULT_ANTHROPIC_VERSION = "2023-06-01";
export const DEFAULT_UPSTREAM_PATHS = "/v1/messages";

/** Header carrying the StoreKit 2 signed transaction (JWS). */
export const TRANSACTION_HEADER = "X-IAP-Transaction";
/** Header carrying the App Attest assertion (base64). */
export const ASSERTION_HEADER = "X-App-Attest-Assertion";
/** Header carrying the App Attest key identifier the assertion was signed with. */
export const KEY_ID_HEADER = "X-App-Attest-Key-Id";

/** Route Apple's App Store Server Notifications V2 POSTs here. */
export const NOTIFICATIONS_PATH = "/apple/notifications";
/** Route the app's one-time App Attest key registration here. */
export const REGISTER_PATH = "/app-attest/register";
/** Route the app's registration-challenge requests here. */
export const CHALLENGE_PATH = "/app-attest/challenge";

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# Example Wrangler config for the gated Claude BFF Worker.

name = "claude-bff-example"
main = "worker.ts"
compatibility_date = "2026-06-01"

# Public, non-secret configuration:
[vars]
# --- StoreKit entitlement gate (active when both are set) ---
# Comma-separated bundle IDs your app(s) ship under.
ALLOWED_BUNDLE_IDS = "com.example.app"
# Optional: restrict to specific product IDs. Empty = accept any product.
ALLOWED_PRODUCT_IDS = ""
# Hex SHA-256 of the DER-encoded "Apple Root CA - G3" certificate.
# Obtain and verify from https://www.apple.com/certificateauthority/
APPLE_ROOT_CA_SHA256 = "PUT_THE_PINNED_FINGERPRINT_HERE"

# --- App Attest authenticity gate (active when both are set) ---
# Leave blank to run StoreKit only. Set both to require a genuine app instance.
APP_ATTEST_TEAM_ID = ""
APP_ATTEST_BUNDLE_ID = ""
# The "Apple App Attestation Root CA" certificate (PEM or base64 DER). The
# attestation chain omits its root, so the verifier needs the certificate
# itself. Obtain and verify from https://www.apple.com/certificateauthority/
APP_ATTEST_ROOT_CA = ""

# --- Spend controls (each optional; set to bound what entitled callers spend) ---
# Comma-separated allowlist of model IDs the proxy will forward.
ALLOWED_MODELS = "claude-opus-4-8"
# Upper bound on max_tokens per request.
MAX_TOKENS_LIMIT = "4096"
# Tokens each caller may request per UTC day (max_tokens, debited upfront).
DAILY_TOKEN_BUDGET = "200000"

# --- Proxy configuration ---
# Opt in to each upstream path the app may reach. Default is the Messages API.
ALLOWED_UPSTREAM_PATHS = "/v1/messages"
# Anthropic API version header.
ANTHROPIC_VERSION = "2023-06-01"

# --- Durable Object bindings ---
# One TokenBudget instance per caller identity.
[[durable_objects.bindings]]
name = "TOKEN_BUDGET"
class_name = "TokenBudget"

# One AttestKey instance per App Attest keyId (public key + counter).
[[durable_objects.bindings]]
name = "ATTEST_KEYS"
class_name = "AttestKey"

# One AttestChallenge instance per issued registration challenge.
[[durable_objects.bindings]]
name = "ATTEST_CHALLENGES"
class_name = "AttestChallenge"

# One RevocationRecord instance per originalTransactionId.
[[durable_objects.bindings]]
name = "REVOCATIONS"
class_name = "RevocationRecord"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["TokenBudget", "AttestKey", "AttestChallenge", "RevocationRecord"]

# Secret, never commit this; set it out of band:
#   wrangler secret put ANTHROPIC_API_KEY

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

/**
 * JWSTransaction: the decoded StoreKit 2 transaction fields this gate cares
 * about. The full payload carries far more; we read only what the entitlement
 * decision needs.
 */
export interface JWSTransaction {
  bundleId?: string;
  productId?: string;
  /**
   * Stable across renewals and restores, so it is the identity everything
   * server-side keys on: the revocation record and the per-caller budget.
   */
  originalTransactionId?: string;
  /**
   * "Sandbox" or "Production". StoreKit 2 signs sandbox transactions with the
   * same certificate chain as production, and a sandbox Apple ID is free, so a
   * Production check is the only thing that stops anyone minting a valid
   * entitlement for nothing. The gate requires "Production".
   */
  environment?: "Sandbox" | "Production";
  /** Subscription expiry, ms since epoch. Absent for non-subscription products. */
  expiresDate?: number;
  /** Set (ms since epoch) when Apple revokes the purchase (refund, dispute). */
  revocationDate?: number;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

/**
 * The entitlement decision: a pure function, no crypto and no network. Given a
 * decoded StoreKit 2 transaction and the gate config, decide whether the caller
 * is entitled. Keeping it pure makes it testable in isolation.
 */
import type { JWSTransaction } from "./transaction.ts";

export interface GateConfig {
  allowedBundleIds: Set<string>;
  allowedProductIds: Set<string> | null; // null = any product
  now: number; // ms since epoch
}

export type GateResult =
  | { ok: true }
  | { ok: false; status: 401 | 403; reason: string };

/** Parse a comma-separated env var into a trimmed, non-empty Set. */
export function parseList(value: string | undefined): Set<string> {
  return new Set(
    (value ?? "")
      .split(",")
      .map((s) => s.trim())
      .filter((s) => s.length > 0),
  );
}

export function evaluateEntitlement(
  txn: JWSTransaction,
  cfg: GateConfig,
): GateResult {
  if (!txn.bundleId || !cfg.allowedBundleIds.has(txn.bundleId)) {
    return { ok: false, status: 403, reason: "bundle_id_not_allowed" };
  }
  if (
    cfg.allowedProductIds &&
    (!txn.productId || !cfg.allowedProductIds.has(txn.productId))
  ) {
    return { ok: false, status: 403, reason: "product_id_not_allowed" };
  }
  // A sandbox transaction is signed by the same chain as production and costs
  // nothing to mint, so it must never clear the gate.
  if (txn.environment !== "Production") {
    return { ok: false, status: 403, reason: "environment_not_production" };
  }
  if (txn.revocationDate != null) {
    return { ok: false, status: 403, reason: "entitlement_revoked" };
  }
  // Trial and paid are the same check: a subscription is valid while its
  // expiresDate is in the future. Non-subscription products omit expiresDate.
  if (txn.expiresDate != null && txn.expiresDate <= cfg.now) {
    return { ok: false, status: 403, reason: "entitlement_expired" };
  }
  return { ok: true };
}

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

/**
 * Shared Apple certificate-chain and JWS verification.
 *
 * Three Apple credentials flow through this Worker, and all of them are signed
 * the same way: a StoreKit 2 transaction, an App Store Server Notifications V2
 * payload, and an App Attest attestation each carry an x5c certificate chain.
 * This file owns the chain walk so every caller gets the same checks: every
 * certificate inside its validity window, every link signed by the next, and
 * the trust anchor pinned rather than assumed.
 *
 * Two anchoring modes, because Apple ships two chain shapes. StoreKit and the
 * notifications payload include the root in the chain, so pinning its SHA-256
 * is enough. The App Attest attestation omits the root, so the verifier needs
 * the root certificate itself to check the last link's signature.
 *
 * The crypto dependencies are imported lazily so the pure logic elsewhere
 * stays unit-testable with zero installs. Production dependencies: `jose`,
 * `@peculiar/x509`.
 */
import type { X509Certificate } from "@peculiar/x509";

/** Apple chains are leaf, intermediate, root. Refuse anything outlandish. */
const MAX_CHAIN_LENGTH = 5;

type X509Module = typeof import("@peculiar/x509");

async function chainCerts(
  x509: X509Module,
  x5c: Array<string | Uint8Array>,
): Promise<X509Certificate[]> {
  if (x5c.length < 2 || x5c.length > MAX_CHAIN_LENGTH) {
    throw new Error("unexpected certificate chain length");
  }
  const certs = x5c.map((der) => new x509.X509Certificate(der));
  const now = new Date();
  for (const cert of certs) {
    if (now < cert.notBefore || now > cert.notAfter) {
      throw new Error("certificate outside its validity window");
    }
  }
  // Verify each link in the chain (leaf first, root last).
  for (let i = 0; i < certs.length - 1; i++) {
    const issuerKey = await certs[i + 1].publicKey.export();
    if (!(await certs[i].verify({ publicKey: issuerKey }))) {
      throw new Error("broken certificate chain");
    }
  }
  return certs;
}

/**
 * Verify a chain that carries its own root, and pin that root by SHA-256.
 * Used for StoreKit 2 transactions and server notifications, whose x5c ends
 * at Apple Root CA - G3.
 */
export async function verifyChainAndPin(
  x5c: Array<string | Uint8Array>,
  pinnedSha256: string,
): Promise<X509Certificate[]> {
  const x509 = await import("@peculiar/x509");
  const certs = await chainCerts(x509, x5c);
  const root = certs[certs.length - 1];
  const rootSha256 = toHex(await crypto.subtle.digest("SHA-256", root.rawData));
  if (rootSha256 !== normalizeHex(pinnedSha256)) {
    throw new Error("untrusted root certificate");
  }
  return certs;
}

/**
 * Verify a chain that omits its root, anchoring the last certificate to a
 * configured trust anchor. Used for App Attest attestations, whose x5c stops
 * at the intermediate; `anchor` is the Apple App Attestation Root CA
 * certificate (PEM or base64 DER).
 */
export async function verifyChainToAnchor(
  x5c: Array<string | Uint8Array>,
  anchor: string,
): Promise<X509Certificate[]> {
  const x509 = await import("@peculiar/x509");
  const certs = await chainCerts(x509, x5c);
  const root = new x509.X509Certificate(anchor);
  const rootKey = await root.publicKey.export();
  const last = certs[certs.length - 1];
  if (!(await last.verify({ publicKey: rootKey }))) {
    throw new Error("chain does not anchor to the pinned root");
  }
  return certs;
}

/**
 * Verify an Apple JWS end to end: walk and pin the x5c chain, then verify the
 * signature with the leaf key, accepting only ES256. Returns the payload.
 */
export async function verifyAppleJWS(
  jws: string,
  pinnedRootSha256: string,
): Promise<unknown> {
  const { decodeProtectedHeader, importX509, jwtVerify } = await import("jose");
  const header = decodeProtectedHeader(jws);
  if (!Array.isArray(header.x5c)) {
    throw new Error("JWS is missing an x5c certificate chain");
  }
  const certs = await verifyChainAndPin(header.x5c, pinnedRootSha256);
  const leafKey = await importX509(certs[0].toString("pem"), "ES256");
  const { payload } = await jwtVerify(jws, leafKey, { algorithms: ["ES256"] });
  return payload;
}

export function toHex(buf: ArrayBuffer): string {
  return [...new Uint8Array(buf)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
}

export function normalizeHex(s: string): string {
  return s.toLowerCase().replace(/[^0-9a-f]/g, "");
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

/**
 * Byte helpers shared by the verifiers: base64, constant-time comparison, and
 * concatenation. No crypto and no dependencies.
 */

export function base64ToBytes(b64: string): Uint8Array {
  const bin = atob(b64);
  const out = new Uint8Array(bin.length);
  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
  return out;
}

export function bytesToBase64(bytes: Uint8Array): string {
  let bin = "";
  for (const b of bytes) bin += String.fromCharCode(b);
  return btoa(bin);
}

/** Constant-time equality, so a comparison never leaks how far it matched. */
export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
  if (a.length !== b.length) return false;
  let diff = 0;
  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
  return diff === 0;
}

export function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
  const out = new Uint8Array(a.length + b.length);
  out.set(a, 0);
  out.set(b, a.length);
  return out;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

/**
 * StoreKit 2 signed-transaction verification.
 *
 * A StoreKit 2 transaction is an Apple JWS whose x5c chain ends at Apple Root
 * CA - G3, so the whole job lives in applejws.ts: walk the chain, check every
 * validity window, pin the root, verify the ES256 signature with the leaf key.
 * This file keeps the typed seam, so tests can swap in a fake and skip real
 * certificates.
 */
import type { JWSTransaction } from "./transaction.ts";
import { verifyAppleJWS } from "./applejws.ts";

/** Verifier signature, so tests can swap in a fake and skip real certificates. */
export type TransactionVerifier = (
  jws: string,
  appleRootSha256: string,
) => Promise<JWSTransaction>;

export const verifyTransactionJWS: TransactionVerifier = async (
  jws,
  appleRootSha256,
) => (await verifyAppleJWS(jws, appleRootSha256)) as JWSTransaction;

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112

/**
 * The server-side revocation record: what Apple has told us since the JWS in
 * the caller's hand was minted.
 *
 * The entitlement gate reads revocationDate from the token the client sends,
 * so on its own it only catches a refund the client honestly reports. This
 * record closes that: the notifications webhook writes refunds and
 * revocations here as Apple reports them, and the worker checks it on every
 * request. One Durable Object per originalTransactionId keeps the record
 * strongly consistent everywhere with great distributed performance.
 *
 * The notification-to-action mapping is a pure function, kept apart from the
 * store so it tests in isolation.
 */
import type { DurableObjectNamespaceLike, Env } from "./env.ts";

/** Injectable seam over the REVOCATIONS binding. */
export interface RevocationStore {
  isRevoked(originalTransactionId: string): Promise<boolean>;
  revoke(originalTransactionId: string, reason: string): Promise<void>;
  unrevoke(originalTransactionId: string): Promise<void>;
}

interface StorageLike {
  get(key: string): Promise<unknown>;
  put(key: string, value: unknown): Promise<void>;
}

interface StateLike {
  storage: StorageLike;
}

type RevocationRequest =
  | { action: "get" }
  | { action: "revoke"; reason: string }
  | { action: "unrevoke" };

/**
 * One instance per originalTransactionId (idFromName). Classic fetch-based
 * Durable Object.
 */
export class RevocationRecord {
  storage: StorageLike;

  constructor(state: StateLike) {
    this.storage = state.storage;
  }

  async fetch(request: Request): Promise<Response> {
    const body = (await request.json()) as RevocationRequest;
    if (body.action === "revoke") {
      await this.storage.put("revoked", { reason: body.reason });
      return Response.json({ revoked: true });
    }
    if (body.action === "unrevoke") {
      await this.storage.put("revoked", null);
      return Response.json({ revoked: false });
    }
    const revoked = ((await this.storage.get("revoked")) ?? null) != null;
    return Response.json({ revoked });
  }
}

/** Wrap the REVOCATIONS binding, or null when it is not configured. */
export function revocationStoreFromEnv(env: Env): RevocationStore | null {
  const ns: DurableObjectNamespaceLike | undefined = env.REVOCATIONS;
  if (!ns) return null;
  const call = async (id: string, body: RevocationRequest) => {
    const stub = ns.get(ns.idFromName(id));
    const res = await stub.fetch("https://revocation/", {
      method: "POST",
      body: JSON.stringify(body),
    });
    const { revoked } = (await res.json()) as { revoked: boolean };
    return revoked;
  };
  return {
    isRevoked: (id) => call(id, { action: "get" }),
    async revoke(id, reason) {
      await call(id, { action: "revoke", reason });
    },
    async unrevoke(id) {
      await call(id, { action: "unrevoke" });
    },
  };
}

export type RevocationAction =
  | { kind: "revoke"; originalTransactionId: string; reason: string }
  | { kind: "unrevoke"; originalTransactionId: string }
  | null;

/**
 * Map a verified notification to a revocation action. REFUND and REVOKE
 * (family sharing loss) revoke; REFUND_REVERSED restores; every other type
 * (renewals, subscribes, test notifications) is none of this record's
 * business and maps to null.
 */
export function revocationFromNotification(
  notificationType: string | undefined,
  txn: { originalTransactionId?: string },
): RevocationAction {
  const id = txn.originalTransactionId;
  if (!id) return null;
  if (notificationType === "REFUND" || notificationType === "REVOKE") {
    return { kind: "revoke", originalTransactionId: id, reason: notificationType };
  }
  if (notificationType === "REFUND_REVERSED") {
    return { kind: "unrevoke", originalTransactionId: id };
  }
  return null;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

/**
 * The App Store Server Notifications V2 webhook: Apple pushing the truth
 * about refunds and revocations to the Worker.
 *
 * The route is unauthenticated by design. Apple does not sign requests with a
 * shared secret; it signs the payload itself. The body is one JWS
 * (signedPayload) wrapping another (data.signedTransactionInfo), both
 * verified against the same pinned Apple Root CA - G3 as a StoreKit
 * transaction. A forged POST fails the signature and gets a 401; the
 * signature is the authentication.
 */
import { verifyAppleJWS } from "./applejws.ts";
import {
  revocationFromNotification,
  type RevocationStore,
} from "./revocation.ts";

export interface DecodedNotification {
  notificationType?: string;
  transaction: { originalTransactionId?: string };
}

/** Verifier signature, so tests can swap in a fake and skip real certificates. */
export type NotificationVerifier = (
  signedPayload: string,
  appleRootSha256: string,
) => Promise<DecodedNotification>;

export const verifyNotification: NotificationVerifier = async (
  signedPayload,
  appleRootSha256,
) => {
  const payload = (await verifyAppleJWS(signedPayload, appleRootSha256)) as {
    notificationType?: string;
    data?: { signedTransactionInfo?: string };
  };
  const inner = payload.data?.signedTransactionInfo;
  const transaction = inner
    ? ((await verifyAppleJWS(inner, appleRootSha256)) as {
        originalTransactionId?: string;
      })
    : {};
  return { notificationType: payload.notificationType, transaction };
};

export async function handleNotification(
  request: Request,
  appleRootSha256: string,
  verifier: NotificationVerifier,
  store: RevocationStore,
): Promise<Response> {
  let signedPayload: unknown;
  try {
    ({ signedPayload } = (await request.json()) as {
      signedPayload?: unknown;
    });
  } catch {
    return new Response("malformed notification", { status: 400 });
  }
  if (typeof signedPayload !== "string") {
    return new Response("malformed notification", { status: 400 });
  }

  let decoded: DecodedNotification;
  try {
    decoded = await verifier(signedPayload, appleRootSha256);
  } catch {
    // A failed signature is a 401 so App Store Connect retries a transient
    // problem; a forged payload never reaches the store.
    return new Response("invalid signature", { status: 401 });
  }

  const action = revocationFromNotification(
    decoded.notificationType,
    decoded.transaction,
  );
  if (action?.kind === "revoke") {
    await store.revoke(action.originalTransactionId, action.reason);
  } else if (action?.kind === "unrevoke") {
    await store.unrevoke(action.originalTransactionId);
  }

  // 200 for processed and ignored alike: Apple only needs delivery confirmed.
  return new Response(null, { status: 200 });
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

/**
 * The App Attest registration challenge: the Worker issues it, a Durable
 * Object remembers it, and registration consumes it exactly once.
 *
 * The challenge is what binds an attestation to one registration attempt: the
 * app attests its key over the SHA-256 of a value the server chose, so a
 * captured registration cannot be replayed. One Durable Object per challenge
 * value makes "exactly once" atomic: consume is a single-threaded
 * test-and-set, and a spent or expired challenge never passes again.
 */
import type { DurableObjectNamespaceLike, Env } from "./env.ts";

/** A challenge is good for one registration attempt within this window. */
export const CHALLENGE_TTL_MS = 10 * 60 * 1000;

/** Injectable seam: issue a fresh challenge, consume it exactly once. */
export interface ChallengeStore {
  issue(): Promise<string>;
  consume(challenge: string): Promise<boolean>;
}

interface StorageLike {
  get(key: string): Promise<unknown>;
  put(key: string, value: unknown): Promise<void>;
}

interface StateLike {
  storage: StorageLike;
}

type ChallengeRequest =
  | { action: "issue"; now: number }
  | { action: "consume"; now: number };

/** One instance per challenge value (idFromName). Classic fetch-based DO. */
export class AttestChallenge {
  storage: StorageLike;

  constructor(state: StateLike) {
    this.storage = state.storage;
  }

  async fetch(request: Request): Promise<Response> {
    const { action, now } = (await request.json()) as ChallengeRequest;
    if (action === "issue") {
      await this.storage.put("issuedAt", now);
      return Response.json({ ok: true });
    }
    const issuedAt = (await this.storage.get("issuedAt")) as number | undefined;
    const used = ((await this.storage.get("used")) ?? false) as boolean;
    if (issuedAt == null || used || now - issuedAt > CHALLENGE_TTL_MS) {
      return Response.json({ ok: false });
    }
    await this.storage.put("used", true);
    return Response.json({ ok: true });
  }
}

/** Wrap the ATTEST_CHALLENGES binding, or null when it is not configured. */
export function challengeStoreFromEnv(env: Env): ChallengeStore | null {
  const ns: DurableObjectNamespaceLike | undefined = env.ATTEST_CHALLENGES;
  if (!ns) return null;
  const call = async (challenge: string, action: "issue" | "consume") => {
    const stub = ns.get(ns.idFromName(challenge));
    const res = await stub.fetch("https://challenge/", {
      method: "POST",
      body: JSON.stringify({ action, now: Date.now() }),
    });
    const { ok } = (await res.json()) as { ok: boolean };
    return ok;
  };
  return {
    async issue() {
      const challenge = crypto.randomUUID();
      await call(challenge, "issue");
      return challenge;
    },
    consume: (challenge) => call(challenge, "consume"),
  };
}

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190

/**
 * App Attest one-time registration: verify the attestation object and store
 * the hardware-backed public key.
 *
 * The app asks the Worker for a challenge, calls
 * DCAppAttestService.attestKey over its SHA-256, and POSTs the result here.
 * The handler consumes the challenge exactly once (challenge.ts), then the
 * verifier follows Apple's documented procedure: check the certificate chain
 * to the Apple App Attestation Root CA, the nonce Apple embeds in the
 * credential certificate, the key identifier, and the authenticator data.
 * Only then does the public key land in the key record (attestkey.ts), where
 * appattest.ts looks it up on every request.
 */
import type { AppAttestConfig } from "./appattest.ts";
import type { AttestKeyStore } from "./attestkey.ts";
import type { ChallengeStore } from "./challenge.ts";
import { verifyChainToAnchor } from "./applejws.ts";
import {
  base64ToBytes,
  bytesEqual,
  bytesToBase64,
  concatBytes,
} from "./bytes.ts";

export interface AttestationInput {
  keyId: string;
  /** Base64 CBOR attestation object from DCAppAttestService.attestKey. */
  attestation: string;
  /** SHA-256 of the challenge the key was attested over. */
  clientDataHash: ArrayBuffer;
}

export type AttestationConfig = AppAttestConfig & {
  /** The Apple App Attestation Root CA certificate (PEM or base64 DER). */
  attestRootCa: string;
};

/** Resolves with the verified public key (SPKI base64); throws otherwise. */
export type AttestationVerifier = (
  input: AttestationInput,
  cfg: AttestationConfig,
) => Promise<{ spkiBase64: string }>;

/** Apple's marker for the App Attest authenticator in authData. */
const AAGUIDS = ["appattest\0\0\0\0\0\0\0", "appattestdevelop"];
/** The credential-certificate extension Apple reserves for the nonce. */
const NONCE_EXTENSION_OID = "1.2.840.113635.100.8.2";

export const verifyAttestation: AttestationVerifier = async (input, cfg) => {
  const cbor = await import("cbor-x");
  const decoded = cbor.decode(base64ToBytes(input.attestation)) as {
    fmt?: string;
    attStmt?: { x5c?: Uint8Array[] };
    authData?: Uint8Array;
  };
  if (decoded.fmt !== "apple-appattest") {
    throw new Error("not an App Attest attestation");
  }
  const x5c = decoded.attStmt?.x5c;
  const authData = decoded.authData;
  if (!Array.isArray(x5c) || !authData || authData.length < 55) {
    throw new Error("malformed attestation object");
  }

  // 1. The chain: credCert <- intermediate, anchored to the configured Apple
  //    App Attestation Root CA. The x5c omits the root, which is why the
  //    anchor is a certificate rather than a fingerprint.
  const certs = await verifyChainToAnchor(x5c, cfg.attestRootCa);
  const credCert = certs[0];

  // 2. The nonce: SHA-256(authData || clientDataHash) must appear in the
  //    credential certificate's reserved extension. This binds the
  //    certificate Apple issued to this exact attestation.
  const nonce = new Uint8Array(
    await crypto.subtle.digest(
      "SHA-256",
      concatBytes(authData, new Uint8Array(input.clientDataHash)),
    ),
  );
  const ext = credCert.getExtension(NONCE_EXTENSION_OID);
  if (!ext || !containsOctetString(new Uint8Array(ext.value), nonce)) {
    throw new Error("attestation nonce mismatch");
  }

  // 3. The key identifier: SHA-256 of the credential public key (the
  //    uncompressed P-256 point) must equal the keyId the app submitted.
  const spki = new Uint8Array(credCert.publicKey.rawData);
  const point = spki.slice(spki.length - 65);
  if (spki.length < 65 || point[0] !== 0x04) {
    throw new Error("unexpected public key format");
  }
  const keyIdHash = new Uint8Array(await crypto.subtle.digest("SHA-256", point));
  if (!bytesEqual(keyIdHash, base64ToBytes(input.keyId))) {
    throw new Error("key identifier does not match the attested key");
  }

  // 4. The authenticator data: bound to this App ID, counter at zero, the
  //    App Attest aaguid, and a credentialId equal to the key identifier.
  const appId = `${cfg.teamId}.${cfg.bundleId}`;
  const expectedRpId = new Uint8Array(
    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(appId)),
  );
  if (!bytesEqual(authData.slice(0, 32), expectedRpId)) {
    throw new Error("attestation rpId does not match this app");
  }
  const counter = new DataView(
    authData.buffer,
    authData.byteOffset + 33,
    4,
  ).getUint32(0);
  if (counter !== 0) {
    throw new Error("attestation counter must be zero");
  }
  const aaguid = new TextDecoder().decode(authData.slice(37, 53));
  if (!AAGUIDS.includes(aaguid)) {
    throw new Error("unexpected attestation aaguid");
  }
  const credIdLen = (authData[53] << 8) | authData[54];
  if (authData.length < 55 + credIdLen) {
    throw new Error("malformed attestation object");
  }
  const credentialId = authData.slice(55, 55 + credIdLen);
  if (!bytesEqual(credentialId, base64ToBytes(input.keyId))) {
    throw new Error("credentialId does not match the key identifier");
  }

  return { spkiBase64: bytesToBase64(spki) };
};

export async function handleRegistration(
  request: Request,
  cfg: AttestationConfig,
  verifier: AttestationVerifier,
  keys: AttestKeyStore,
  challenges: ChallengeStore,
): Promise<Response> {
  let body: { keyId?: unknown; attestation?: unknown; challenge?: unknown };
  try {
    body = (await request.json()) as typeof body;
  } catch {
    return new Response("malformed registration", { status: 400 });
  }
  const { keyId, attestation, challenge } = body;
  if (
    typeof keyId !== "string" ||
    typeof attestation !== "string" ||
    typeof challenge !== "string"
  ) {
    return new Response("malformed registration", { status: 400 });
  }

  // The challenge is consumed before verification, so one issued challenge
  // buys one attempt; a failed attempt starts over with a fresh challenge.
  if (!(await challenges.consume(challenge))) {
    return new Response("unknown or used challenge", { status: 401 });
  }

  const clientDataHash = await crypto.subtle.digest(
    "SHA-256",
    new TextEncoder().encode(challenge),
  );
  try {
    const { spkiBase64 } = await verifier(
      { keyId, attestation, clientDataHash },
      cfg,
    );
    await keys.putPublicKey(keyId, spkiBase64);
  } catch {
    return new Response("invalid attestation", { status: 401 });
  }
  return new Response(null, { status: 204 });
}

/**
 * Scan DER for an OCTET STRING holding exactly `needle`. Apple wraps the
 * nonce as a single tagged octet string inside a small sequence; scanning for
 * the tagged value avoids a full ASN.1 parser for one field.
 */
function containsOctetString(der: Uint8Array, needle: Uint8Array): boolean {
  for (let i = 0; i + 2 + needle.length <= der.length; i++) {
    if (
      der[i] === 0x04 &&
      der[i + 1] === needle.length &&
      bytesEqual(der.slice(i + 2, i + 2 + needle.length), needle)
    ) {
      return true;
    }
  }
  return false;
}

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

/**
 * App Attest assertion verification, the per-request half.
 *
 * StoreKit answers "is this user entitled?" App Attest answers "is this even
 * my app talking?" The app attests a hardware-backed key once (attestation.ts
 * verifies it and stores the public key), then signs an assertion over each
 * request. This file verifies that per-request assertion:
 *
 *   1. look up the registered public key for keyId,
 *   2. CBOR-decode the assertion into { signature, authenticatorData },
 *   3. check rpIdHash === SHA-256("<teamId>.<bundleId>"),
 *   4. verify the ES256 signature over (authenticatorData || clientDataHash),
 *   5. check the signature counter is strictly increasing (replay defense),
 *      and only after a valid signature, so forgeries never burn a counter.
 *
 * The verifier is injectable, mirroring storekit.ts, so tests run offline
 * with fakes in place of a real device assertion and a stored public key.
 */
import type { Env } from "./env.ts";
import type { AttestKeyStore } from "./attestkey.ts";
import { base64ToBytes, bytesEqual, concatBytes } from "./bytes.ts";

export interface AppAttestConfig {
  teamId: string;
  bundleId: string;
}

export interface AppAttestAssertion {
  keyId: string;
  /** Base64 CBOR assertion produced by DCAppAttestService.generateAssertion. */
  assertion: string;
  /** SHA-256 of the exact request payload the client signed over. */
  clientDataHash: ArrayBuffer;
}

/** Resolves if the assertion is authentic; throws otherwise. */
export type AppAttestVerifier = (
  assertion: AppAttestAssertion,
  cfg: AppAttestConfig,
  keys: AttestKeyStore,
) => Promise<void>;

/** App Attest is "configured" only when both identity values are present. */
export function appAttestConfig(env: Env): AppAttestConfig | null {
  if (!env.APP_ATTEST_TEAM_ID || !env.APP_ATTEST_BUNDLE_ID) return null;
  return {
    teamId: env.APP_ATTEST_TEAM_ID,
    bundleId: env.APP_ATTEST_BUNDLE_ID,
  };
}

export const verifyAppAttestAssertion: AppAttestVerifier = async (
  assertion,
  cfg,
  keys,
) => {
  if (!assertion.keyId || !assertion.assertion) {
    throw new Error("missing App Attest assertion");
  }

  // 1. The registered key. An unregistered keyId is untrusted, full stop.
  const spkiBase64 = await keys.getPublicKey(assertion.keyId);
  if (!spkiBase64) {
    throw new Error("unregistered App Attest key");
  }

  // 2. Decode. The bytes are untrusted, so guard lengths before slicing.
  const cbor = await import("cbor-x");
  const decoded = cbor.decode(base64ToBytes(assertion.assertion)) as {
    authenticatorData?: Uint8Array;
    signature?: Uint8Array;
  };
  const authData = decoded.authenticatorData;
  const signature = decoded.signature;
  if (!authData || !signature || authData.length < 37) {
    throw new Error("malformed App Attest assertion");
  }

  // 3. The assertion must bind to this App ID.
  const rpIdHash = authData.slice(0, 32);
  const appId = `${cfg.teamId}.${cfg.bundleId}`;
  const expected = new Uint8Array(
    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(appId)),
  );
  if (!bytesEqual(rpIdHash, expected)) {
    throw new Error("App Attest rpId does not match this app");
  }

  // 4. The signature: ES256 over (authenticatorData || clientDataHash) with
  //    the registered key. Apple emits DER-encoded ECDSA signatures and
  //    WebCrypto verifies the raw r||s form, so convert first; skipping that
  //    step makes every verification fail and is a classic landmine.
  const key = await crypto.subtle.importKey(
    "spki",
    base64ToBytes(spkiBase64),
    { name: "ECDSA", namedCurve: "P-256" },
    false,
    ["verify"],
  );
  const message = concatBytes(authData, new Uint8Array(assertion.clientDataHash));
  const ok = await crypto.subtle.verify(
    { name: "ECDSA", hash: "SHA-256" },
    key,
    derToRaw(signature),
    message,
  );
  if (!ok) {
    throw new Error("App Attest signature verification failed");
  }

  // 5. The counter, last: only a valid signature may advance it.
  const counter = new DataView(
    authData.buffer,
    authData.byteOffset + 33,
    4,
  ).getUint32(0);
  if (!(await keys.bump(assertion.keyId, counter))) {
    throw new Error("App Attest assertion replayed");
  }
};

/**
 * Convert a DER ECDSA-Sig-Value (SEQUENCE of two INTEGERs) to the raw 64-byte
 * r||s form WebCrypto expects for P-256.
 */
function derToRaw(der: Uint8Array): Uint8Array {
  if (der[0] !== 0x30) throw new Error("not a DER signature");
  let offset = der[1] & 0x80 ? 2 + (der[1] & 0x7f) : 2;
  const readInteger = (): Uint8Array => {
    if (der[offset] !== 0x02) throw new Error("not a DER signature");
    const len = der[offset + 1];
    const start = offset + 2;
    if (!Number.isInteger(len) || start + len > der.length) {
      throw new Error("not a DER signature");
    }
    offset = start + len;
    let bytes = der.slice(start, offset);
    // Strip the sign padding, then left-pad back to 32 bytes.
    while (bytes.length > 32 && bytes[0] === 0) bytes = bytes.slice(1);
    if (bytes.length > 32) throw new Error("not a P-256 signature");
    const out = new Uint8Array(32);
    out.set(bytes, 32 - bytes.length);
    return out;
  };
  const r = readInteger();
  const s = readInteger();
  const raw = new Uint8Array(64);
  raw.set(r, 0);
  raw.set(s, 32);
  return raw;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

/**
 * The App Attest key record: one Durable Object per keyId holding the
 * registered public key and its assertion counter, plus the injectable store
 * the verifiers talk to.
 *
 * The key and the counter belong together: registration writes the public key
 * and starts the counter at zero, and every verified assertion advances the
 * counter through the same single-threaded instance. Durable Objects give
 * each keyId its own strongly consistent instance with great distributed
 * performance, so "strictly increasing" holds everywhere at once.
 */
import type { DurableObjectNamespaceLike, Env } from "./env.ts";

/** Injectable seam: registered keys and their assertion counters. */
export interface AttestKeyStore {
  getPublicKey(keyId: string): Promise<string | null>;
  putPublicKey(keyId: string, spkiBase64: string): Promise<void>;
  /** True only when `counter` is strictly greater than the stored value. */
  bump(keyId: string, counter: number): Promise<boolean>;
}

interface StorageLike {
  get(key: string): Promise<unknown>;
  put(key: string, value: unknown): Promise<void>;
}

interface StateLike {
  storage: StorageLike;
}

type AttestKeyRequest =
  | { action: "get" }
  | { action: "put"; spkiBase64: string }
  | { action: "bump"; counter: number };

/** One instance per keyId (idFromName). Classic fetch-based Durable Object. */
export class AttestKey {
  storage: StorageLike;

  constructor(state: StateLike) {
    this.storage = state.storage;
  }

  async fetch(request: Request): Promise<Response> {
    const body = (await request.json()) as AttestKeyRequest;
    if (body.action === "put") {
      await this.storage.put("spki", body.spkiBase64);
      await this.storage.put("counter", 0);
      return Response.json({ ok: true });
    }
    if (body.action === "get") {
      const spki = (await this.storage.get("spki")) ?? null;
      return Response.json({ spki });
    }
    const last = ((await this.storage.get("counter")) ?? 0) as number;
    if (!Number.isInteger(body.counter) || body.counter <= last) {
      return Response.json({ ok: false });
    }
    await this.storage.put("counter", body.counter);
    return Response.json({ ok: true });
  }
}

/** Wrap the ATTEST_KEYS binding, or null when it is not configured. */
export function attestKeyStoreFromEnv(env: Env): AttestKeyStore | null {
  const ns: DurableObjectNamespaceLike | undefined = env.ATTEST_KEYS;
  if (!ns) return null;
  const call = async (keyId: string, body: AttestKeyRequest) => {
    const stub = ns.get(ns.idFromName(keyId));
    const res = await stub.fetch("https://attest-key/", {
      method: "POST",
      body: JSON.stringify(body),
    });
    return res.json();
  };
  return {
    async getPublicKey(keyId) {
      const { spki } = (await call(keyId, { action: "get" })) as {
        spki: string | null;
      };
      return spki;
    },
    async putPublicKey(keyId, spkiBase64) {
      await call(keyId, { action: "put", spkiBase64 });
    },
    async bump(keyId, counter) {
      const { ok } = (await call(keyId, { action: "bump", counter })) as {
        ok: boolean;
      };
      return ok;
    },
  };
}