repoaccess-core 0.2.0

package/src/worker-env.d.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+// Hand-written env-type augmentation - NOT generated, so `wrangler types` (which overwrites
+// worker-configuration.d.ts) never clobbers it. Declaration-merges into the global CloudflareBindings.
+//
+// EVENT_WEBHOOK_SECRET is the OPTIONAL outbound-delivery signing secret (opt-in via EVENT_WEBHOOK_URL).
+// It is intentionally NOT in wrangler.jsonc `secrets.required` - wrangler's `secrets` has no `optional`
+// list, and listing it under `required` would force it set before every deploy. Defining `secrets`
+// stops .dev.vars name-inference, so it would otherwise be untyped. Declare it OPTIONAL here so
+// `env.EVENT_WEBHOOK_SECRET` is `string | undefined`; events.ts fail-closes when it is unset.
+interface CloudflareBindings {
+  EVENT_WEBHOOK_SECRET?: string
+}

package/src/workflow-id.ts

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Gary Stupak
+
+/**
+ * Cloudflare Workflows instance-id constraints. Verified against BOTH the public docs
+ * (workflows/build/workers-api: "up to 100 characters") and the bundled `workflows-shared`
+ * runtime that miniflare/production use:
+ *
+ *   ALLOWED_STRING_ID_PATTERN = "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$"   (max 100 chars)
+ *
+ * Allowed: letters, digits, `_`, `-`. NOTABLY the colon `:` from the original id scheme's
+ * `{adapter}:{event_type}:{transaction_id}` is REJECTED ("Workflow instance has invalid id").
+ */
+export const WORKFLOW_INSTANCE_ID_PATTERN = /^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/
+export const MAX_WORKFLOW_INSTANCE_ID_LENGTH = 100
+
+export async function sha256Hex(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(input),
+  )
+  return [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+/**
+ * Build the deterministic Workflow instance id = the idempotency key. Components are
+ * joined with `-` (the `:` separator is rejected by the runtime). `adapter` and `eventType` come from a
+ * fixed, charset-safe vocabulary; `transactionId` is provider-defined and may (for some future
+ * provider) contain out-of-charset characters or be very long.
+ *
+ * Security-gate decision (availability): do NOT throw on such a transactionId - a
+ * thrown id denies a paying buyer access AND makes the webhook retry forever. Instead fall back to a
+ * SHA-256 hash of the transaction_id: always charset-valid, length-bounded, and collision-resistant
+ * (so dedupe stays correct - unlike lossy character-sanitization). Deterministic, so the same txn
+ * always yields the same id (idempotency holds). The readable form is kept for the common case
+ * (Stripe `payment_intent`, Paddle `txn_…` - both charset-safe).
+ */
+export async function workflowInstanceId(
+  adapter: string,
+  eventType: string,
+  transactionId: string,
+): Promise<string> {
+  const readable = `${adapter}-${eventType}-${transactionId}`
+  if (
+    readable.length <= MAX_WORKFLOW_INSTANCE_ID_LENGTH &&
+    WORKFLOW_INSTANCE_ID_PATTERN.test(readable)
+  ) {
+    return readable
+  }
+  const digest = await sha256Hex(transactionId)
+  // adapter + eventType are controlled vocab (charset-safe); slice guards the pathological length.
+  return `${adapter}-${eventType}-${digest}`.slice(
+    0,
+    MAX_WORKFLOW_INSTANCE_ID_LENGTH,
+  )
+}
+
+/**
+ * Deterministic Workflow id for an `api_callback` ping. The event_type and transaction_id are
+ * UNKNOWN before the entity is fetched (which happens in the Workflow, not on the ack path), so the
+ * id hashes the RAW ping body instead: identical retried pings collide → idempotent dedupe (the same
+ * `createBatch` guarantee as hmac); distinct events (sale vs refund vs dispute → different bodies)
+ * hash to distinct ids. `apicallback` is a fixed, charset-safe event-type slot. The SHA-256 hex is
+ * charset-safe and length-bounded; `adapter` is controlled vocab (slice guards a pathological name).
+ */
+export async function apiCallbackInstanceId(
+  adapter: string,
+  rawBody: string,
+): Promise<string> {
+  const digest = await sha256Hex(rawBody)
+  return `${adapter}-apicallback-${digest}`.slice(
+    0,
+    MAX_WORKFLOW_INSTANCE_ID_LENGTH,
+  )
+}