kempo-payments 0.1.1

package/server/utils/payments/sync.js

@@ -0,0 +1,179 @@
+import { triggerHook } from 'kempo/server/sdk.js';
+import { providerForPayment } from '../../providers/index.js';
+import { getPayment, recordRefund, refundedTotal, updatePayment } from './store.js';
+import { stripNulBytes } from './text.js';
+
+/*
+  Where a payment's row is brought into line with what the processor says, and where the hooks
+  other extensions listen to are fired.
+
+  Everything that can change a payment — the admin capturing one, a webhook arriving, a page asking
+  for the current state — funnels through here rather than writing the row itself. That is what
+  makes "did the order get fulfilled?" answerable: there is exactly one place a payment can become
+  `succeeded`, and it is the same place that fires `payment:succeeded`.
+
+  Hooks fire only on a real transition. A processor that redelivers the same event ten times, or an
+  admin screen that polls, produces no changes and therefore no hooks — which matters because the
+  handler on the other end sends an email, issues a licence key or ships a box.
+*/
+
+/*
+  The events this extension fires. Consumers register handlers for them in their own
+  kempo-config.json — see the README.
+
+  `payment:succeeded` is the one to hang fulfilment off. It fires once per payment, when the money
+  has actually been taken, whether that was automatic or a capture somebody performed by hand.
+*/
+export const EVENTS = [
+  'payment:created',     // { payment } — an attempt has been started; no money has moved
+  'payment:authorized',  // { payment } — held on the customer's card, waiting to be captured
+  'payment:succeeded',   // { payment } — taken
+  'payment:failed',      // { payment, error } — the processor refused it
+  'payment:canceled',    // { payment } — abandoned, or the hold released
+  'payment:refunded',    // { payment, refund } — some or all of it given back
+  'payment:disputed',    // { payment, disputed, reason } — a chargeback opened, or closed
+];
+
+const fire = async (event, data) => {
+  const [error] = await triggerHook(event, data);
+  if(error) console.warn(`[kempo-payments] Could not fire ${event}: ${error.msg}`);
+};
+
+/*
+  Persists a provider's view of a payment and fires whatever that change means.
+
+  `state` is the normalised shape a provider module returns. Fields it leaves undefined are fields
+  the provider had no answer for on this call, and they are left alone rather than zeroed — an
+  unexpanded charge reports no refund total, and writing 0 over a real one would erase a refund
+  from the record without erasing it from the customer's statement.
+*/
+export const applyProviderState = async (payment, state, { failed = false } = {}) => {
+  const changes = {};
+
+  if(state.status && state.status !== payment.status) changes.status = state.status;
+  if(Number.isInteger(state.amountCaptured) && state.amountCaptured !== payment.amountCaptured){
+    changes.amountCaptured = state.amountCaptured;
+  }
+  if(Number.isInteger(state.amountRefunded) && state.amountRefunded !== payment.amountRefunded){
+    changes.amountRefunded = state.amountRefunded;
+  }
+  if(typeof state.livemode === 'boolean' && state.livemode !== payment.livemode) changes.livemode = state.livemode;
+  if(state.captureMethod && state.captureMethod !== payment.captureMethod) changes.captureMethod = state.captureMethod;
+
+  /*
+    A decline message is kept until something works, then cleared. A payment that eventually
+    succeeded on the third card is not a failed payment, and leaving the first card's message on it
+    makes every screen showing the payment say otherwise.
+  */
+  const nextError = stripNulBytes(failed ? (state.lastError || 'The payment failed') : state.lastError ?? null);
+  if((nextError || null) !== (payment.lastError || null)) changes.lastError = nextError || null;
+
+  if(!Object.keys(changes).length) return [null, { payment, changed: false }];
+
+  const [error, updated] = await updatePayment(payment.id, changes);
+  if(error) return [error, null];
+
+  if(failed) await fire('payment:failed', { payment: updated, error: updated.lastError });
+
+  if(changes.status){
+    if(changes.status === 'succeeded') await fire('payment:succeeded', { payment: updated });
+    if(changes.status === 'requires_capture') await fire('payment:authorized', { payment: updated });
+    if(changes.status === 'canceled') await fire('payment:canceled', { payment: updated });
+  }
+
+  return [null, { payment: updated, changed: true }];
+};
+
+/*
+  Records refunds the provider reported and rolls the payment's refunded total up from them.
+
+  The total is recomputed from the refund rows rather than added to, so an admin refund and the
+  webhook that reports the same refund a second later cannot between them claim twice the money was
+  returned.
+*/
+export const applyRefunds = async (payment, refunds, { issuedBy } = {}) => {
+  const recorded = [];
+
+  for(const refund of refunds || []){
+    if(!refund?.ref) continue;
+
+    const [error, row] = await recordRefund({
+      paymentId: payment.id,
+      provider: payment.provider,
+      providerRef: refund.ref,
+      amount: refund.amount,
+      currency: refund.currency || payment.currency,
+      status: refund.status || 'pending',
+      reason: stripNulBytes(refund.reason),
+      issuedBy,
+    });
+    if(error) return [error, null];
+    recorded.push(row);
+  }
+
+  const [totalError, total] = await refundedTotal(payment.id);
+  if(totalError) return [totalError, null];
+
+  let current = payment;
+  if(total !== payment.amountRefunded){
+    const [error, updated] = await updatePayment(payment.id, { amountRefunded: total });
+    if(error) return [error, null];
+    current = updated;
+
+    for(const refund of recorded){
+      await fire('payment:refunded', { payment: current, refund });
+    }
+  }
+
+  return [null, { payment: current, refunds: recorded }];
+};
+
+export const applyDispute = async (payment, { disputed, reason }) => {
+  if(payment.disputed === disputed) return [null, { payment, changed: false }];
+
+  const [error, updated] = await updatePayment(payment.id, { disputed });
+  if(error) return [error, null];
+
+  await fire('payment:disputed', { payment: updated, disputed, reason: reason || null });
+  return [null, { payment: updated, changed: true }];
+};
+
+export const firePaymentCreated = payment => fire('payment:created', { payment });
+
+/*
+  Asks the processor what it thinks and writes the answer down.
+
+  The webhook is the authority in normal operation — this is for the cases where it is not: a
+  webhook that has not arrived yet, a site whose signing secret was wrong for a week, a payment
+  somebody is looking at right now and wants the truth about. Safe to call as often as wanted;
+  it only writes when something actually differs.
+*/
+export const syncPayment = async id => {
+  const [loadError, payment] = await getPayment(id);
+  if(loadError) return [loadError, null];
+
+  const [providerError, provider] = providerForPayment(payment);
+  if(providerError) return [providerError, null];
+
+  const [fetchError, state] = await provider.retrieveIntent(payment.providerRef);
+  if(fetchError) return [fetchError, null];
+
+  if(!provider.listRefunds) return applyProviderState(payment, state);
+
+  /*
+    Refunds are reconciled from the refunds themselves, not from the charge's running total. Both
+    would agree, but the total alone leaves a refund with no row, and the next refund's recompute
+    from rows would then quietly erase it. The total is also held back from `applyProviderState`
+    so that `applyRefunds` sees the change and fires `payment:refunded` for it.
+  */
+  const [refundsError, refunds] = await provider.listRefunds(payment.providerRef);
+  if(refundsError) return [refundsError, null];
+
+  const [stateError, applied] = await applyProviderState(payment, { ...state, amountRefunded: undefined });
+  if(stateError) return [stateError, null];
+
+  const [applyError, result] = await applyRefunds(applied.payment, refunds);
+  if(applyError) return [applyError, null];
+
+  return [null, { payment: result.payment, changed: applied.changed || result.payment.amountRefunded !== payment.amountRefunded }];
+};

