enigma-memory 0.1.17 → 0.1.22

package/packages/private-economy/src/payments.js

@@ -0,0 +1,509 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { mkdir, open, readFile, rename } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+export const ENIGMA_PAYMENT_STORE_SCHEMA = 'enigma.private_payment_store.v1';
+export const ENIGMA_PAYMENT_QUOTE_SCHEMA = 'enigma.private_credit_quote.v1';
+export const SOLANA_MAINNET_USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const SIGNATURE_PATTERN = /^[1-9A-HJ-NP-Za-km-z]{64,96}$/;
+const ADDRESS_PATTERN = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+function requiredString(value, name, maximum = 1024) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} is required`);
+  const normalized = value.trim();
+  if (normalized.length > maximum) throw new TypeError(`${name} exceeds ${maximum} characters`);
+  return normalized;
+}
+
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+  return value;
+}
+
+function checkoutReturnUrl(value, name) {
+  const url = new URL(requiredString(value, name, 4096));
+  const loopback = ['127.0.0.1', 'localhost', '::1'].includes(url.hostname);
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) throw new TypeError(`${name} must use HTTPS outside localhost`);
+  if (url.username || url.password) throw new TypeError(`${name} must not contain credentials`);
+  return url.toString();
+}
+
+function boundedInteger(value, name, minimum, maximum, fallback) {
+  const resolved = value === undefined ? fallback : value;
+  if (!Number.isSafeInteger(resolved) || resolved < minimum || resolved > maximum) throw new TypeError(`${name} must be from ${minimum} through ${maximum}`);
+  return resolved;
+}
+
+function iso(clock) {
+  return new Date(clock()).toISOString();
+}
+
+function emptyState() {
+  return { schema: ENIGMA_PAYMENT_STORE_SCHEMA, revision: 0, quotes: {}, usedSignatures: {}, webhookEvents: {}, subscriptions: {} };
+}
+
+function publicQuote(quote) {
+  return {
+    schema: ENIGMA_PAYMENT_QUOTE_SCHEMA,
+    id: quote.id,
+    packageId: quote.packageId,
+    label: quote.label,
+    rail: quote.rail,
+    creditsMicrocredits: quote.creditsMicrocredits,
+    createdAt: quote.createdAt,
+    expiresAt: quote.expiresAt,
+    status: quote.status,
+    memo: quote.memo,
+    payment: structuredClone(quote.payment),
+    settlementReference: quote.creditReference || null,
+  };
+}
+
+function createStoreAdapter(load, save, clock) {
+  let queue = Promise.resolve();
+  const transaction = (operation) => {
+    const run = queue.then(async () => {
+      const state = await load();
+      const result = await operation(state);
+      state.revision += 1;
+      await save(state);
+      return result;
+    });
+    queue = run.catch(() => undefined);
+    return run;
+  };
+  const view = async (operation) => {
+    await queue;
+    return operation(await load());
+  };
+  return Object.freeze({
+    async insertQuote(quote) {
+      return transaction((state) => {
+        if (state.quotes[quote.id]) throw new Error('payment quote collision');
+        state.quotes[quote.id] = structuredClone(quote);
+        return structuredClone(quote);
+      });
+    },
+    async getQuote(id) {
+      return view((state) => state.quotes[id] ? structuredClone(state.quotes[id]) : null);
+    },
+    async markCheckout(id, sessionId) {
+      return transaction((state) => {
+        const quote = state.quotes[id];
+        if (!quote) return null;
+        if (quote.status === 'credited') return structuredClone(quote);
+        if (quote.checkoutSessionId && quote.checkoutSessionId !== sessionId) throw new Error('quote already has a different checkout session');
+        quote.checkoutSessionId = sessionId;
+        quote.status = 'checkout_created';
+        return structuredClone(quote);
+      });
+    },
+    async beginOnchain(id, signature, verified, graceMs) {
+      return transaction((state) => {
+        const quote = state.quotes[id];
+        if (!quote) return null;
+        const usedBy = state.usedSignatures[signature];
+        if (usedBy && usedBy !== id) throw new Error('transaction signature was already used for another quote');
+        if (quote.status === 'credited') {
+          if (quote.transactionSignature !== signature) throw new Error('quote was already settled by another transaction');
+          return { quote: structuredClone(quote), duplicate: true };
+        }
+        if (verified.blockTimeMs > Date.parse(quote.expiresAt) || clock() > Date.parse(quote.expiresAt) + graceMs) {
+          throw new Error('payment quote expired before settlement');
+        }
+        if (quote.transactionSignature && quote.transactionSignature !== signature) throw new Error('quote already has a different transaction');
+        state.usedSignatures[signature] = id;
+        quote.transactionSignature = signature;
+        quote.verifiedBlockTime = new Date(verified.blockTimeMs).toISOString();
+        quote.status = 'processing';
+        return { quote: structuredClone(quote), duplicate: false };
+      });
+    },
+    async finalizeQuote(id, reference) {
+      return transaction((state) => {
+        const quote = state.quotes[id];
+        if (!quote) return null;
+        quote.status = 'credited';
+        quote.creditedAt ||= iso(clock);
+        quote.creditReference ||= reference;
+        return structuredClone(quote);
+      });
+    },
+    async beginWebhook(eventId, type) {
+      return transaction((state) => {
+        const existing = state.webhookEvents[eventId];
+        if (existing?.status === 'done') return { duplicate: true, event: structuredClone(existing) };
+        const event = existing || { id: eventId, type, status: 'processing', receivedAt: iso(clock), completedAt: null };
+        if (event.type !== type) throw new Error('Stripe event identifier changed type');
+        state.webhookEvents[eventId] = event;
+        return { duplicate: false, event: structuredClone(event) };
+      });
+    },
+    async finishWebhook(eventId) {
+      return transaction((state) => {
+        const event = state.webhookEvents[eventId];
+        if (!event) return null;
+        event.status = 'done';
+        event.completedAt = iso(clock);
+        return structuredClone(event);
+      });
+    },
+    async putSubscription(subscriptionId, subscription) {
+      return transaction((state) => {
+        const existing = state.subscriptions[subscriptionId];
+        if (existing && existing.vaultId !== subscription.vaultId) throw new Error('subscription was already bound to another credits vault');
+        state.subscriptions[subscriptionId] = { ...existing, ...structuredClone(subscription), subscriptionId };
+        return structuredClone(state.subscriptions[subscriptionId]);
+      });
+    },
+    async getSubscription(subscriptionId) {
+      return view((state) => state.subscriptions[subscriptionId] ? structuredClone(state.subscriptions[subscriptionId]) : null);
+    },
+  });
+}
+
+export function createEphemeralPaymentStore(options = {}) {
+  const clock = options.clock || Date.now;
+  let state = emptyState();
+  return createStoreAdapter(async () => structuredClone(state), async (next) => { state = structuredClone(next); }, clock);
+}
+
+export function createFilePaymentStore(options = {}) {
+  const path = resolve(String(options.path || '.enigma/payments.json'));
+  const clock = options.clock || Date.now;
+  async function load() {
+    try {
+      const state = JSON.parse(await readFile(path, 'utf8'));
+      if (state?.schema !== ENIGMA_PAYMENT_STORE_SCHEMA) throw new Error('unsupported payment store schema');
+      return state;
+    } catch (error) {
+      if (error.code === 'ENOENT') return emptyState();
+      throw error;
+    }
+  }
+  async function save(state) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+      await handle.writeFile(JSON.stringify(state));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, path);
+  }
+  return createStoreAdapter(load, save, clock);
+}
+
+function normalizePackages(values = []) {
+  if (!Array.isArray(values)) throw new TypeError('payment packages must be an array');
+  const seen = new Set();
+  return values.map((value) => {
+    if (!value || typeof value !== 'object') throw new TypeError('payment package must be an object');
+    const id = requiredString(value.id, 'package id', 120);
+    if (seen.has(id)) throw new TypeError(`duplicate payment package: ${id}`);
+    seen.add(id);
+    const rails = {};
+    if (value.usdcAmountBaseUnits !== undefined) rails.usdcAmountBaseUnits = positiveInteger(value.usdcAmountBaseUnits, 'usdcAmountBaseUnits');
+    if (value.tokenBurnBaseUnits !== undefined) rails.tokenBurnBaseUnits = positiveInteger(value.tokenBurnBaseUnits, 'tokenBurnBaseUnits');
+    if (value.stripePriceId !== undefined) rails.stripePriceId = requiredString(value.stripePriceId, 'stripePriceId', 200);
+    if (!Object.keys(rails).length) throw new TypeError(`payment package ${id} has no configured rail`);
+    return Object.freeze({ id, label: requiredString(value.label || id, 'package label', 120), creditsMicrocredits: positiveInteger(value.creditsMicrocredits, 'creditsMicrocredits'), ...rails });
+  });
+}
+
+function accountSigners(transaction) {
+  return new Set((transaction?.transaction?.message?.accountKeys || [])
+    .filter((key) => key?.signer === true)
+    .map((key) => String(key.pubkey)));
+}
+
+function allInstructions(transaction) {
+  const top = transaction?.transaction?.message?.instructions || [];
+  const inner = (transaction?.meta?.innerInstructions || []).flatMap((entry) => entry.instructions || []);
+  return [...top, ...inner];
+}
+
+function instructionAmount(info) {
+  const value = info?.tokenAmount?.amount ?? info?.amount;
+  return typeof value === 'string' && /^\d+$/.test(value) ? value : String(value ?? '');
+}
+
+function hasMemo(transaction, memo) {
+  return allInstructions(transaction).some((instruction) => instruction?.program === 'spl-memo' && String(instruction.parsed) === memo);
+}
+
+export function createSolanaPaymentVerifier(options = {}) {
+  const rpcUrl = new URL(requiredString(options.rpcUrl, 'Solana RPC URL', 4096));
+  if (rpcUrl.protocol !== 'https:' && !(rpcUrl.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(rpcUrl.hostname))) {
+    throw new TypeError('Solana RPC must use HTTPS outside localhost');
+  }
+  const timeoutMs = boundedInteger(options.timeoutMs, 'timeoutMs', 1000, 120000, 20000);
+  return async function verifySolanaPayment({ signature, quote }) {
+    if (!SIGNATURE_PATTERN.test(signature)) throw new TypeError('Solana signature is invalid');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error('Solana verification timed out')), timeoutMs);
+    try {
+      const response = await fetch(rpcUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ jsonrpc: '2.0', id: quote.id, method: 'getTransaction', params: [signature, { commitment: 'finalized', encoding: 'jsonParsed', maxSupportedTransactionVersion: 0 }] }),
+        signal: controller.signal,
+      });
+      const payload = await response.json();
+      if (!response.ok || payload.error || !payload.result) throw new Error('finalized Solana transaction was not found');
+      const transaction = payload.result;
+      if (transaction.meta?.err !== null) throw new Error('Solana transaction failed');
+      if (!Number.isInteger(transaction.blockTime)) throw new Error('Solana transaction has no block time');
+      if (!hasMemo(transaction, quote.memo)) throw new Error('Solana transaction does not contain the quote memo');
+      const signers = accountSigners(transaction);
+      const payment = quote.payment;
+      if (quote.rail === 'usdc') {
+        const match = allInstructions(transaction).find((instruction) => {
+          const info = instruction?.parsed?.info;
+          return instruction?.program === 'spl-token'
+            && ['transfer', 'transferChecked'].includes(instruction?.parsed?.type)
+            && info?.destination === payment.destinationTokenAccount
+            && info?.mint === payment.mint
+            && instructionAmount(info) === String(payment.amountBaseUnits)
+            && signers.has(String(info?.authority));
+        });
+        if (!match) throw new Error('USDC transfer does not match quote destination, mint, amount, and signer');
+      } else if (quote.rail === 'token_burn') {
+        const match = allInstructions(transaction).find((instruction) => {
+          const info = instruction?.parsed?.info;
+          return instruction?.program === 'spl-token'
+            && ['burn', 'burnChecked'].includes(instruction?.parsed?.type)
+            && info?.mint === payment.mint
+            && instructionAmount(info) === String(payment.amountBaseUnits)
+            && signers.has(String(info?.authority));
+        });
+        if (!match) throw new Error('token burn does not match quote mint, amount, and signer');
+      } else throw new Error('quote is not an on-chain rail');
+      return { signature, blockTimeMs: transaction.blockTime * 1000, slot: transaction.slot };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
+function stripeSignatureParts(value) {
+  const result = { timestamp: null, signatures: [] };
+  for (const part of String(value || '').split(',')) {
+    const [key, candidate] = part.split('=', 2);
+    if (key === 't') result.timestamp = Number(candidate);
+    if (key === 'v1') result.signatures.push(candidate);
+  }
+  return result;
+}
+
+export function createStripeSubscriptionProvider(options = {}) {
+  const apiKey = requiredString(options.apiKey, 'Stripe API key', 4096);
+  const webhookSecret = requiredString(options.webhookSecret, 'Stripe webhook secret', 4096);
+  const baseUrl = new URL(options.baseUrl || 'https://api.stripe.com/v1/');
+  if (baseUrl.protocol !== 'https:' && !(baseUrl.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(baseUrl.hostname))) throw new TypeError('Stripe API must use HTTPS outside localhost');
+  const toleranceSeconds = boundedInteger(options.toleranceSeconds, 'toleranceSeconds', 30, 900, 300);
+
+  async function request(path, init = {}) {
+    const response = await fetch(new URL(path, baseUrl), {
+      ...init,
+      headers: { Authorization: `Bearer ${apiKey}`, ...(init.body ? { 'Content-Type': 'application/x-www-form-urlencoded' } : {}), ...(init.headers || {}) },
+    });
+    const payload = await response.json();
+    if (!response.ok) throw new Error(`Stripe request failed with HTTP ${response.status}`);
+    return payload;
+  }
+
+  return Object.freeze({
+    async createCheckout({ quote, successUrl, cancelUrl }) {
+      const form = new URLSearchParams({
+        mode: 'subscription',
+        'line_items[0][price]': quote.payment.stripePriceId,
+        'line_items[0][quantity]': '1',
+        client_reference_id: quote.id,
+        success_url: successUrl,
+        cancel_url: cancelUrl,
+        'metadata[enigma_quote_id]': quote.id,
+        'subscription_data[metadata][enigma_quote_id]': quote.id,
+      });
+      const session = await request('checkout/sessions', { method: 'POST', headers: { 'Idempotency-Key': quote.id }, body: form });
+      if (!session.id || !session.url) throw new Error('Stripe returned no checkout session URL');
+      return { id: session.id, url: session.url };
+    },
+    async retrieveSubscription(id) {
+      return request(`subscriptions/${encodeURIComponent(requiredString(id, 'subscription id'))}`);
+    },
+    verifyWebhook(rawBody, signatureHeader, now = Date.now()) {
+      if (!Buffer.isBuffer(rawBody)) throw new TypeError('Stripe webhook body must be a Buffer');
+      const parts = stripeSignatureParts(signatureHeader);
+      if (!Number.isInteger(parts.timestamp) || Math.abs(Math.floor(now / 1000) - parts.timestamp) > toleranceSeconds) throw new Error('Stripe webhook timestamp is outside tolerance');
+      const expected = createHmac('sha256', webhookSecret).update(`${parts.timestamp}.`).update(rawBody).digest('hex');
+      const valid = parts.signatures.some((candidate) => {
+        const actualBytes = Buffer.from(String(candidate));
+        const expectedBytes = Buffer.from(expected);
+        return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+      });
+      if (!valid) throw new Error('Stripe webhook signature is invalid');
+      const event = JSON.parse(rawBody.toString('utf8'));
+      if (!event?.id || !event?.type || !event?.data?.object) throw new Error('Stripe webhook event is malformed');
+      return event;
+    },
+  });
+}
+
+function stripeSubscriptionId(object) {
+  return typeof object?.subscription === 'string'
+    ? object.subscription
+    : typeof object?.parent?.subscription_details?.subscription === 'string'
+      ? object.parent.subscription_details.subscription
+      : null;
+}
+
+function stripePriceIds(invoice) {
+  return new Set((invoice?.lines?.data || []).map((line) => line?.pricing?.price_details?.price || line?.price?.id).filter(Boolean));
+}
+
+export function createCreditPaymentService(options = {}) {
+  const store = options.store;
+  const credits = options.credits;
+  if (!store || typeof store.insertQuote !== 'function') throw new TypeError('payment store is required');
+  if (!credits || typeof credits.authenticate !== 'function' || typeof credits.credit !== 'function') throw new TypeError('private credits service is required');
+  const clock = options.clock || Date.now;
+  const packages = normalizePackages(options.packages || []);
+  const packagesById = new Map(packages.map((entry) => [entry.id, entry]));
+  const usdcMint = options.usdcMint || SOLANA_MAINNET_USDC_MINT;
+  const usdcDestinationTokenAccount = options.usdcDestinationTokenAccount || null;
+  const tokenBurnMint = options.tokenBurnMint || null;
+  if (usdcDestinationTokenAccount && !ADDRESS_PATTERN.test(usdcDestinationTokenAccount)) throw new TypeError('USDC destination token account is invalid');
+  if (tokenBurnMint && !ADDRESS_PATTERN.test(tokenBurnMint)) throw new TypeError('token burn mint is invalid');
+  const verifySolanaPayment = options.verifySolanaPayment || null;
+  const stripe = options.stripe || null;
+  const quoteTtlMs = boundedInteger(options.quoteTtlSeconds, 'quoteTtlSeconds', 60, 3600, 600) * 1000;
+  const settlementGraceMs = boundedInteger(options.settlementGraceSeconds, 'settlementGraceSeconds', 60, 86400, 3600) * 1000;
+
+  function availableRails(entry) {
+    return [
+      ...(entry.usdcAmountBaseUnits && usdcDestinationTokenAccount && verifySolanaPayment ? ['usdc'] : []),
+      ...(entry.tokenBurnBaseUnits && tokenBurnMint && verifySolanaPayment ? ['token_burn'] : []),
+      ...(entry.stripePriceId && stripe ? ['subscription'] : []),
+    ];
+  }
+
+  async function authenticatedVault(accessToken) {
+    const principal = await credits.authenticate(accessToken);
+    if (!principal) throw new Error('private credits access token is invalid or expired');
+    return principal;
+  }
+
+  return Object.freeze({
+    listPackages() {
+      return packages.map((entry) => ({ id: entry.id, label: entry.label, creditsMicrocredits: entry.creditsMicrocredits, rails: availableRails(entry) }));
+    },
+    async quote(accessToken, input = {}) {
+      const principal = await authenticatedVault(accessToken);
+      const entry = packagesById.get(requiredString(input.packageId, 'packageId', 120));
+      if (!entry) throw new Error('payment package not found');
+      const rail = requiredString(input.rail, 'rail', 32);
+      if (!availableRails(entry).includes(rail)) throw new Error('payment rail is not configured for this package');
+      const id = randomUUID();
+      const createdAt = clock();
+      const memo = `enigma:${id}`;
+      const payment = rail === 'usdc'
+        ? { network: 'solana-mainnet', mint: usdcMint, destinationTokenAccount: usdcDestinationTokenAccount, amountBaseUnits: entry.usdcAmountBaseUnits }
+        : rail === 'token_burn'
+          ? { network: 'solana-mainnet', mint: tokenBurnMint, amountBaseUnits: entry.tokenBurnBaseUnits }
+          : { provider: 'stripe', mode: 'subscription', stripePriceId: entry.stripePriceId };
+      const stored = await store.insertQuote({
+        id, vaultId: principal.vaultId, packageId: entry.id, label: entry.label, rail,
+        creditsMicrocredits: entry.creditsMicrocredits, createdAt: new Date(createdAt).toISOString(),
+        expiresAt: new Date(createdAt + quoteTtlMs).toISOString(), status: 'quoted', memo, payment,
+        transactionSignature: null, checkoutSessionId: null, creditedAt: null, creditReference: null,
+      });
+      return publicQuote(stored);
+    },
+    async settleOnchain(accessToken, input = {}) {
+      const principal = await authenticatedVault(accessToken);
+      const quote = await store.getQuote(requiredString(input.quoteId, 'quoteId'));
+      if (!quote || quote.vaultId !== principal.vaultId) throw new Error('payment quote not found');
+      if (!['usdc', 'token_burn'].includes(quote.rail) || !verifySolanaPayment) throw new Error('quote is not payable through an on-chain rail');
+      const signature = requiredString(input.signature, 'signature', 128);
+      const verified = await verifySolanaPayment({ signature, quote: publicQuote(quote) });
+      const begun = await store.beginOnchain(quote.id, signature, verified, settlementGraceMs);
+      if (!begun) throw new Error('payment quote not found');
+      const credited = await credits.credit(quote.vaultId, {
+        amountMicrocredits: quote.creditsMicrocredits,
+        idempotencyKey: `solana:${signature}`,
+        reference: `${quote.rail}:${signature}`,
+      });
+      const finalized = await store.finalizeQuote(quote.id, `${quote.rail}:${signature}`);
+      return { quote: publicQuote(finalized), vault: credited.vault, duplicate: begun.duplicate || !credited.inserted };
+    },
+    async createSubscriptionCheckout(accessToken, input = {}) {
+      const principal = await authenticatedVault(accessToken);
+      const quote = await store.getQuote(requiredString(input.quoteId, 'quoteId'));
+      if (!quote || quote.vaultId !== principal.vaultId) throw new Error('payment quote not found');
+      if (quote.rail !== 'subscription' || !stripe) throw new Error('quote is not a Stripe subscription quote');
+      if (Date.parse(quote.expiresAt) <= clock()) throw new Error('payment quote expired');
+      const checkout = await stripe.createCheckout({
+        quote: publicQuote(quote),
+        successUrl: checkoutReturnUrl(input.successUrl, 'successUrl'),
+        cancelUrl: checkoutReturnUrl(input.cancelUrl, 'cancelUrl'),
+      });
+      await store.markCheckout(quote.id, checkout.id);
+      return { checkoutUrl: checkout.url, sessionId: checkout.id, quoteId: quote.id };
+    },
+    async processStripeWebhook(event) {
+      if (!stripe) throw new Error('Stripe subscription provider is not configured');
+      const claim = await store.beginWebhook(requiredString(event.id, 'Stripe event id'), requiredString(event.type, 'Stripe event type'));
+      if (claim.duplicate) return { duplicate: true, type: event.type };
+      const object = event.data.object;
+      if (event.type === 'checkout.session.completed') {
+        const quoteId = object.metadata?.enigma_quote_id || object.client_reference_id;
+        const subscriptionId = stripeSubscriptionId(object);
+        const quote = quoteId ? await store.getQuote(quoteId) : null;
+        if (!quote || quote.rail !== 'subscription' || !subscriptionId) throw new Error('Stripe checkout event is not bound to an Enigma subscription quote');
+        await store.putSubscription(subscriptionId, {
+          quoteId: quote.id,
+          vaultId: quote.vaultId,
+          creditsMicrocredits: quote.creditsMicrocredits,
+          stripePriceId: quote.payment.stripePriceId,
+          status: 'active',
+          createdAt: iso(clock),
+        });
+      } else if (event.type === 'invoice.paid') {
+        const subscriptionId = stripeSubscriptionId(object);
+        if (!subscriptionId || !positiveInteger(object.amount_paid, 'Stripe invoice amount_paid')) throw new Error('paid invoice has no funded subscription');
+        let subscription = await store.getSubscription(subscriptionId);
+        if (!subscription) {
+          const remote = await stripe.retrieveSubscription(subscriptionId);
+          const quoteId = remote.metadata?.enigma_quote_id;
+          const quote = quoteId ? await store.getQuote(quoteId) : null;
+          if (!quote || quote.rail !== 'subscription') throw new Error('Stripe subscription is not bound to an Enigma quote');
+          subscription = await store.putSubscription(subscriptionId, {
+            quoteId: quote.id,
+            vaultId: quote.vaultId,
+            creditsMicrocredits: quote.creditsMicrocredits,
+            stripePriceId: quote.payment.stripePriceId,
+            status: 'active',
+            createdAt: iso(clock),
+          });
+        }
+        if (!stripePriceIds(object).has(subscription.stripePriceId)) throw new Error('Stripe invoice price does not match subscription package');
+        await credits.credit(subscription.vaultId, {
+          amountMicrocredits: subscription.creditsMicrocredits,
+          idempotencyKey: `stripe-invoice:${object.id}`,
+          reference: `stripe:${object.id}`,
+        });
+        const quote = await store.getQuote(subscription.quoteId);
+        if (quote && quote.status !== 'credited') await store.finalizeQuote(quote.id, `stripe:${object.id}`);
+      } else if (event.type === 'customer.subscription.deleted') {
+        const subscriptionId = object.id;
+        const existing = await store.getSubscription(subscriptionId);
+        if (existing) await store.putSubscription(subscriptionId, { ...existing, status: 'cancelled', cancelledAt: iso(clock) });
+      }
+      await store.finishWebhook(event.id);
+      return { duplicate: false, type: event.type };
+    },
+  });
+}