@stratacommerce/stripe-connect 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StrataCommerce Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @stratacommerce/stripe-connect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Card payments through Strata Hub's Stripe Connect platform. The store never holds Stripe keys: the Hub calls Stripe, and the store records the Hub's signed payment facts. Needs a store linked to Strata Hub.
+
+- `.` is the API module. Build it into the API and admin images with `STRATA_EXTENSIONS=@stratacommerce/stripe-connect`, or `@stratacommerce/stripe-connect@<version>` to install a published version.
+- `./admin` adds the payments settings panel and order fee and dispute details.
+- `./storefront` is the checkout component for a site's `src/payments.tsx`. Generated sites already depend on it.
+
+`@stratacommerce/i18n`, `drizzle-orm` and `react` are optional peers: each host provides the ones its entries use, and the extension shares the host's i18n context. Each core release also publishes `stratacommerce-api-stripe-connect` and `stratacommerce-admin-stripe-connect` images with this extension built in.
+
+In this repository, operations are in `docs/stripe-connect-operations.md`.

package/dist/admin/fact-list.d.ts

@@ -0,0 +1,5 @@
+import type { ConnectPaymentFact } from '@stratacommerce/hub-protocol';
+export declare function FactList({ facts, locale }: {
+    facts: ConnectPaymentFact[];
+    locale: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/admin/fact-list.js

@@ -0,0 +1,9 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useT } from '@stratacommerce/i18n';
+import { NAMESPACE } from './messages.js';
+// Signed payment facts from the Hub, as stored by the extension.
+export function FactList({ facts, locale }) {
+    const t = useT(NAMESPACE);
+    return _jsx("ul", { className: "space-y-3", children: facts.map((fact) => _jsxs("li", { className: "text-sm break-words", children: [_jsx("strong", { children: t(`factKinds.${fact.kind}`) }), ": ", fact.amountMinor, " ", fact.currency.toUpperCase(), " ", t('minorUnits'), " ", 'status' in fact ? fact.status : '', _jsx("br", {}), _jsx("span", { className: "text-muted-foreground", children: fact.objectId }), fact.kind === 'dispute' && _jsxs(_Fragment, { children: [_jsx("br", {}), fact.deadline !== null && _jsxs(_Fragment, { children: [_jsxs("span", { children: [t('evidenceDue'), ": ", _jsx("time", { dateTime: new Date(fact.deadline * 1000).toISOString(), children: new Date(fact.deadline * 1000).toLocaleString(locale, { timeZoneName: 'short' }) })] }), _jsx("br", {})] }), _jsx("a", { className: "underline", href: `https://dashboard.stripe.com/${fact.scope.livemode ? '' : 'test/'}disputes/${encodeURIComponent(fact.objectId)}`, target: "_blank", rel: "noreferrer", children: t('manageDispute') })] })] }, `${fact.kind}:${fact.objectId}`)) });
+}

package/dist/admin/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@stratacommerce/extension-sdk/admin").AdminExtension;
+export default _default;

package/dist/admin/index.js

@@ -0,0 +1,13 @@
+'use client';
+import { defineAdminExtension } from '@stratacommerce/extension-sdk/admin';
+import { messages } from './messages.js';
+import { ConnectOrderPanel } from './order-panel.js';
+import { ConnectSettingsPanel } from './settings-panel.js';
+export default defineAdminExtension({
+    id: 'stripe-connect',
+    slots: {
+        'payments.settings': ConnectSettingsPanel,
+        'order.payment': ConnectOrderPanel,
+    },
+    messages,
+});

package/dist/admin/messages.d.ts

@@ -0,0 +1,79 @@
+export declare const NAMESPACE = "ext.stripe-connect";
+export declare const messages: {
+    "en-US": {
+        title: string;
+        description: string;
+        loading: string;
+        unavailable: string;
+        live: string;
+        test: string;
+        environment: string;
+        fee: string;
+        feeExplanation: string;
+        consent: string;
+        approve: string;
+        finishHub: string;
+        disable: string;
+        enable: string;
+        revoke: string;
+        connect: string;
+        refresh: string;
+        verifyStore: string;
+        hubOff: string;
+        linkChanged: string;
+        disableExplanation: string;
+        revokeExplanation: string;
+        cancel: string;
+        financials: string;
+        minorUnits: string;
+        evidenceDue: string;
+        manageDispute: string;
+        factKinds: {
+            capture: string;
+            refund: string;
+            application_fee: string;
+            fee_refund: string;
+            dispute: string;
+        };
+        orderTitle: string;
+        orderUnavailable: string;
+    };
+    "es-MX": {
+        title: string;
+        description: string;
+        loading: string;
+        unavailable: string;
+        live: string;
+        test: string;
+        environment: string;
+        fee: string;
+        feeExplanation: string;
+        consent: string;
+        approve: string;
+        finishHub: string;
+        disable: string;
+        enable: string;
+        revoke: string;
+        connect: string;
+        refresh: string;
+        verifyStore: string;
+        hubOff: string;
+        linkChanged: string;
+        disableExplanation: string;
+        revokeExplanation: string;
+        cancel: string;
+        financials: string;
+        minorUnits: string;
+        evidenceDue: string;
+        manageDispute: string;
+        factKinds: {
+            capture: string;
+            refund: string;
+            application_fee: string;
+            fee_refund: string;
+            dispute: string;
+        };
+        orderTitle: string;
+        orderUnavailable: string;
+    };
+};

package/dist/admin/messages.js

@@ -0,0 +1,80 @@
+// Admin messages. The admin registers them under `ext.<extension id>`.
+export const NAMESPACE = 'ext.stripe-connect';
+export const messages = {
+    "en-US": {
+        "title": "Stripe through Strata Connect",
+        "description": "Connect an existing eligible account or create one in Stripe. Strata holds the platform credentials.",
+        "loading": "Loading payment connections…",
+        "unavailable": "Payment status is unavailable. Retry or check your Hub connection.",
+        "live": "Live",
+        "test": "Test",
+        "environment": "Hub environment",
+        "fee": "Revenue share: {{percent}}% ({{bps}} basis points). Terms: {{terms}}.",
+        "feeExplanation": "Applies to the amount collected through Stripe, including shipping and tax, excluding gift-card tender. Customer refunds and fee returns settle separately.",
+        "consent": "As the store owner and an authorized merchant representative, I approve this account, environment, payment delegation and fee terms, including any listed historical recovery.",
+        "approve": "Approve payment connection",
+        "finishHub": "Owner approval recorded. Return to Hub to finish enrolling this store.",
+        "disable": "Disable new checkout",
+        "enable": "Enable new checkout",
+        "revoke": "Revoke this store’s payment authorization",
+        "connect": "Continue in Strata Hub",
+        "refresh": "Refresh status",
+        "verifyStore": "Connect this store to Strata Hub and confirm its API address first.",
+        "hubOff": "Strata Hub is off for this store, so card payments through Stripe Connect are unavailable. Recorded payments and their financial facts stay here. Set STRATA_HUB_KEY on the API to turn the Hub back on.",
+        "linkChanged": "This connection was made through an earlier Hub link. Connect payments again in Strata Hub.",
+        "disableExplanation": "Disabling stops new checkouts and schedules cancellation of unconfirmed attempts. Existing refunds and financial facts retain their original account association.",
+        "revokeExplanation": "This revokes this store’s service credential. Already issued client secrets may still confirm, and refunds may need a fresh owner-approved connection. To disconnect Strata from the Stripe account for every store, use Hub.",
+        "cancel": "Keep authorization",
+        "financials": "Payment reconciliation",
+        "minorUnits": "minor units",
+        "evidenceDue": "Evidence due",
+        "manageDispute": "Manage dispute in Stripe",
+        "factKinds": {
+            "capture": "Customer payment",
+            "refund": "Customer refund",
+            "application_fee": "Collected application fee",
+            "fee_refund": "Application-fee return",
+            "dispute": "Dispute"
+        },
+        "orderTitle": "Stripe Connect fees and disputes",
+        "orderUnavailable": "Stripe Connect details are unavailable for this order."
+    },
+    "es-MX": {
+        "title": "Stripe mediante Strata Connect",
+        "description": "Conecta una cuenta elegible existente o crea una en Stripe. Strata conserva las credenciales de la plataforma.",
+        "loading": "Cargando conexiones de pago…",
+        "unavailable": "El estado de pagos no está disponible. Reintenta o revisa la conexión con Hub.",
+        "live": "En vivo",
+        "test": "Prueba",
+        "environment": "Entorno de Hub",
+        "fee": "Participación en ingresos: {{percent}}% ({{bps}} puntos base). Condiciones: {{terms}}.",
+        "feeExplanation": "Se aplica al importe cobrado mediante Stripe, incluidos envío e impuestos, sin incluir tarjetas de regalo. Los reembolsos al cliente y las devoluciones de comisiones se liquidan por separado.",
+        "consent": "Como propietario de la tienda y representante autorizado del comercio, apruebo esta cuenta, entorno, delegación de pagos y condiciones de comisiones, incluida cualquier recuperación histórica indicada.",
+        "approve": "Aprobar conexión de pagos",
+        "finishHub": "Se registró la aprobación del propietario. Regresa a Hub para terminar de registrar esta tienda.",
+        "disable": "Desactivar nuevos pagos",
+        "enable": "Activar nuevos pagos",
+        "revoke": "Revocar la autorización de pagos de esta tienda",
+        "connect": "Continuar en Strata Hub",
+        "refresh": "Actualizar estado",
+        "verifyStore": "Primero conecta esta tienda a Strata Hub y confirma la dirección de su API.",
+        "hubOff": "Strata Hub está desactivado en esta tienda, así que los pagos con tarjeta mediante Stripe Connect no están disponibles. Los pagos registrados y sus datos financieros se conservan aquí. Define STRATA_HUB_KEY en la API para volver a activar Hub.",
+        "linkChanged": "Esta conexión se hizo mediante un enlace anterior de Hub. Vuelve a conectar los pagos en Strata Hub.",
+        "disableExplanation": "La desactivación impide nuevos pagos y programa la cancelación de intentos sin confirmar. Los reembolsos y registros financieros existentes conservan su asociación con la cuenta original.",
+        "revokeExplanation": "Se revoca la credencial de servicio de esta tienda. Los secretos de cliente ya emitidos aún pueden confirmar pagos, y los reembolsos pueden requerir una conexión nueva aprobada por el propietario. Para desconectar Strata de la cuenta de Stripe en todas las tiendas, usa Hub.",
+        "cancel": "Conservar autorización",
+        "financials": "Conciliación de pagos",
+        "minorUnits": "unidades menores",
+        "evidenceDue": "Fecha límite para las pruebas",
+        "manageDispute": "Gestionar disputa en Stripe",
+        "factKinds": {
+            "capture": "Pago del cliente",
+            "refund": "Reembolso al cliente",
+            "application_fee": "Comisión de aplicación cobrada",
+            "fee_refund": "Devolución de comisión de aplicación",
+            "dispute": "Disputa"
+        },
+        "orderTitle": "Comisiones y disputas de Stripe Connect",
+        "orderUnavailable": "Los detalles de Stripe Connect no están disponibles para este pedido."
+    }
+};

package/dist/admin/order-panel.d.ts

@@ -0,0 +1,2 @@
+import type { OrderPaymentSlotProps } from '@stratacommerce/extension-sdk/admin';
+export declare function ConnectOrderPanel({ api, order }: OrderPaymentSlotProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/admin/order-panel.js

@@ -0,0 +1,35 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { useLocale, useT } from '@stratacommerce/i18n';
+import { FactList } from './fact-list.js';
+import { NAMESPACE } from './messages.js';
+// Fees, fee returns and disputes for one order. Captures and refunds already
+// show in core's order financials, so they are left out here.
+const shown = new Set(['application_fee', 'fee_refund', 'dispute']);
+export function ConnectOrderPanel({ api, order }) {
+    const t = useT(NAMESPACE);
+    const { locale } = useLocale();
+    const [facts, setFacts] = useState(null), [failed, setFailed] = useState(false);
+    const hasConnectPayment = order.payments.some((payment) => payment.provider === 'stripe-connect:card');
+    useEffect(() => {
+        setFacts(null);
+        setFailed(false);
+        if (!hasConnectPayment)
+            return;
+        let current = true;
+        api.get(`/orders/${encodeURIComponent(order.id)}/financials`)
+            .then((rows) => { if (current)
+            setFacts(rows.filter((fact) => shown.has(fact.kind))); })
+            .catch(() => { if (current)
+            setFailed(true); });
+        return () => { current = false; };
+    }, [api, order.id, hasConnectPayment]);
+    if (!hasConnectPayment)
+        return null;
+    if (failed)
+        return _jsx("p", { role: "alert", className: "type-body text-muted-foreground", children: t('orderUnavailable') });
+    if (!facts?.length)
+        return null;
+    return _jsxs("section", { className: "sa-card", children: [_jsx("div", { className: "sa-card__head", children: _jsx("h2", { className: "sa-card__title type-card-title", children: t('orderTitle') }) }), _jsx("div", { className: "sa-card__body", children: _jsx(FactList, { facts: facts, locale: locale }) })] });
+}

package/dist/admin/settings-panel.d.ts

@@ -0,0 +1,4 @@
+import type { PaymentsSettingsSlotProps } from '@stratacommerce/extension-sdk/admin';
+export declare function ConnectSettingsPanel({ api, navigate }: PaymentsSettingsSlotProps & {
+    navigate?: (url: string) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/admin/settings-panel.js

@@ -0,0 +1,29 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { useLocale, useT } from '@stratacommerce/i18n';
+import { FactList } from './fact-list.js';
+import { NAMESPACE } from './messages.js';
+export function ConnectSettingsPanel({ api, navigate = (url) => window.location.assign(url) }) {
+    const t = useT(NAMESPACE);
+    const { locale } = useLocale();
+    const [connections, setConnections] = useState([]), [hubOn, setHubOn] = useState(true), [facts, setFacts] = useState([]), [loading, setLoading] = useState(true), [busy, setBusy] = useState(false), [error, setError] = useState(''), [accepted, setAccepted] = useState({}), [notice, setNotice] = useState(''), [revoke, setRevoke] = useState(null);
+    async function refresh() {
+        const [status, financials] = await Promise.all([api.get('/status'), api.get('/financials')]);
+        setHubOn(status.hub !== 'disabled');
+        setConnections(status.connections);
+        setFacts(financials);
+    }
+    async function run(work) { setBusy(true); setError(''); setNotice(''); try {
+        await work();
+    }
+    catch (failure) {
+        setError(failure instanceof Error ? failure.message : t('unavailable'));
+    }
+    finally {
+        setBusy(false);
+    } }
+    useEffect(() => { refresh().catch(() => setError(t('unavailable'))).finally(() => setLoading(false)); }, []);
+    return _jsxs("section", { className: "sa-card", children: [_jsxs("div", { className: "sa-card__head", children: [_jsx("h2", { className: "sa-card__title type-card-title", children: t('title') }), _jsx("p", { className: "sa-card__description type-caption", children: t('description') })] }), _jsxs("div", { className: "sa-card__body space-y-5", children: [loading && _jsx("p", { role: "status", children: t('loading') }), error && _jsx("p", { role: "alert", children: error }), notice && _jsx("p", { role: "status", children: notice }), !loading && !hubOn && _jsx("p", { role: "status", children: t('hubOff') }), connections.map((connection) => _jsxs("section", { className: "space-y-3 border-b pb-4 break-words", children: [_jsxs("p", { className: "font-medium", children: [connection.scope.stripeAccountId, " \u00B7 ", connection.scope.livemode ? t('live') : t('test'), " \u00B7 ", connection.state] }), _jsxs("p", { className: "text-sm text-muted-foreground", children: [t('environment'), ": ", connection.scope.hubEnvironmentId, " \u00B7 ", connection.scope.contextId] }), hubOn && !connection.linkCurrent && connection.state !== 'revoked' && _jsx("p", { role: "alert", className: "text-sm", children: t('linkChanged') }), _jsx("p", { className: "text-sm", children: t('fee', { bps: connection.policy.revenueShareBps, percent: (connection.policy.revenueShareBps / 100).toFixed(2), terms: connection.policy.termsVersion }) }), _jsx("p", { className: "text-sm text-muted-foreground", children: t('feeExplanation') }), hubOn && connection.state === 'pending' && connection.linkCurrent && _jsxs(_Fragment, { children: [_jsxs("label", { className: "flex items-start gap-2 text-sm", children: [_jsx("input", { type: "checkbox", checked: !!accepted[connection.id], onChange: (e) => setAccepted({ ...accepted, [connection.id]: e.target.checked }) }), t('consent')] }), _jsx("button", { type: "button", className: "sa-btn type-control sa-btn--primary sa-btn--default", disabled: busy || !accepted[connection.id], onClick: () => run(async () => { await api.post(`/approvals/${connection.id}/approve`, { termsVersion: connection.policy.termsVersion, representativeAccepted: true }); await refresh(); setNotice(t('finishHub')); }), children: t('approve') })] }), hubOn && connection.state === 'approved' && _jsx("p", { role: "status", children: t('finishHub') }), hubOn && ['active', 'disabled'].includes(connection.state) && _jsxs("div", { className: "flex flex-wrap gap-3", children: [_jsx("button", { type: "button", className: "sa-btn type-control sa-btn--outline sa-btn--default", disabled: busy, onClick: () => run(async () => { await api.post(`/connections/${connection.id}/enabled`, { enabled: connection.state !== 'active' }); await refresh(); }), children: connection.state === 'active' ? t('disable') : t('enable') }), _jsx("button", { type: "button", className: "sa-btn type-control sa-btn--danger sa-btn--default", disabled: busy, onClick: () => setRevoke(connection.id), children: t('revoke') })] })] }, connection.id)), _jsxs("div", { className: "flex flex-wrap gap-3", children: [hubOn && _jsx("button", { type: "button", className: "sa-btn type-control sa-btn--primary sa-btn--default", disabled: busy, onClick: () => run(async () => { const result = await api.get('/connect-url'); if (!result.available || !result.url)
+                                    throw new Error(result.reason || t('verifyStore')); navigate(result.url); }), children: t('connect') }), _jsx("button", { type: "button", className: "sa-btn type-control sa-btn--outline sa-btn--default", disabled: busy, onClick: () => run(refresh), children: t('refresh') })] }), hubOn && _jsx("p", { className: "text-sm text-muted-foreground", children: t('disableExplanation') }), revoke && _jsxs("div", { role: "alertdialog", "aria-labelledby": "stripe-connect-revoke-title", "aria-describedby": "stripe-connect-revoke-description", className: "space-y-3 border-t pt-4", children: [_jsx("h3", { id: "stripe-connect-revoke-title", className: "font-medium", children: t('revoke') }), _jsx("p", { id: "stripe-connect-revoke-description", className: "text-sm", children: t('revokeExplanation') }), _jsxs("div", { className: "flex flex-wrap gap-3", children: [_jsx("button", { type: "button", className: "sa-btn type-control sa-btn--outline sa-btn--default", disabled: busy, onClick: () => setRevoke(null), children: t('cancel') }), _jsx("button", { type: "button", className: "sa-btn type-control sa-btn--danger sa-btn--default", disabled: busy, onClick: () => run(async () => { await api.post(`/connections/${revoke}/revoke`, {}); setRevoke(null); await refresh(); }), children: t('revoke') })] })] }), !!facts.length && _jsxs("section", { className: "space-y-3", children: [_jsx("h3", { className: "font-medium", children: t('financials') }), _jsx(FactList, { facts: facts, locale: locale })] })] })] });
+}

package/dist/enrollments.d.ts

@@ -0,0 +1,92 @@
+import { type ExtensionContext, type HubLink } from '@stratacommerce/extension-sdk';
+import { type ConnectApproval, type ConnectEnrollmentReceipt } from '@stratacommerce/hub-protocol';
+export declare function createEnrollments(ctx: ExtensionContext): {
+    recordChallenge(link: HubLink, input: unknown): Promise<{
+        received: boolean;
+    }>;
+    /** The owner approves locally; the admin route requires the owner role. */
+    approve(actorId: string, id: string, input: unknown): Promise<{
+        approved: boolean;
+    }>;
+    enroll(link: HubLink, id: string, input: unknown): Promise<ConnectEnrollmentReceipt>;
+    approval(link: HubLink, id: string): Promise<ConnectApproval>;
+    refreshKeys(link: HubLink, id: string, input: unknown): Promise<{
+        refreshed: boolean;
+    }>;
+    /** Enrollments for the admin. `linkCurrent` is false once the store link they were enrolled through is gone or unusable here. */
+    status(): Promise<{
+        id: string;
+        scope: {
+            livemode: boolean;
+            hubEnvironmentId: string;
+            generation: number;
+            linkId: string;
+            hubOrigin: string;
+            hubAccountId: string;
+            hubStoreId: string;
+            paymentBindingId: string;
+            platformId: string;
+            stripeAccountId: string;
+            contextId: string;
+            environmentRole: "development" | "staging" | "production";
+        };
+        policy: {
+            id: string;
+            termsVersion: string;
+            revenueShareBps: number;
+            feeBase: "stripe_collected_gross";
+            rounding: "floor";
+            refundPolicy: "proportional_after_success";
+            disputePolicy: "return_on_final_loss";
+        };
+        state: "pending" | "disabled" | "approved" | "active" | "revoked";
+        expiresAt: Date;
+        recoveryBindingIds: string[];
+        linkCurrent: boolean;
+    }[]>;
+    credentials(id: string): Promise<{
+        clientId: string;
+        token: string;
+        id: string;
+        expiresAt: Date;
+        state: "pending" | "disabled" | "approved" | "active" | "revoked";
+        linkId: string;
+        scope: {
+            livemode: boolean;
+            hubEnvironmentId: string;
+            generation: number;
+            linkId: string;
+            hubOrigin: string;
+            hubAccountId: string;
+            hubStoreId: string;
+            paymentBindingId: string;
+            platformId: string;
+            stripeAccountId: string;
+            contextId: string;
+            environmentRole: "development" | "staging" | "production";
+        };
+        policy: {
+            id: string;
+            termsVersion: string;
+            revenueShareBps: number;
+            feeBase: "stripe_collected_gross";
+            rounding: "floor";
+            refundPolicy: "proportional_after_success";
+            disputePolicy: "return_on_final_loss";
+        };
+        publicKeys: Record<string, string>;
+        recoveryBindingIds: string[];
+        approvedBy: string | null;
+        nonceHash: string;
+        tokenBox: string | null;
+        approvedAt: Date | null;
+        createdAt: Date;
+    }>;
+    setEnabled(id: string, enabled: boolean): Promise<{
+        enabled: boolean;
+    }>;
+    revoke(id: string): Promise<{
+        connected: boolean;
+    }>;
+};
+export type Enrollments = ReturnType<typeof createEnrollments>;

package/dist/enrollments.js

@@ -0,0 +1,173 @@
+import { createHash, createPublicKey } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { eq } from 'drizzle-orm';
+import { z } from 'zod';
+import { AppError } from '@stratacommerce/extension-sdk';
+import { connectChallengeSchema, connectEnrollmentSchema, connectKeyRefreshSchema } from '@stratacommerce/hub-protocol';
+import { assertConnectLink, hubOff } from './identity.js';
+import { enrollments } from './schema.js';
+// Connect enrollment on the store link (docs/hub-store-link.md). The Hub
+// calls these with its Hub token; the extension accepts them, and runs
+// payment work, only while the enrollment's link is the active link and
+// usable here.
+const hash = (s) => createHash('sha256').update(s).digest('hex');
+const approvalSchema = z.object({ termsVersion: z.string(), representativeAccepted: z.literal(true) }).strict();
+const credentialSchema = connectEnrollmentSchema.omit({ nonce: true });
+// The payment client token is sealed by core, bound to this enrollment, the
+// store link and this environment's address.
+const purpose = (id) => `enrollment:${id}`;
+export function createEnrollments(ctx) {
+    const db = ctx.db;
+    async function seal(value, id) {
+        return ctx.hub.seal(purpose(id), JSON.stringify(value));
+    }
+    async function open(box, id) {
+        const opened = await ctx.hub.open(purpose(id), box);
+        const parsed = opened === null ? null : credentialSchema.safeParse(JSON.parse(opened));
+        if (!parsed?.success)
+            throw new AppError('The payment credential does not open in this environment. Reconnect payments.', 'PAYMENT_AUTHORIZATION_REVOKED', 409);
+        return parsed.data;
+    }
+    async function row(id) {
+        const [value] = await db.select().from(enrollments).where(eq(enrollments.id, z.string().uuid().parse(id)));
+        if (!value)
+            throw new AppError('Payment connection not found', 'PAYMENT_CONNECTION_NOT_FOUND', 404);
+        return value;
+    }
+    /** The enrollment's link must be the link in use: the Hub's caller, or this environment's usable active link. */
+    function belongs(value, link) {
+        assertConnectLink(value.scope, link, ctx.environment);
+        if (value.linkId !== link.linkId)
+            throw new AppError('This payment connection belongs to another Hub link. Reconnect payments in Strata Hub.', 'PAYMENT_ENVIRONMENT_MISMATCH', 409);
+    }
+    async function usable(value) {
+        const { state, link } = await ctx.hub.status();
+        if (state === 'disabled')
+            throw hubOff();
+        belongs(value, link);
+        return link;
+    }
+    return {
+        async recordChallenge(link, input) {
+            const parsed = connectChallengeSchema.safeParse(input);
+            if (!parsed.success)
+                throw new AppError('Use a current payment challenge from Hub', 'PAYMENT_CHALLENGE_INVALID', 400);
+            const value = parsed.data, expiry = Date.parse(value.expiresAt);
+            // A challenge lasts at most five minutes on the Hub's clock, which may run a minute ahead of this one.
+            if (expiry <= Date.now() || expiry > Date.now() + 300000 + 60000 || !Object.keys(value.publicKeys).length)
+                throw new AppError('Use a current payment challenge from Hub', 'PAYMENT_CHALLENGE_INVALID', 400);
+            assertConnectLink(value.scope, link, ctx.environment);
+            for (const pem of Object.values(value.publicKeys)) {
+                try {
+                    if (createPublicKey(pem).asymmetricKeyType !== 'ed25519')
+                        throw Error();
+                }
+                catch {
+                    throw new AppError('Payment delivery keys must use Ed25519', 'PAYMENT_CHALLENGE_INVALID', 400);
+                }
+            }
+            await db.transaction(async (tx) => {
+                await tx.insert(enrollments).values({ id: value.scope.paymentBindingId, linkId: link.linkId, scope: value.scope, policy: value.policy, state: 'pending', nonceHash: hash(value.nonce),
+                    expiresAt: new Date(expiry), publicKeys: value.publicKeys, recoveryBindingIds: value.recoveryBindingIds }).onConflictDoNothing();
+                const [existing] = await tx.select().from(enrollments).where(eq(enrollments.id, value.scope.paymentBindingId)).for('update');
+                if (existing.linkId !== link.linkId || existing.nonceHash !== hash(value.nonce) || !isDeepStrictEqual(existing.scope, value.scope) || !isDeepStrictEqual(existing.policy, value.policy) ||
+                    !isDeepStrictEqual(existing.publicKeys, value.publicKeys) || !isDeepStrictEqual(existing.recoveryBindingIds, value.recoveryBindingIds))
+                    throw new AppError('Restart payment authorization', 'PAYMENT_CHALLENGE_INVALID', 409);
+            });
+            return { received: true };
+        },
+        /** The owner approves locally; the admin route requires the owner role. */
+        async approve(actorId, id, input) {
+            const accepted = approvalSchema.parse(input);
+            id = z.string().uuid().parse(id);
+            return db.transaction(async (tx) => {
+                const [value] = await tx.select().from(enrollments).where(eq(enrollments.id, id)).for('update');
+                if (!value || value.state !== 'pending' || value.expiresAt <= new Date() || accepted.termsVersion !== value.policy.termsVersion)
+                    throw new AppError('Review a current payment approval', 'PAYMENT_CHALLENGE_INVALID', 409);
+                await usable(value);
+                await tx.update(enrollments).set({ state: 'approved', approvedBy: actorId, approvedAt: new Date() }).where(eq(enrollments.id, id));
+                return { approved: true };
+            });
+        },
+        async enroll(link, id, input) {
+            const accepted = connectEnrollmentSchema.parse(input), value = await row(id);
+            belongs(value, link);
+            return db.transaction(async (tx) => {
+                const [current] = await tx.select().from(enrollments).where(eq(enrollments.id, id)).for('update');
+                if (current.state === 'active' && current.tokenBox) {
+                    const saved = await open(current.tokenBox, id);
+                    if (saved.clientId === accepted.clientId && hash(saved.token) === hash(accepted.token))
+                        return { clientId: saved.clientId };
+                    throw new AppError('Create a fresh payment authorization', 'PAYMENT_ENROLLMENT_USED', 409);
+                }
+                if (current.state !== 'approved')
+                    throw new AppError('The store owner must approve this payment connection', 'PAYMENT_OWNER_APPROVAL_REQUIRED', 409);
+                if (current.expiresAt <= new Date() || current.nonceHash !== hash(accepted.nonce))
+                    throw new AppError('Create a fresh payment authorization', 'PAYMENT_CHALLENGE_INVALID', 409);
+                // Configure checkout before exposing an active client to Hub recovery.
+                // If either write fails, the enrollment stays approved and Hub resends
+                // it. A method pointing at an approved enrollment cannot take payments.
+                // The row lock also keeps completed replays from changing owner choices.
+                await ctx.payments.setMethod('card', { enabled: true, config: { paymentBindingId: id } });
+                // One enrollment per Hub environment and payment context, as on the Hub.
+                const previous = await tx.select().from(enrollments);
+                for (const prior of previous)
+                    if (prior.id !== id && ['active', 'disabled'].includes(prior.state) && prior.scope.hubEnvironmentId === value.scope.hubEnvironmentId && prior.scope.contextId === value.scope.contextId)
+                        await tx.update(enrollments).set({ state: 'revoked', tokenBox: null }).where(eq(enrollments.id, prior.id));
+                await tx.update(enrollments).set({ state: 'active', tokenBox: await seal({ clientId: accepted.clientId, token: accepted.token }, id) }).where(eq(enrollments.id, id));
+                return { clientId: accepted.clientId };
+            });
+        },
+        async approval(link, id) {
+            const value = await row(id);
+            belongs(value, link);
+            return { state: value.state, scope: value.scope, policy: value.policy, clientId: value.tokenBox ? (await open(value.tokenBox, id)).clientId : null, approvedBy: value.approvedBy };
+        },
+        async refreshKeys(link, id, input) {
+            const value = await row(id);
+            belongs(value, link);
+            if (!['active', 'disabled'].includes(value.state))
+                throw new AppError('Payment key refresh is not authorized', 'PAYMENT_AUTHORIZATION_REVOKED', 409);
+            const { publicKeys } = connectKeyRefreshSchema.parse(input);
+            if (!Object.keys(publicKeys).length || Object.keys(publicKeys).length > 10)
+                throw new AppError('Provide the current delivery keys', 'PAYMENT_CHALLENGE_INVALID', 400);
+            for (const pem of Object.values(publicKeys))
+                if (createPublicKey(pem).asymmetricKeyType !== 'ed25519')
+                    throw new AppError('Use Ed25519 delivery keys', 'PAYMENT_CHALLENGE_INVALID', 400);
+            await db.update(enrollments).set({ publicKeys }).where(eq(enrollments.id, id));
+            return { refreshed: true };
+        },
+        /** Enrollments for the admin. `linkCurrent` is false once the store link they were enrolled through is gone or unusable here. */
+        async status() {
+            const rows = await db.select().from(enrollments);
+            if (!rows.length)
+                return [];
+            const link = await ctx.hub.link();
+            return rows.map(({ id, scope, policy, state, expiresAt, recoveryBindingIds, linkId }) => ({ id, scope, policy, state, expiresAt, recoveryBindingIds, linkCurrent: link?.linkId === linkId }));
+        },
+        async credentials(id) {
+            const value = await row(id);
+            await usable(value);
+            if (!['active', 'disabled'].includes(value.state) || !value.tokenBox)
+                throw new AppError('Reconnect this payment account', 'PAYMENT_AUTHORIZATION_REVOKED', 409);
+            return { ...value, ...await open(value.tokenBox, id) };
+        },
+        async setEnabled(id, enabled) {
+            const value = await row(id);
+            // Disabling is always allowed; enabling needs the enrollment's link to be usable here.
+            if (enabled)
+                await usable(value);
+            if (!['active', 'disabled'].includes(value.state))
+                throw new AppError('Reconnect this payment account', 'PAYMENT_AUTHORIZATION_REVOKED', 409);
+            await db.update(enrollments).set({ state: enabled ? 'active' : 'disabled' }).where(eq(enrollments.id, id));
+            if (!enabled)
+                await ctx.payments.cancelPendingCheckouts(id);
+            return { enabled };
+        },
+        async revoke(id) {
+            id = z.string().uuid().parse(id);
+            await db.update(enrollments).set({ state: 'revoked', tokenBox: null }).where(eq(enrollments.id, id));
+            return { connected: false };
+        },
+    };
+}