package/server/utils/payments/text.js

@@ -0,0 +1,38 @@
+/*
+  Postgres cannot store a NUL byte in a text or jsonb value, so one anywhere in what is about to be
+  written can only end in a failed insert. Found by testing, twice over:
+
+  - From a caller. On a payment that meant a processor intent was created first and cancelled again
+    once the insert failed; on a refund it was worse — the processor had already moved the money
+    when the insert failed, and the caller got a 500 for a refund that had happened. So what a
+    caller hands over is checked up front (`hasNulByte`) and refused as a 400 before any provider
+    is contacted.
+  - From the processor. That same refund's reason came back on the webhook, and could not be
+    recorded either. There is nothing to refuse there — the money has moved — so what the processor
+    sends is cleaned (`stripNulBytes`) rather than rejected.
+*/
+
+export const hasNulByte = (...values) => {
+  let found = false;
+
+  for(const value of values){
+    JSON.stringify(value ?? null, (key, entry) => {
+      if(typeof entry === 'string' && entry.includes('\u0000')) found = true;
+      return entry;
+    });
+    if(found) return true;
+  }
+  return false;
+};
+
+/*
+  Works on a string or on anything JSON-shaped, so a whole webhook event can be cleaned before it is
+  stored: the event is kept verbatim as a jsonb log entry, and one NUL anywhere inside it fails
+  that insert and with it the whole delivery.
+*/
+export const stripNulBytes = value => {
+  const clean = entry => typeof entry === 'string' ? entry.replaceAll('\u0000', '') : entry;
+
+  if(value && typeof value === 'object') return JSON.parse(JSON.stringify(value, (key, entry) => clean(entry)));
+  return clean(value);
+};

