deepline 0.3.113 → 0.3.114

package/dist/bundling-sources/shared_libs/security/receipt-admission-token.ts

@@ -0,0 +1,224 @@
+/**
+ * HMAC capabilities for a Convex-owned receipt to call its corresponding
+ * Vercel private adapter. This lives in a package because Convex is a separate
+ * workspace: it must mint the same short-lived capability that the app
+ * verifies, without importing application source across the workspace seam.
+ */
+const TOKEN_VERSION = 1 as const;
+const TOKEN_TTL_SECONDS = 5 * 60;
+const TOKEN_ISSUER = 'deepline.internal' as const;
+const TOKEN_DERIVATION_LABEL = 'deepline:internal-bootstrap-token:v1';
+
+const PLAY_WEBHOOK_RECEIPT_AUDIENCE =
+  'deepline.play_webhook_receipt.admission' as const;
+const PLAY_WEBHOOK_RECEIPT_PURPOSE = 'play_webhook_receipt_admission' as const;
+const PLAY_WEBHOOK_RECEIPT_BATCH_AUDIENCE =
+  'deepline.play_webhook_receipt.batch_admission' as const;
+const PLAY_WEBHOOK_RECEIPT_BATCH_PURPOSE =
+  'play_webhook_receipt_batch_admission' as const;
+const PLAY_WEBHOOK_RECEIPT_LARGE_BATCH_PURPOSE =
+  'play_webhook_receipt_large_batch_admission' as const;
+export const PLAY_WEBHOOK_RECEIPT_LARGE_BATCH_MAX_RECEIPTS = 1_024;
+const PLAY_TRIGGER_EVENT_AUDIENCE =
+  'deepline.play_trigger_event.admission' as const;
+const PLAY_TRIGGER_EVENT_PURPOSE = 'play_trigger_event_admission' as const;
+const SIGNAL_RADAR_INBOUND_RECEIPT_AUDIENCE =
+  'deepline.signal_radar_inbound_receipt.process' as const;
+const SIGNAL_RADAR_INBOUND_RECEIPT_PURPOSE =
+  'signal_radar_inbound_receipt_process' as const;
+
+function rootSecret(): string {
+  const secret = process.env.BETTER_AUTH_SECRET;
+  if (!secret) throw new Error('BETTER_AUTH_SECRET is not set.');
+  return `${secret}:${TOKEN_DERIVATION_LABEL}`;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function toBase64Url(bytes: Uint8Array): string {
+  return bytesToBase64(bytes)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '');
+}
+
+function encodeJson(value: unknown): string {
+  return toBase64Url(new TextEncoder().encode(JSON.stringify(value)));
+}
+
+async function sign(value: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(rootSecret()),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  return toBase64Url(
+    new Uint8Array(
+      await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(value)),
+    ),
+  );
+}
+
+async function mint(claims: Record<string, unknown>): Promise<string> {
+  const header = encodeJson({ alg: 'HS256', typ: 'JWT' });
+  const payload = encodeJson(claims);
+  const signingInput = `${header}.${payload}`;
+  return `${signingInput}.${await sign(signingInput)}`;
+}
+
+/**
+ * Bind a large request body to its capability without putting up to 1,024
+ * receipt IDs in an HTTP header. JSON preserves order and length, so this is
+ * an exact ordered set rather than a lossy collection fingerprint.
+ */
+export async function hashPlayWebhookReceiptBatchIds(
+  receiptIds: readonly string[],
+): Promise<string> {
+  return toBase64Url(
+    new Uint8Array(
+      await crypto.subtle.digest(
+        'SHA-256',
+        new TextEncoder().encode(JSON.stringify(receiptIds)),
+      ),
+    ),
+  );
+}
+
+function assertUniqueReceiptIds(
+  receiptIds: readonly string[],
+  maxLength: number,
+  label: string,
+) {
+  if (receiptIds.length < 1 || receiptIds.length > maxLength) {
+    throw new Error(
+      `${label} must contain between 1 and ${maxLength} receipts.`,
+    );
+  }
+  if (
+    receiptIds.some(
+      (receiptId) =>
+        typeof receiptId !== 'string' || receiptId.trim().length === 0,
+    )
+  ) {
+    throw new Error(`${label} receipt IDs must be non-empty strings.`);
+  }
+  if (new Set(receiptIds).size !== receiptIds.length) {
+    throw new Error(`${label} receipt IDs must be unique.`);
+  }
+}
+
+export async function mintPlayWebhookReceiptAdmissionToken(input: {
+  orgId: string;
+  receiptId: string;
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  return await mint({
+    v: TOKEN_VERSION,
+    iss: TOKEN_ISSUER,
+    aud: PLAY_WEBHOOK_RECEIPT_AUDIENCE,
+    purpose: PLAY_WEBHOOK_RECEIPT_PURPOSE,
+    org_id: input.orgId,
+    receipt_id: input.receiptId,
+    sub: 'play_webhook_receipt_dispatcher',
+    iat: issuedAt,
+    exp: issuedAt + TOKEN_TTL_SECONDS,
+  });
+}
+
+/** Capability for one Convex-owned, single-workspace receipt batch. */
+export async function mintPlayWebhookReceiptBatchAdmissionToken(input: {
+  orgId: string;
+  receiptIds: readonly string[];
+  nowMs?: number;
+}): Promise<string> {
+  assertUniqueReceiptIds(input.receiptIds, 32, 'Webhook admission batch');
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  return await mint({
+    v: TOKEN_VERSION,
+    iss: TOKEN_ISSUER,
+    aud: PLAY_WEBHOOK_RECEIPT_BATCH_AUDIENCE,
+    purpose: PLAY_WEBHOOK_RECEIPT_BATCH_PURPOSE,
+    org_id: input.orgId,
+    receipt_ids: [...input.receiptIds],
+    sub: 'play_webhook_receipt_batch_dispatcher',
+    iat: issuedAt,
+    exp: issuedAt + TOKEN_TTL_SECONDS,
+  });
+}
+
+/**
+ * Capability for one large, exact receipt collection. Its digest keeps the
+ * signed header small enough for Vercel while the body still carries every
+ * independently durable source identity.
+ */
+export async function mintPlayWebhookReceiptLargeBatchAdmissionToken(input: {
+  orgId: string;
+  receiptIds: readonly string[];
+  nowMs?: number;
+}): Promise<string> {
+  assertUniqueReceiptIds(
+    input.receiptIds,
+    PLAY_WEBHOOK_RECEIPT_LARGE_BATCH_MAX_RECEIPTS,
+    'Webhook large admission batch',
+  );
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  return await mint({
+    v: TOKEN_VERSION,
+    iss: TOKEN_ISSUER,
+    aud: PLAY_WEBHOOK_RECEIPT_BATCH_AUDIENCE,
+    purpose: PLAY_WEBHOOK_RECEIPT_LARGE_BATCH_PURPOSE,
+    org_id: input.orgId,
+    receipt_ids_sha256: await hashPlayWebhookReceiptBatchIds(input.receiptIds),
+    sub: 'play_webhook_receipt_large_batch_dispatcher',
+    iat: issuedAt,
+    exp: issuedAt + TOKEN_TTL_SECONDS,
+  });
+}
+
+export async function mintPlayTriggerEventAdmissionToken(input: {
+  orgId: string;
+  eventId: string;
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  return await mint({
+    v: TOKEN_VERSION,
+    iss: TOKEN_ISSUER,
+    aud: PLAY_TRIGGER_EVENT_AUDIENCE,
+    purpose: PLAY_TRIGGER_EVENT_PURPOSE,
+    org_id: input.orgId,
+    event_id: input.eventId,
+    sub: 'play_trigger_event_dispatcher',
+    iat: issuedAt,
+    exp: issuedAt + TOKEN_TTL_SECONDS,
+  });
+}
+
+export async function mintSignalRadarInboundReceiptToken(input: {
+  orgId: string;
+  receiptId: string;
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  return await mint({
+    v: TOKEN_VERSION,
+    iss: TOKEN_ISSUER,
+    aud: SIGNAL_RADAR_INBOUND_RECEIPT_AUDIENCE,
+    purpose: SIGNAL_RADAR_INBOUND_RECEIPT_PURPOSE,
+    org_id: input.orgId,
+    receipt_id: input.receiptId,
+    sub: 'signal_radar_inbound_receipt_dispatcher',
+    iat: issuedAt,
+    exp: issuedAt + TOKEN_TTL_SECONDS,
+  });
+}