caelum0x 19291a5d0b feat: add operator console server logic with API client, owner auth and proof formatting
New @settlekit/operator-console (Next.js 14) scaffold and its server-side
libraries: typed operator API client (key sent only on private routes,
envelope/error mapping), HMAC-signed owner session tokens with constant-time
password check, proof view model with per-decision anchored status, policy
drift rows, decision paging, bill form validation, attempt limiter, and the
connect-your-business onboarding over the existing API. Tests include an
onboarding run against the real API app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:19:41 +03:00

306 lines
13 KiB
TypeScript

/**
* "Connect your business" onboarding for external small teams, over the
* existing SettleKit API only:
*
* 1. POST /v1/auth/register (merchant) -> the team's own org + API key
* 2. POST /v1/products (+ /prices, /publish) with the team's key
* 3. POST /v1/checkout-sessions, network "arc", payTo = the team's
* OperatorVault -> a hosted Arc USDC checkout link into the vault
*
* Caps and the payout allowlist are enforced by the team's own OperatorVault
* on Arc. This module renders the exact deploy / setAllowlist commands and
* the matching off-chain policy; it never holds the team's funds or keys.
*/
import { createHash } from "node:crypto";
import type { FetchLike } from "./api-client";
import { PRODUCT_KINDS, type ProductKind } from "./onboarding-kinds";
export { PRODUCT_KINDS, type ProductKind };
export const ARC_TESTNET_RPC = "https://rpc.testnet.arc.network";
export const ARC_TESTNET_USDC = "0x3600000000000000000000000000000000000000";
const ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
const USDC_RE = /^\d{1,12}(\.\d{1,6})?$/;
const MAX_ALLOWLIST = 20;
export interface ConnectInput {
readonly teamName: string;
readonly email: string;
readonly password: string;
readonly productName: string;
readonly productKind: ProductKind;
readonly priceUsdc: string;
readonly ownerAddress: string;
readonly vaultAddress: string | null;
readonly allowlist: readonly string[];
readonly perTxCap: string;
readonly dailyCap: string;
readonly escalateAbove: string;
}
export type FieldErrors = Readonly<Record<string, string>>;
export type ParseResult<T> = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly errors: FieldErrors };
const field = (form: Readonly<Record<string, unknown>>, key: string): string => {
const value = form[key];
return typeof value === "string" ? value.trim() : "";
};
/** USDC decimal -> base units (6 dp), exact. */
export function toBaseUnits(decimal: string): bigint {
const [whole = "0", frac = ""] = decimal.split(".");
return BigInt(whole) * 1_000_000n + BigInt(frac.padEnd(6, "0").slice(0, 6) || "0");
}
function positiveUsdc(value: string): boolean {
return USDC_RE.test(value) && toBaseUnits(value) > 0n;
}
/** Validate the untrusted onboarding form (all errors at once). */
export function parseConnectForm(form: Readonly<Record<string, unknown>>): ParseResult<ConnectInput> {
const errors: Record<string, string> = {};
const teamName = field(form, "teamName");
const email = field(form, "email").toLowerCase();
const password = typeof form.password === "string" ? form.password : "";
const productName = field(form, "productName");
const productKind = field(form, "productKind") as ProductKind;
const priceUsdc = field(form, "priceUsdc");
const ownerAddress = field(form, "ownerAddress");
const vaultRaw = field(form, "vaultAddress");
const allowlist = [...new Set(field(form, "allowlist").split(/[\s,]+/).filter(Boolean).map((a) => a.toLowerCase()))];
const perTxCap = field(form, "perTxCap");
const dailyCap = field(form, "dailyCap");
const escalateAbove = field(form, "escalateAbove");
if (teamName.length < 2 || teamName.length > 80) errors.teamName = "Enter your team or company name (2-80 characters).";
if (!EMAIL_RE.test(email) || email.length > 200) errors.email = "Enter a valid email address.";
if (password.length < 10 || password.length > 200) errors.password = "Use at least 10 characters.";
if (productName.length < 2 || productName.length > 120) errors.productName = "Name what you sell (2-120 characters).";
if (!PRODUCT_KINDS.includes(productKind)) errors.productKind = "Choose a product type.";
if (!positiveUsdc(priceUsdc)) errors.priceUsdc = "Enter a USDC price, e.g. 49 or 49.99.";
if (!ADDRESS_RE.test(ownerAddress)) errors.ownerAddress = "Enter the 0x address of the human who approves escalations.";
if (vaultRaw && !ADDRESS_RE.test(vaultRaw)) errors.vaultAddress = "Vault address must be a 0x address, or leave it empty.";
if (allowlist.length > MAX_ALLOWLIST) errors.allowlist = `At most ${MAX_ALLOWLIST} payees.`;
else if (allowlist.some((a) => !ADDRESS_RE.test(a))) errors.allowlist = "Every payee must be a 0x address.";
for (const [key, value] of [["perTxCap", perTxCap], ["dailyCap", dailyCap]] as const) {
if (!positiveUsdc(value)) errors[key] = "Enter a positive USDC amount.";
}
if (!USDC_RE.test(escalateAbove)) errors.escalateAbove = "Enter a USDC amount (0 escalates every payment).";
if (!errors.perTxCap && !errors.dailyCap && toBaseUnits(perTxCap) > toBaseUnits(dailyCap)) {
errors.perTxCap = "Per-payment cap cannot exceed the daily cap.";
}
if (!errors.escalateAbove && !errors.perTxCap && toBaseUnits(escalateAbove) > toBaseUnits(perTxCap)) {
errors.escalateAbove = "Escalation threshold cannot exceed the per-payment cap.";
}
if (Object.keys(errors).length > 0) return { ok: false, errors };
return {
ok: true,
value: {
teamName,
email,
password,
productName,
productKind,
priceUsdc,
ownerAddress,
vaultAddress: vaultRaw || null,
allowlist,
perTxCap,
dailyCap,
escalateAbove,
},
};
}
/** Deterministic bytes32 for owner setup actions (anchored by DecisionAnchored). */
export function setupHash(label: string): string {
return `0x${createHash("sha256").update(`tameion-onboarding:${label}`).digest("hex")}`;
}
/** Shell commands: deploy the team's OperatorVault, then allowlist payees. */
export function vaultCommands(input: ConnectInput, operatorAddress: string | null): readonly string[] {
const operator = operatorAddress ?? "<OPERATOR_DCW_ADDRESS>";
const deploy = [
`OPERATOR_VAULT_OWNER=${input.ownerAddress}`,
`OPERATOR_VAULT_OPERATOR=${operator}`,
`OPERATOR_PER_TX_CAP=${toBaseUnits(input.perTxCap)}`,
`OPERATOR_DAILY_CAP=${toBaseUnits(input.dailyCap)}`,
`OPERATOR_ESCALATE_ABOVE=${toBaseUnits(input.escalateAbove)}`,
"forge script script/DeployOperator.s.sol",
`--rpc-url ${ARC_TESTNET_RPC}`,
"--private-key $DEPLOYER_KEY --broadcast",
].join(" \\\n ");
const vault = input.vaultAddress ?? "$VAULT";
const allow = input.allowlist.map(
(payee) =>
`cast send ${vault} "setAllowlist(bytes32,address,bool)" ${setupHash(`allowlist:${payee}`)} ${payee} true \\\n --rpc-url ${ARC_TESTNET_RPC} --private-key $OWNER_KEY`,
);
return [`cd contracts && ${deploy}`, ...allow];
}
/** Off-chain policy matching the vault (PUT /v1/operator/policy body). */
export function operatorPolicy(input: ConnectInput): Record<string, unknown> {
return {
split: { OPERATING: 7000, YIELD: 2000, REFUND: 1000 },
taxRateBps: 2500,
perTxCap: input.perTxCap,
dailyCap: input.dailyCap,
escalateAbove: input.escalateAbove,
minFloat: "0",
yieldTarget: "0",
allowlist: [...input.allowlist],
maxX402PerDay: 20,
};
}
export class OnboardingError extends Error {
constructor(
readonly step: "register" | "product" | "price" | "publish" | "checkout" | "lookup",
readonly status: number,
message: string,
) {
super(message);
this.name = "OnboardingError";
}
}
interface Api {
readonly baseUrl: string;
readonly fetchImpl?: FetchLike;
}
async function post<T>(api: Api, step: OnboardingError["step"], path: string, body: unknown, key?: string): Promise<T> {
return send<T>(api, step, "POST", path, body, key);
}
async function send<T>(api: Api, step: OnboardingError["step"], method: "GET" | "POST", path: string, body: unknown, key?: string): Promise<T> {
const fetchImpl: FetchLike = api.fetchImpl ?? ((i, init) => fetch(i, init));
let res: Response;
try {
res = await fetchImpl(`${api.baseUrl.replace(/\/+$/, "")}${path}`, {
method,
headers: { "content-type": "application/json", accept: "application/json", ...(key ? { authorization: `Bearer ${key}` } : {}) },
cache: "no-store",
signal: AbortSignal.timeout(15_000),
...(body !== undefined ? { body: JSON.stringify(body) } : {}),
});
} catch {
throw new OnboardingError(step, 0, "The SettleKit API is unreachable. Try again shortly.");
}
const json = (await res.json().catch(() => ({}))) as { data?: T; error?: { message?: string } };
if (!res.ok || json.data === undefined) {
throw new OnboardingError(step, res.status, json.error?.message ?? `HTTP ${res.status}`);
}
return json.data;
}
export interface CheckoutLink {
readonly sessionId: string;
readonly url: string;
readonly expiresAt: string | null;
}
export interface ConnectResult {
readonly orgId: string;
readonly accountId: string;
/** Shown once; the console never stores it. */
readonly apiKey: string;
readonly productId: string;
readonly priceId: string;
readonly checkout: CheckoutLink | null;
readonly commands: readonly string[];
readonly policy: Record<string, unknown>;
}
interface Registered {
readonly account: { readonly id: string; readonly organizationId?: string };
readonly apiKey?: string;
}
export async function createCheckoutLink(
api: Api,
args: { readonly apiKey: string; readonly merchantId: string; readonly productId: string; readonly priceId: string; readonly vaultAddress: string; readonly checkoutUrl: string },
): Promise<CheckoutLink> {
const session = await post<{ id: string; expiresAt?: string }>(api, "checkout", "/v1/checkout-sessions", {
merchantId: args.merchantId,
items: [{ priceId: args.priceId, productId: args.productId, quantity: 1 }],
payToAddress: args.vaultAddress,
network: "arc",
}, args.apiKey);
return { sessionId: session.id, url: `${args.checkoutUrl.replace(/\/+$/, "")}/c/${session.id}`, expiresAt: session.expiresAt ?? null };
}
/** Run the whole onboarding against the API. */
export async function connectBusiness(api: Api, input: ConnectInput, options: { readonly checkoutUrl: string; readonly operatorAddress: string | null }): Promise<ConnectResult> {
const registered = await post<Registered>(api, "register", "/v1/auth/register", {
email: input.email,
password: input.password,
type: "merchant",
displayName: input.teamName,
});
const apiKey = registered.apiKey;
const orgId = registered.account.organizationId;
if (!apiKey || !orgId) throw new OnboardingError("register", 500, "Registration did not return an organization API key.");
const merchantId = registered.account.id;
const product = await post<{ id: string }>(api, "product", "/v1/products", {
merchantId,
name: input.productName,
description: `${input.teamName} on Arc USDC via SettleKit`,
type: input.productKind,
deliveryMode: "none",
metadata: { source: "tameion-onboarding" },
}, apiKey);
const price = await post<{ id: string }>(api, "price", `/v1/products/${encodeURIComponent(product.id)}/prices`, {
amount: input.priceUsdc,
interval: "one_time",
}, apiKey);
await post(api, "publish", `/v1/products/${encodeURIComponent(product.id)}/publish`, undefined, apiKey);
const checkout = input.vaultAddress
? await createCheckoutLink(api, { apiKey, merchantId, productId: product.id, priceId: price.id, vaultAddress: input.vaultAddress, checkoutUrl: options.checkoutUrl })
: null;
return {
orgId,
accountId: merchantId,
apiKey,
productId: product.id,
priceId: price.id,
checkout,
commands: vaultCommands(input, options.operatorAddress),
policy: operatorPolicy(input),
};
}
export interface LinkInput {
readonly apiKey: string;
readonly productId: string;
readonly priceId: string;
readonly vaultAddress: string;
}
export function parseLinkForm(form: Readonly<Record<string, unknown>>): ParseResult<LinkInput> {
const errors: Record<string, string> = {};
const apiKey = field(form, "apiKey");
const productId = field(form, "productId");
const priceId = field(form, "priceId");
const vaultAddress = field(form, "vaultAddress");
if (apiKey.length < 8 || apiKey.length > 512) errors.apiKey = "Paste the API key you received at signup.";
if (!/^[\w-]{1,128}$/.test(productId)) errors.productId = "Enter the product id.";
if (!/^[\w-]{1,128}$/.test(priceId)) errors.priceId = "Enter the price id.";
if (!ADDRESS_RE.test(vaultAddress)) errors.vaultAddress = "Enter your OperatorVault 0x address.";
if (Object.keys(errors).length > 0) return { ok: false, errors };
return { ok: true, value: { apiKey, productId, priceId, vaultAddress } };
}
/** Later step: once the vault is deployed, mint a checkout link into it. */
export async function linkVault(api: Api, input: LinkInput, checkoutUrl: string): Promise<CheckoutLink> {
const product = await send<{ id: string; merchantId: string }>(api, "lookup", "GET", `/v1/products/${encodeURIComponent(input.productId)}`, undefined, input.apiKey);
return createCheckoutLink(api, { apiKey: input.apiKey, merchantId: product.merchantId, productId: product.id, priceId: input.priceId, vaultAddress: input.vaultAddress, checkoutUrl });
}