package/server/utils/permissions/gate.js

@@ -0,0 +1,42 @@
+import { getSession, currentUserHasPermission } from 'kempo/server/sdk.js';
+
+/*
+  The same shape kempo-thumbs and kempo-user-dirs use, for the same reason: a permission check
+  written out longhand in every route is one that eventually has a clause wrong somewhere.
+
+  Every route in this extension is gated except two, and both are deliberate: the webhook endpoint
+  (authenticated by the provider's signature instead, since the caller is Stripe and has no
+  session) and the client config endpoint (it returns a publishable key, which is designed to be
+  seen by every visitor, and a checkout page has to work for a guest with no account).
+*/
+
+export const requireSession = async request => {
+  const token = request.cookies?.session_token;
+  if(!token) return [{ code: 401, msg: 'Authentication required' }, null];
+
+  const [error, session] = await getSession({ token });
+  if(error || !session?.user) return [{ code: 401, msg: 'Authentication required' }, null];
+
+  return [null, { token, user: session.user }];
+};
+
+export const requirePermission = async (token, name) => {
+  const [error, allowed] = await currentUserHasPermission(token, name);
+  if(error) return [{ code: error.code, msg: error.msg }, null];
+  if(!allowed) return [{ code: 403, msg: 'Insufficient permissions' }, null];
+  return [null, true];
+};
+
+/*
+  The two together, since every gated route in this extension needs both and none of them needs
+  them apart.
+*/
+export const gate = async (request, permission) => {
+  const [sessionError, session] = await requireSession(request);
+  if(sessionError) return [sessionError, null];
+
+  const [permError] = await requirePermission(session.token, permission);
+  if(permError) return [permError, null];
+
+  return [null, session];
+};

package/server/utils/webhooks/receive.js

