@hyodotdev/openiap-commerce-protocol 0.0.0-bootstrap.0 → 0.1.0

package/src/index.d.ts

@@ -0,0 +1,63 @@
+export interface JsonSchema {
+  $id: string;
+  $schema: string;
+  title: string;
+  [key: string]: unknown;
+}
+
+export declare const primitivesSchema: JsonSchema;
+export declare const bundleSchema: JsonSchema;
+export declare const commerceEventSchema: JsonSchema;
+export declare const providerCapabilitiesSchema: JsonSchema;
+export declare const storeEventMappingSchema: JsonSchema;
+export declare const operationsSchema: JsonSchema;
+export declare const schemas: readonly JsonSchema[];
+
+export interface HttpBindingOperation {
+  name: string;
+  kind: "query" | "mutation";
+  profile: string;
+  auth: "none" | "verification" | "server";
+  method: "GET" | "POST";
+  path: string;
+  successStatus: number;
+  idempotent: boolean;
+  errors: readonly string[];
+  input: string | null;
+  result: string;
+}
+
+export declare const HTTP_BINDING: Readonly<{
+  protocolVersion: string;
+  profiles: Readonly<Record<string, string>>;
+  bindings: Readonly<Record<string, string>>;
+  errorStatus: Readonly<Record<string, number>>;
+  errorResponse: string;
+  operations: readonly HttpBindingOperation[];
+}>;
+
+export declare const KNOWN_PROTOCOL_ERROR_CODES: readonly string[];
+export declare const PROTOCOL_PROFILES: Readonly<Record<string, string>>;
+export declare const PROTOCOL_BINDINGS: Readonly<Record<string, string>>;
+
+export declare const COMMERCE_EVENT_VERSION: string;
+export declare const KNOWN_COMMERCE_EVENT_TYPES: readonly string[];
+export declare const KNOWN_STORES: readonly string[];
+export declare const SUBSCRIPTION_STATES: readonly string[];
+export declare const DATA_PROVENANCE: readonly string[];
+
+export declare const EXTENSION_LIMITS: Readonly<{
+  maxEntries: number;
+  maxKeyLength: number;
+  maxValueLength: number;
+}>;
+
+export declare const WEBHOOK: Readonly<{
+  signatureHeader: string;
+  timestampHeader: string;
+  eventIdHeader: string;
+  deliveryIdHeader: string;
+  signaturePrefix: string;
+  contentType: string;
+  toleranceSeconds: number;
+}>;

package/src/index.mjs