@@ -0,0 +1,153 @@
+import { desc, eq } from 'drizzle-orm';
+import db from 'kempo/server/db/index.js';
+import { kempoPaymentEvent } from '../../db/schema.js';
+import { getProvider } from '../../providers/index.js';
+import { getPaymentByRef } from '../payments/store.js';
+import { applyDispute, applyProviderState, applyRefunds } from '../payments/sync.js';
+import { stripNulBytes } from '../payments/text.js';
+
+/*
+  Where the processor tells us what happened.
+
+  This is the authority on whether a payment succeeded — not the browser. A customer whose
+  connection drops the instant after their card is charged never tells the site anything, and one
+  who is determined to can make their browser claim whatever they like. The webhook comes from the
+  processor, signed, and it arrives whether anybody's browser is still open or not.
+
+  Three properties this endpoint has to have, in order of how expensive they are to get wrong:
+
+  1. **Verified.** An unsigned request that reaches this endpoint could mark any payment paid. The
+     signature check happens before the body is even looked at.
+  2. **Idempotent.** Processors retry until they get a 2xx and may redeliver after one. Claiming a
+     row in `kempoPaymentEvent` — whose primary key is the processor's own event id — is what makes
+     the second delivery a no-op instead of a second order.
+  3. **Forgiving about what it does not recognise.** An unknown event type is recorded and answered
+     200. Returning an error would make the processor retry an event nothing here will ever act on.
+*/
+
+const claimEvent = async ({ provider, eventId, type, payload }) => {
+  const id = `${provider}:${eventId}`;
+
+  try {
+    const [row] = await db.insert(kempoPaymentEvent).values({
+      id,
+      provider,
+      providerEventId: eventId,
+      type,
+      payload,
+      createdAt: new Date(),
+    }).onConflictDoNothing().returning();
+
+    // No row back means the primary key was already taken: we have seen this event before.
+    return [null, row || null];
+  } catch {
+    return [{ code: 500, msg: 'Could not record the event' }, null];
+  }
+};
+
+const finish = async (id, changes) => {
+  try {
+    await db.update(kempoPaymentEvent).set({ handledAt: new Date(), ...changes }).where(eq(kempoPaymentEvent.id, id));
+  } catch {
+    // The work itself already happened; failing to annotate the log entry is not worth failing the
+    // webhook over, because a non-2xx would make the processor redeliver work that is already done.
+  }
+};
+
+const release = async id => {
+  try {
+    await db.delete(kempoPaymentEvent).where(eq(kempoPaymentEvent.id, id));
+  } catch {
+    // Nothing more to do: the caller is already returning the failure that made this necessary.
+  }
+};
+
+export const receiveWebhook = async ({ provider: providerName, payload, signature }) => {
+  const [providerError, provider] = getProvider(providerName);
+  if(providerError) return [providerError, null];
+
+  const [verifyError, event] = await provider.verifyEvent({ payload, signature });
+  if(verifyError) return [verifyError, null];
+
+  const [claimError, claimed] = await claimEvent({
+    provider: provider.name,
+    eventId: event.id,
+    type: event.type,
+    payload: stripNulBytes(event),
+  });
+  if(claimError) return [claimError, null];
+  if(!claimed) return [null, { duplicate: true, type: event.type }];
+
+  const interpreted = provider.interpretEvent(event);
+
+  if(interpreted.kind === 'ignored'){
+    await finish(claimed.id, {});
+    return [null, { handled: false, type: event.type }];
+  }
+
+  /*
+    An event about a payment this site has no record of. Normal, and not an error: one Stripe
+    account can sit behind a staging site and a production one, and each will be sent the other's
+    events. Recorded and acknowledged, so it stops being redelivered.
+  */
+  const [lookupError, payment] = await getPaymentByRef(provider.name, interpreted.providerRef);
+  if(lookupError){
+    await finish(claimed.id, { error: lookupError.code === 404 ? 'No matching payment' : lookupError.msg });
+    return [null, { handled: false, type: event.type, unmatched: true }];
+  }
+
+  let applyError = null;
+
+  if(interpreted.kind === 'payment'){
+    [applyError] = await applyProviderState(payment, interpreted.payment, {
+      failed: event.type.endsWith('payment_failed'),
+    });
+  }
+
+  if(interpreted.kind === 'refund'){
+    let refunds = interpreted.refunds;
+
+    /*
+      An event that says a refund happened without saying which one — Stripe's `charge.refunded`
+      reports only the new total — is answered by asking the processor, since there is nothing to
+      record otherwise. Without this such a refund was "handled" as a no-op and never appeared.
+    */
+    if(!refunds.length && provider.listRefunds){
+      [applyError, refunds] = await provider.listRefunds(payment.providerRef);
+    }
+
+    if(!applyError) [applyError] = await applyRefunds(payment, refunds);
+  }
+
+  if(interpreted.kind === 'dispute'){
+    [applyError] = await applyDispute(payment, interpreted);
+  }
+
+  /*
+    Handled means applied. The claim is what turns a redelivery into a no-op, so a claim left behind
+    by an event that then failed to apply would make the processor's retry — the very thing the
+    non-2xx below asks for — answer "duplicate" and drop it for good, leaving the payment wrong
+    until somebody noticed. Found by testing: a refund that could not be recorded stayed
+    unrecorded, and its retry was swallowed. Releasing the claim lets the retry do the work.
+  */
+  if(applyError){
+    await release(claimed.id);
+    return [applyError, null];
+  }
+
+  await finish(claimed.id, { paymentId: payment.id });
+
+  return [null, { handled: true, type: event.type, paymentId: payment.id }];
+};
+
+export const listEvents = async (paymentId, limit = 25) => {
+  try {
+    const rows = await db.select().from(kempoPaymentEvent)
+      .where(eq(kempoPaymentEvent.paymentId, paymentId))
+      .orderBy(desc(kempoPaymentEvent.createdAt))
+      .limit(Math.min(100, Math.max(1, Number(limit) || 25)));
+    return [null, rows];
+  } catch {
+    return [{ code: 500, msg: 'Could not load the event log' }, null];
+  }
+};