@@ -0,0 +1,121 @@
+// Programmatic access to the specification artifacts.
+//
+// The generated JSON Schemas are the runtime artifacts. Every exported contract
+// value is read from them rather than restated here; their GraphQL authoring
+// source is commerce-protocol.graphql.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const load = (name) =>
+  JSON.parse(
+    readFileSync(
+      fileURLToPath(new URL(`../generated/schemas/${name}`, import.meta.url)),
+      "utf8",
+    ),
+  );
+
+export const primitivesSchema = load("primitives.schema.json");
+/**
+ * Every schema in one document with no external reference. Prefer this when
+ * validating: it needs no sibling file and no network access, so an
+ * implementation can validate offline and forever.
+ */
+export const bundleSchema = load("commerce-protocol.bundle.schema.json");
+export const commerceEventSchema = load("commerce-event.schema.json");
+export const providerCapabilitiesSchema = load(
+  "provider-capabilities.schema.json",
+);
+export const storeEventMappingSchema = load("store-event-mapping.schema.json");
+export const operationsSchema = load("operations.schema.json");
+
+export const schemas = Object.freeze([
+  primitivesSchema,
+  commerceEventSchema,
+  providerCapabilitiesSchema,
+  storeEventMappingSchema,
+  operationsSchema,
+]);
+
+const loadGenerated = (name) =>
+  JSON.parse(
+    readFileSync(
+      fileURLToPath(new URL(`../generated/${name}`, import.meta.url)),
+      "utf8",
+    ),
+  );
+
+/** HTTP binding manifest for the operation surface, generated from the SDL. */
+export const HTTP_BINDING = Object.freeze(
+  loadGenerated("bindings/http-binding.json"),
+);
+
+/** Protocol error codes this version names; the value space stays open. */
+export const KNOWN_PROTOCOL_ERROR_CODES = Object.freeze([
+  ...operationsSchema.$defs.ProtocolError.properties.code.examples,
+]);
+
+/** Operation profiles and transport bindings, keyed by name with versions. */
+export const PROTOCOL_PROFILES = Object.freeze({ ...HTTP_BINDING.profiles });
+export const PROTOCOL_BINDINGS = Object.freeze({ ...HTTP_BINDING.bindings });
+
+const eventVersion = commerceEventSchema.$id.match(/\/(\d+\.\d+)\//)?.[1];
+if (!eventVersion)
+  throw new Error("Commerce event schema has no MAJOR.MINOR ID");
+
+/** Version of the event body, derived from the generated schema identifier. */
+export const COMMERCE_EVENT_VERSION = eventVersion;
+
+/** Event types named by this version; the schema permits future minor values. */
+export const KNOWN_COMMERCE_EVENT_TYPES = Object.freeze([
+  ...commerceEventSchema.properties.eventType.examples,
+]);
+
+/**
+ * The stores this version names. The value space is deliberately open — an
+ * implementation may emit a store that is not listed here, and a consumer must
+ * forward it rather than reject the event.
+ */
+export const KNOWN_STORES = Object.freeze([
+  ...primitivesSchema.$defs.Store.examples,
+]);
+
+export const SUBSCRIPTION_STATES = Object.freeze([
+  ...primitivesSchema.$defs.SubscriptionState.enum,
+]);
+
+export const DATA_PROVENANCE = Object.freeze([
+  ...primitivesSchema.$defs.DataProvenance.enum,
+]);
+
+/** Bounds on the `extensions` escape hatch, read from the schema. */
+export const EXTENSION_LIMITS = Object.freeze({
+  maxEntries: primitivesSchema.$defs.Extensions.maxProperties,
+  maxKeyLength: primitivesSchema.$defs.Extensions.propertyNames.maxLength,
+  maxValueLength:
+    primitivesSchema.$defs.Extensions.additionalProperties.maxLength,
+});
+
+/**
+ * Transport constants a receiver needs, read from the published vectors so the
+ * package cannot disagree with the file an implementation actually tests
+ * against. Behaviour is specified in SPEC.md §9.4.
+ */
+const signatureVectors = JSON.parse(
+  readFileSync(
+    fileURLToPath(new URL("../vectors/signatures.json", import.meta.url)),
+    "utf8",
+  ),
+);
+
+export const WEBHOOK = Object.freeze({
+  signatureHeader: signatureVectors.headers.signature,
+  timestampHeader: signatureVectors.headers.timestamp,
+  eventIdHeader: signatureVectors.headers.eventId,
+  deliveryIdHeader: signatureVectors.headers.deliveryId,
+  // Literals, not derived values: SPEC.md §9.4.2 and §9.4.1 name them, and
+  // test/vectors.test.mjs asserts every vector carries the prefix.
+  signaturePrefix: "v1=",
+  contentType: "application/json",
+  toleranceSeconds: signatureVectors.toleranceSeconds,
+});

package/vectors/signatures.json

@@ -0,0 +1,139 @@
+{
+  "$comment": "Test vectors for the OpenIAP Commerce Protocol outbound webhook signature. Any implementation, in any language, must reproduce every `expected` value and must reject every case in `rejections`. Signing input is the ASCII timestamp, one 0x2e byte, and the exact body bytes transmitted.",
+  "algorithm": "HMAC-SHA256, lowercase hex, prefixed `v1=`",
+  "toleranceSeconds": 300,
+  "headers": {
+    "signature": "openiap-signature",
+    "timestamp": "openiap-timestamp",
+    "eventId": "openiap-event-id",
+    "deliveryId": "openiap-delivery-id"
+  },
+  "cases": [
+    {
+      "name": "single-key",
+      "description": "The first attempt in the retry pair. retry-after-backoff uses the same body, eventId, and deliveryId with a fresh timestamp and signature.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "deliveryId": "delivery_retry_chain_01",
+      "timestamp": 1756300801,
+      "body": "{\"eventId\":\"evt_01J8Z4WQK7N2M0X5A9C3F6H8T1\",\"eventType\":\"subscription.renewed\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300801420,\"store\":\"apple\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\",\"applicationId\":\"app_2b8d41\",\"userId\":\"user_5e91a7\",\"productId\":\"premium.monthly\",\"transactionId\":\"2000000912345678\",\"originalTransactionId\":\"2000000811111111\",\"subscription\":{\"state\":\"Active\",\"productId\":\"premium.monthly\",\"expiresAt\":1758979200000,\"renewsAt\":1758979200000,\"willRenew\":true,\"active\":true},\"price\":{\"currency\":\"USD\",\"amountMicros\":9990000,\"provenance\":\"store\"},\"sourceStoreEventId\":\"8f3b1c2d-4e5a-6b7c-8d9e-0f1a2b3c4d5e\"}",
+      "expected": "v1=230e9384a09136b9ba877c6f50b4e79da24aee608b2af9b40ef288b1d03948e3"
+    },
+    {
+      "name": "retry-after-backoff",
+      "description": "A later attempt keeps the exact body, eventId, and deliveryId but uses a fresh current timestamp and recomputed signature.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "deliveryId": "delivery_retry_chain_01",
+      "timestamp": 1756301401,
+      "body": "{\"eventId\":\"evt_01J8Z4WQK7N2M0X5A9C3F6H8T1\",\"eventType\":\"subscription.renewed\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300801420,\"store\":\"apple\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\",\"applicationId\":\"app_2b8d41\",\"userId\":\"user_5e91a7\",\"productId\":\"premium.monthly\",\"transactionId\":\"2000000912345678\",\"originalTransactionId\":\"2000000811111111\",\"subscription\":{\"state\":\"Active\",\"productId\":\"premium.monthly\",\"expiresAt\":1758979200000,\"renewsAt\":1758979200000,\"willRenew\":true,\"active\":true},\"price\":{\"currency\":\"USD\",\"amountMicros\":9990000,\"provenance\":\"store\"},\"sourceStoreEventId\":\"8f3b1c2d-4e5a-6b7c-8d9e-0f1a2b3c4d5e\"}",
+      "expected": "v1=b840fe58b3a8e190eeef0612574125c282ce4384970832111de601678c170574"
+    },
+    {
+      "name": "raw-utf8-body",
+      "description": "Whitespace and the raw UTF-8 extension value are signed exactly. Parsing and reserializing this body changes the bytes and must not verify.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "timestamp": 1756300801,
+      "body": "{ \"eventId\": \"evt_raw_bytes\", \"eventType\": \"subscription.expired\", \"eventVersion\": \"1.0\", \"occurredAt\": 1756300800000, \"processedAt\": 1756300801420, \"store\": \"amazon\", \"environment\": \"production\", \"projectId\": \"proj_7f3a9c\", \"extensions\": { \"note\": \"café\" } }",
+      "expected": "v1=f3243f6851f3841fbbc95ef6f28e94be3bddb32facd86fbe65715f7480ec9b95"
+    },
+    {
+      "name": "during-rotation",
+      "description": "While a secret is rotating, the emitter signs with both keys and joins them with a comma. A receiver holding either key must accept. A receiver must compare against each presented value, never against the header as a whole.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "previousSecret": "whsec_fedcba9876543210fedcba9876543210",
+      "timestamp": 1756300801,
+      "body": "{\"eventId\":\"evt_01J8Z4WQK7N2M0X5A9C3F6H8T1\",\"eventType\":\"subscription.renewed\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300801420,\"store\":\"apple\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\",\"applicationId\":\"app_2b8d41\",\"userId\":\"user_5e91a7\",\"productId\":\"premium.monthly\",\"transactionId\":\"2000000912345678\",\"originalTransactionId\":\"2000000811111111\",\"subscription\":{\"state\":\"Active\",\"productId\":\"premium.monthly\",\"expiresAt\":1758979200000,\"renewsAt\":1758979200000,\"willRenew\":true,\"active\":true},\"price\":{\"currency\":\"USD\",\"amountMicros\":9990000,\"provenance\":\"store\"},\"sourceStoreEventId\":\"8f3b1c2d-4e5a-6b7c-8d9e-0f1a2b3c4d5e\"}",
+      "expected": "v1=230e9384a09136b9ba877c6f50b4e79da24aee608b2af9b40ef288b1d03948e3,v1=0f7dee4be14d34164590d0b40fbbb1dc01a22247554c03dfd89659478fc4ba9d",
+      "presentedHeader": "v1=230e9384a09136b9ba877c6f50b4e79da24aee608b2af9b40ef288b1d03948e3, v1=0f7dee4be14d34164590d0b40fbbb1dc01a22247554c03dfd89659478fc4ba9d"
+    },
+    {
+      "name": "minimal-event-omits-extensions",
+      "description": "Optional extensions may be omitted; this case pins a minimal event body.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "timestamp": 1756300801,
+      "body": "{\"eventId\":\"evt_min\",\"eventType\":\"subscription.expired\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300800001,\"store\":\"amazon\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\"}",
+      "expected": "v1=e39611a0dcaa7f1ceed5d41b39394122c7c0514cc91ceb86cffa0bcdea267731"
+    }
+  ],
+  "rejections": [
+    {
+      "name": "tampered-body",
+      "reason": "Body differs from the signed bytes by one character.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "timestamp": 1756300801,
+      "body": "{\"eventId\":\"evt_01J8Z4WQK7N2M0X5A9C3F6H8T1\",\"eventType\":\"subscription.renewed\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300801420,\"store\":\"apple\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\",\"applicationId\":\"app_2b8d41\",\"userId\":\"user_5e91a7\",\"productId\":\"premium.monthly\",\"transactionId\":\"2000000912345678\",\"originalTransactionId\":\"2000000811111111\",\"subscription\":{\"state\":\"Active\",\"productId\":\"premium.monthly\",\"expiresAt\":1758979200000,\"renewsAt\":1758979200000,\"willRenew\":true,\"active\":true},\"price\":{\"currency\":\"USD\",\"amountMicros\":1000,\"provenance\":\"store\"},\"sourceStoreEventId\":\"8f3b1c2d-4e5a-6b7c-8d9e-0f1a2b3c4d5e\"}",
+      "presentedSignature": "v1=230e9384a09136b9ba877c6f50b4e79da24aee608b2af9b40ef288b1d03948e3"
+    },
+    {
+      "name": "wrong-secret",
+      "reason": "Signature was produced with a key the receiver does not hold.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "timestamp": 1756300801,
+      "body": "{\"eventId\":\"evt_01J8Z4WQK7N2M0X5A9C3F6H8T1\",\"eventType\":\"subscription.renewed\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300801420,\"store\":\"apple\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\",\"applicationId\":\"app_2b8d41\",\"userId\":\"user_5e91a7\",\"productId\":\"premium.monthly\",\"transactionId\":\"2000000912345678\",\"originalTransactionId\":\"2000000811111111\",\"subscription\":{\"state\":\"Active\",\"productId\":\"premium.monthly\",\"expiresAt\":1758979200000,\"renewsAt\":1758979200000,\"willRenew\":true,\"active\":true},\"price\":{\"currency\":\"USD\",\"amountMicros\":9990000,\"provenance\":\"store\"},\"sourceStoreEventId\":\"8f3b1c2d-4e5a-6b7c-8d9e-0f1a2b3c4d5e\"}",
+      "presentedSignature": "v1=b45034a19e3c059eeec1e28a122f22410c2e038fbf2a886b19478a280a65b0fe"
+    },
+    {
+      "name": "timestamp-outside-tolerance",
+      "reason": "Signature is internally valid but older than the 300s tolerance, so it is a replay.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "timestamp": 1756300500,
+      "receiverNow": 1756300801,
+      "body": "{\"eventId\":\"evt_01J8Z4WQK7N2M0X5A9C3F6H8T1\",\"eventType\":\"subscription.renewed\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300801420,\"store\":\"apple\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\",\"applicationId\":\"app_2b8d41\",\"userId\":\"user_5e91a7\",\"productId\":\"premium.monthly\",\"transactionId\":\"2000000912345678\",\"originalTransactionId\":\"2000000811111111\",\"subscription\":{\"state\":\"Active\",\"productId\":\"premium.monthly\",\"expiresAt\":1758979200000,\"renewsAt\":1758979200000,\"willRenew\":true,\"active\":true},\"price\":{\"currency\":\"USD\",\"amountMicros\":9990000,\"provenance\":\"store\"},\"sourceStoreEventId\":\"8f3b1c2d-4e5a-6b7c-8d9e-0f1a2b3c4d5e\"}",
+      "presentedSignature": "v1=9f9969c260046b1eff88ecbf4792845115661a8682a1133e9de4fa44048942ad"
+    },
+    {
+      "name": "timestamp-not-in-signed-material",
+      "reason": "Signature covers only the body, so a captured body could be replayed under a fresh timestamp header.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "timestamp": 1756300801,
+      "body": "{\"eventId\":\"evt_01J8Z4WQK7N2M0X5A9C3F6H8T1\",\"eventType\":\"subscription.renewed\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300801420,\"store\":\"apple\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\",\"applicationId\":\"app_2b8d41\",\"userId\":\"user_5e91a7\",\"productId\":\"premium.monthly\",\"transactionId\":\"2000000912345678\",\"originalTransactionId\":\"2000000811111111\",\"subscription\":{\"state\":\"Active\",\"productId\":\"premium.monthly\",\"expiresAt\":1758979200000,\"renewsAt\":1758979200000,\"willRenew\":true,\"active\":true},\"price\":{\"currency\":\"USD\",\"amountMicros\":9990000,\"provenance\":\"store\"},\"sourceStoreEventId\":\"8f3b1c2d-4e5a-6b7c-8d9e-0f1a2b3c4d5e\"}",
+      "presentedSignature": "v1=81bcc31411153799434bd37ff71f041b76bf8038cf6be4a7b1117a2c5e7a86a6"
+    },
+    {
+      "name": "retry-reuses-first-signature",
+      "reason": "The second attempt has a fresh timestamp header but incorrectly reuses the first attempt's signature instead of signing that timestamp.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "timestamp": 1756301401,
+      "receiverNow": 1756301401,
+      "body": "{\"eventId\":\"evt_01J8Z4WQK7N2M0X5A9C3F6H8T1\",\"eventType\":\"subscription.renewed\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300801420,\"store\":\"apple\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\",\"applicationId\":\"app_2b8d41\",\"userId\":\"user_5e91a7\",\"productId\":\"premium.monthly\",\"transactionId\":\"2000000912345678\",\"originalTransactionId\":\"2000000811111111\",\"subscription\":{\"state\":\"Active\",\"productId\":\"premium.monthly\",\"expiresAt\":1758979200000,\"renewsAt\":1758979200000,\"willRenew\":true,\"active\":true},\"price\":{\"currency\":\"USD\",\"amountMicros\":9990000,\"provenance\":\"store\"},\"sourceStoreEventId\":\"8f3b1c2d-4e5a-6b7c-8d9e-0f1a2b3c4d5e\"}",
+      "presentedSignature": "v1=230e9384a09136b9ba877c6f50b4e79da24aee608b2af9b40ef288b1d03948e3"
+    },
+    {
+      "name": "garbage-appended-to-valid-signature",
+      "reason": "The presented value contains a valid signature as a prefix but is not equal to it. Rule 2 compares each whole comma-separated value; a substring or prefix match would accept this.",
+      "secret": "whsec_0123456789abcdef0123456789abcdef",
+      "timestamp": 1756300801,
+      "body": "{\"eventId\":\"evt_01J8Z4WQK7N2M0X5A9C3F6H8T1\",\"eventType\":\"subscription.renewed\",\"eventVersion\":\"1.0\",\"occurredAt\":1756300800000,\"processedAt\":1756300801420,\"store\":\"apple\",\"environment\":\"production\",\"projectId\":\"proj_7f3a9c\",\"applicationId\":\"app_2b8d41\",\"userId\":\"user_5e91a7\",\"productId\":\"premium.monthly\",\"transactionId\":\"2000000912345678\",\"originalTransactionId\":\"2000000811111111\",\"subscription\":{\"state\":\"Active\",\"productId\":\"premium.monthly\",\"expiresAt\":1758979200000,\"renewsAt\":1758979200000,\"willRenew\":true,\"active\":true},\"price\":{\"currency\":\"USD\",\"amountMicros\":9990000,\"provenance\":\"store\"},\"sourceStoreEventId\":\"8f3b1c2d-4e5a-6b7c-8d9e-0f1a2b3c4d5e\"}",
+      "presentedSignature": "v1=230e9384a09136b9ba877c6f50b4e79da24aee608b2af9b40ef288b1d03948e3ffff"
+    }
+  ],
+  "responseSemantics": {
+    "$comment": "SPEC.md 9.4.3. A conforming emitter maps every consumer response to exactly one action. 2xx is delivered; 408, 429, and 5xx are retried; 3xx and every other 4xx are permanent failures the emitter must not retry or follow; a timeout or connection error is retried.",
+    "connectionError": "retry",
+    "cases": [
+      { "status": 200, "action": "delivered" },
+      { "status": 202, "action": "delivered" },
+      { "status": 204, "action": "delivered" },
+      { "status": 299, "action": "delivered" },
+      { "status": 301, "action": "permanent-failure" },
+      { "status": 302, "action": "permanent-failure" },
+      { "status": 303, "action": "permanent-failure" },
+      { "status": 307, "action": "permanent-failure" },
+      { "status": 308, "action": "permanent-failure" },
+      { "status": 400, "action": "permanent-failure" },
+      { "status": 401, "action": "permanent-failure" },
+      { "status": 403, "action": "permanent-failure" },
+      { "status": 404, "action": "permanent-failure" },
+      { "status": 410, "action": "permanent-failure" },
+      { "status": 422, "action": "permanent-failure" },
+      { "status": 408, "action": "retry" },
+      { "status": 429, "action": "retry" },
+      { "status": 500, "action": "retry" },
+      { "status": 502, "action": "retry" },
+      { "status": 503, "action": "retry" },
+      { "status": 504, "action": "retry" },
+      { "status": 505, "action": "retry" },
+      { "status": 507, "action": "retry" },
+      { "status": 599, "action": "retry" }
+    ]
+  }
+}