package/uninstall.js

@@ -0,0 +1,35 @@
+import { listPayments } from './server/utils/payments/store.js';
+
+/*
+  Nothing here is deleted, and nothing here can be.
+
+  kempo drops this extension's three tables straight after this runs, which loses the site's record
+  of every payment it has ever taken. That record is a copy: the money, the charges and the refunds
+  all live at the processor, and they are entirely unaffected by anything happening on this server.
+  Reinstalling does not bring the rows back, but the processor's dashboard has never stopped having
+  them, and a payment can always be refunded there.
+
+  What this does is say so, loudly enough that somebody clicking uninstall on a site that has taken
+  real money knows what they are about to lose before they lose it — because there is no undo
+  anywhere in this stack, and "how much did we take last quarter" is a question that gets asked
+  months after the extension was removed.
+
+  Outstanding authorisations are called out separately. Those are holds on real customers' cards
+  that nothing will ever capture or release once this extension is gone; they expire on their own
+  after a week or so, but a customer looking at their statement in the meantime sees money missing.
+*/
+export default async () => {
+  const [error, data] = await listPayments({ limit: 200 });
+  if(error) return;
+
+  const uncaptured = data.payments.filter(payment => payment.status === 'requires_capture');
+
+  console.log(`[kempo-payments] Removing. ${data.total} payment record${data.total === 1 ? '' : 's'} will be dropped with the tables — the charges themselves are unaffected and remain in the processor's dashboard.`);
+
+  if(uncaptured.length){
+    console.warn(`[kempo-payments] ${uncaptured.length} payment${uncaptured.length === 1 ? ' is' : 's are'} authorised but not captured. Capture or cancel ${uncaptured.length === 1 ? 'it' : 'them'} in the processor's dashboard — nothing here will be able to once this is gone:`);
+    for(const payment of uncaptured){
+      console.warn(`  ${payment.provider} ${payment.providerRef} — ${payment.amount} ${payment.currency.toUpperCase()}`);
+    }
+  }
+};

package/update.js

@@ -0,0 +1,14 @@
+import install from './install.js';
+
+/*
+  Updating is the same job as installing: make sure the indexes exist and say something useful if
+  the encryption key is missing. Both statements are `IF NOT EXISTS`, so this is safe from any
+  version to any other.
+
+  New settings, permissions and groups are added by kempo's own declarative diff before this runs,
+  and existing values are never overwritten — so a site's API keys, currency and capture method all
+  survive an update untouched.
+*/
+export default async () => {
+  await install();
+};