@relume_io/partner-node 0.0.0-stage → 1.0.0

package/dist/bin.js

@@ -0,0 +1,632 @@
+#!/usr/bin/env node
+import {
+  REQUEST_ID_HEADER,
+  SIGNATURE_HEADER,
+  absent,
+  isEmail,
+  isHttpsUrl,
+  isRecord,
+  isString,
+  isWhole,
+  signCall
+} from "./chunk-LOMLIKT2.js";
+
+// src/cli.ts
+import { parseArgs } from "util";
+
+// src/check.ts
+var CHECK_CHARGE_CREDITS = 2;
+var READ_TIMEOUT_MS = 4e3;
+var CHARGE_TIMEOUT_MS = 4e3;
+var REVERSE_TIMEOUT_MS = 1e4;
+var SKEW_SECONDS = 600;
+var ACCEPT = "accepts a correctly signed call";
+var ROTATION = "accepts a key rotation header, with your key second";
+var OTHER_KEY = "rejects a signature made with another key";
+var TAMPERED = "rejects a body changed after signing";
+var STALE = "rejects a timestamp more than 5 minutes old";
+var FUTURE = "rejects a timestamp more than 5 minutes ahead";
+var UNSIGNED = "rejects a call with no signature";
+var USER_GET = "answers user.get with a valid profile";
+var UNKNOWN_USER = "answers user.get 404 for a user it doesn't know";
+var CREDITS_GET = "answers credits.get with a valid balance";
+var DEBIT = "debits a charge";
+var REPEAT_CHARGE = "debits only once when the same charge is sent twice";
+var DECLINE = "answers 402 to a charge the user can't afford";
+var UNKNOWN_REVERSAL = "changes nothing when an unknown charge is reversed";
+var LATE_CHARGE = "refuses a charge that arrives after its reversal";
+var REVERSAL = "credits back a reversal";
+var REPEAT_REVERSAL = "credits a repeated reversalId only once";
+var WALLET = [
+  DEBIT,
+  REPEAT_CHARGE,
+  DECLINE,
+  UNKNOWN_REVERSAL,
+  LATE_CHARGE,
+  REVERSAL,
+  REPEAT_REVERSAL
+];
+var MALFORMED = Symbol("malformed");
+function isOk(answer) {
+  return answer.answered && answer.ok;
+}
+function parseBody(text) {
+  if (text.trim() === "") return {};
+  try {
+    const value = JSON.parse(text);
+    return isRecord(value) ? value : MALFORMED;
+  } catch {
+    return MALFORMED;
+  }
+}
+function said(answer) {
+  if (!answer.answered) return answer.reason;
+  const error = answer.body !== MALFORMED && isRecord(answer.body.error) ? answer.body.error.code : void 0;
+  return typeof error === "string" ? `answered ${answer.status} (${error})` : `answered ${answer.status}`;
+}
+function profileProblem(body) {
+  if (body === MALFORMED) return "the body isn't a JSON object";
+  const { name, email, avatarUrl } = body;
+  if (!absent(name) && !isString(name, 1, 200)) {
+    return "name must be a string of at most 200 characters";
+  }
+  if (!absent(email) && !isEmail(email)) {
+    return "email must be a valid email address";
+  }
+  if (!absent(avatarUrl) && !isHttpsUrl(avatarUrl)) {
+    return "avatarUrl must be an https URL";
+  }
+  return null;
+}
+function optionalBalanceProblem(body) {
+  if (body === MALFORMED) return "the body isn't a JSON object";
+  if (body.balance === void 0 || isWhole(body.balance, 0)) return null;
+  return `balance was ${JSON.stringify(body.balance)}; leave it out or send a whole number, zero or more`;
+}
+function bodyBalance(body) {
+  return body !== MALFORMED && isWhole(body.balance, 0) ? body.balance : void 0;
+}
+function randomId(prefix) {
+  return `${prefix}_${crypto.randomUUID().replaceAll("-", "")}`;
+}
+function networkReason(error) {
+  const cause = error instanceof Error ? error.cause : void 0;
+  const code = isRecord(cause) ? cause.code : void 0;
+  return typeof code === "string" ? `couldn't connect (${code})` : `couldn't connect (${error instanceof Error ? error.message : String(error)})`;
+}
+async function checkEndpoint(options) {
+  const { url, secretKey, userId } = options;
+  const fetchImpl = options.fetch ?? ((...args) => fetch(...args));
+  const now = options.now ?? Date.now;
+  const nowSeconds = () => Math.floor(now() / 1e3);
+  const results = [];
+  const notes = [];
+  function record(result) {
+    results.push(result);
+    options.onResult?.(result);
+  }
+  async function run(name, check) {
+    let failure;
+    try {
+      failure = await check();
+    } catch (error) {
+      failure = `the checker failed: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    record(
+      failure === null ? { name, status: "pass" } : { name, status: "fail", detail: failure }
+    );
+    return failure === null;
+  }
+  function skip(names, detail) {
+    for (const name of names) record({ name, status: "skip", detail });
+  }
+  async function post(rawBody, header, timeoutMs) {
+    const headers = {
+      "Content-Type": "application/json",
+      [REQUEST_ID_HEADER]: randomId("check")
+    };
+    if (header !== null) headers[SIGNATURE_HEADER] = header;
+    try {
+      const response = await fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: rawBody,
+        redirect: "manual",
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      const text = await response.text();
+      if (response.status >= 300 && response.status < 400) {
+        return {
+          answered: false,
+          reason: `redirected with ${response.status} (Relume never follows redirects)`
+        };
+      }
+      return {
+        answered: true,
+        status: response.status,
+        ok: response.status >= 200 && response.status < 300,
+        body: parseBody(text)
+      };
+    } catch (error) {
+      return {
+        answered: false,
+        reason: error instanceof Error && error.name === "TimeoutError" ? `timed out after ${timeoutMs / 1e3}s` : networkReason(error)
+      };
+    }
+  }
+  async function signed(body, timeoutMs) {
+    const rawBody = JSON.stringify(body);
+    return post(
+      rawBody,
+      await signCall(secretKey, nowSeconds(), rawBody),
+      timeoutMs
+    );
+  }
+  async function readBalance() {
+    const answer = await signed(
+      { type: "credits.get", userId },
+      READ_TIMEOUT_MS
+    );
+    if (!isOk(answer)) {
+      return { failure: `credits.get ${said(answer)}; expected 200` };
+    }
+    if (answer.body === MALFORMED) {
+      return {
+        failure: `credits.get answered ${answer.status} with a body that isn't a JSON object`
+      };
+    }
+    if (!isWhole(answer.body.balance, 0)) {
+      return {
+        failure: `credits.get answered balance ${JSON.stringify(answer.body.balance)}; expected a whole number, zero or more`
+      };
+    }
+    return { balance: answer.body.balance };
+  }
+  const found = { wrongKey: false, balance: null, charged: null, reversed: false };
+  const read = JSON.stringify({ type: "credits.get", userId });
+  const tampered = JSON.stringify({
+    type: "credits.get",
+    userId,
+    note: "changed after signing"
+  });
+  const otherKey = randomId("sk_test_relume_check");
+  const t = nowSeconds();
+  await run(ACCEPT, async () => {
+    const answer = await post(
+      read,
+      await signCall(secretKey, t, read),
+      READ_TIMEOUT_MS
+    );
+    if (isOk(answer)) return null;
+    if (answer.answered && answer.status === 401) {
+      found.wrongKey = true;
+      return `${said(answer)} to a signed credits.get: is --secret-key the key this endpoint verifies with?`;
+    }
+    return `${said(answer)} to a signed credits.get; expected 200`;
+  });
+  if (found.wrongKey) {
+    skip(
+      [
+        ROTATION,
+        OTHER_KEY,
+        TAMPERED,
+        STALE,
+        FUTURE,
+        UNSIGNED,
+        USER_GET,
+        UNKNOWN_USER,
+        CREDITS_GET,
+        ...WALLET
+      ],
+      "needs the endpoint to accept a correctly signed call"
+    );
+    return { ok: false, results, notes };
+  }
+  await run(ROTATION, async () => {
+    const answer = await post(
+      read,
+      await signCall([otherKey, secretKey], t, read),
+      READ_TIMEOUT_MS
+    );
+    return isOk(answer) ? null : `${said(answer)}; accept a call when any v1= value matches your key`;
+  });
+  const forgeries = [
+    [OTHER_KEY, read, await signCall(otherKey, t, read)],
+    [TAMPERED, tampered, await signCall(secretKey, t, read)],
+    [STALE, read, await signCall(secretKey, t - SKEW_SECONDS, read)],
+    [FUTURE, read, await signCall(secretKey, t + SKEW_SECONDS, read)],
+    [UNSIGNED, read, null]
+  ];
+  for (const [name, rawBody, header] of forgeries) {
+    await run(name, async () => {
+      const answer = await post(rawBody, header, READ_TIMEOUT_MS);
+      if (answer.answered && answer.status === 401) return null;
+      if (isOk(answer)) {
+        return `${said(answer)}: it acted on a call Relume didn't sign; answer 401 invalid_signature`;
+      }
+      return `${said(answer)}; expected 401 invalid_signature`;
+    });
+  }
+  await run(USER_GET, async () => {
+    const answer = await signed({ type: "user.get", userId }, READ_TIMEOUT_MS);
+    if (answer.answered && answer.status === 404) {
+      return `answered 404: it doesn't know user "${userId}". Pass a --user your wallet knows`;
+    }
+    if (!isOk(answer)) {
+      return `${said(answer)}; expected 200 { name?, email?, avatarUrl? }`;
+    }
+    return profileProblem(answer.body);
+  });
+  await run(UNKNOWN_USER, async () => {
+    const answer = await signed(
+      { type: "user.get", userId: randomId("u_check_unknown") },
+      READ_TIMEOUT_MS
+    );
+    return answer.answered && answer.status === 404 ? null : `${said(answer)} for a user id your wallet has never seen; expected 404`;
+  });
+  await run(CREDITS_GET, async () => {
+    const result = await readBalance();
+    if ("failure" in result) return result.failure;
+    found.balance = result.balance;
+    return null;
+  });
+  const start = found.balance;
+  if (start === null) {
+    skip(WALLET, "needs a working credits.get");
+    return { ok: false, results, notes };
+  }
+  if (start < CHECK_CHARGE_CREDITS) {
+    skip(
+      WALLET,
+      `user "${userId}" has a balance of ${start}; top it up to at least ${CHECK_CHARGE_CREDITS} (the check gives it back)`
+    );
+    return { ok: false, results, notes };
+  }
+  let current = start;
+  const toReverse = /* @__PURE__ */ new Map();
+  async function expectBalance(delta, what) {
+    const result = await readBalance();
+    if ("failure" in result) return result.failure;
+    const before = current;
+    current = result.balance;
+    if (result.balance === before + delta) return null;
+    return `${what} moved the balance from ${before} to ${result.balance}; expected ${before + delta}`;
+  }
+  async function giveBack(id) {
+    const left = toReverse.get(id);
+    if (left === void 0) return;
+    toReverse.delete(id);
+    const answer = await signed(
+      {
+        type: "credits.reverse",
+        userId,
+        reversalId: randomId("rv_check"),
+        ...left,
+        chargeId: id,
+        reason: "work_failed"
+      },
+      REVERSE_TIMEOUT_MS
+    );
+    if (!isOk(answer)) notes.push(`Giving back charge ${id} ${said(answer)}.`);
+  }
+  async function walletCheck(name, check) {
+    if (await run(name, check)) return;
+    const result = await readBalance();
+    if ("balance" in result) current = result.balance;
+  }
+  try {
+    const chargeId = randomId("ch_check");
+    const charge = JSON.stringify({
+      type: "credits.charge",
+      userId,
+      chargeId,
+      partnerCredits: CHECK_CHARGE_CREDITS,
+      relumeCredits: CHECK_CHARGE_CREDITS,
+      action: "chat.message",
+      description: "Relume conformance check (given back)"
+    });
+    await walletCheck(DEBIT, async () => {
+      toReverse.set(chargeId, {
+        partnerCredits: CHECK_CHARGE_CREDITS,
+        relumeCredits: CHECK_CHARGE_CREDITS
+      });
+      const answer = await post(
+        charge,
+        await signCall(secretKey, nowSeconds(), charge),
+        CHARGE_TIMEOUT_MS
+      );
+      if (!isOk(answer)) {
+        return `${said(answer)} to a charge of ${CHECK_CHARGE_CREDITS} from a balance of ${current}; expected 200`;
+      }
+      found.charged = answer;
+      const problem = optionalBalanceProblem(answer.body) ?? await expectBalance(-CHECK_CHARGE_CREDITS, "the charge");
+      if (problem) return problem;
+      const reported = bodyBalance(answer.body);
+      return reported === void 0 || reported === current ? null : `the charge answered balance ${reported}, but credits.get says ${current}`;
+    });
+    const { charged } = found;
+    if (charged === null) {
+      skip([REPEAT_CHARGE], "needs the first charge to succeed");
+    } else {
+      await walletCheck(REPEAT_CHARGE, async () => {
+        const answer = await post(
+          charge,
+          await signCall(secretKey, nowSeconds(), charge),
+          CHARGE_TIMEOUT_MS
+        );
+        if (!answer.answered || answer.status !== charged.status) {
+          return `the repeat ${said(answer)}, the first ${said(charged)}; answer a repeated chargeId with the first result`;
+        }
+        const moved = await expectBalance(0, "the repeat");
+        if (moved) return `${moved}: it debited the same chargeId twice`;
+        const was = bodyBalance(charged.body);
+        const again = bodyBalance(answer.body);
+        return was === void 0 || again === void 0 || was === again ? null : `the repeat answered balance ${again}, the first ${was}; answer a repeated chargeId with the first result`;
+      });
+    }
+    await walletCheck(DECLINE, async () => {
+      const declinedId = randomId("ch_check");
+      const amount = current + 1;
+      toReverse.set(declinedId, {
+        partnerCredits: amount,
+        relumeCredits: CHECK_CHARGE_CREDITS
+      });
+      const answer = await signed(
+        {
+          type: "credits.charge",
+          userId,
+          chargeId: declinedId,
+          partnerCredits: amount,
+          relumeCredits: CHECK_CHARGE_CREDITS,
+          action: "chat.message",
+          description: "Relume conformance check (should be declined)"
+        },
+        CHARGE_TIMEOUT_MS
+      );
+      if (isOk(answer)) {
+        await giveBack(declinedId);
+        return `${said(answer)}: it accepted a charge of ${amount} from a balance of ${current}; answer 402`;
+      }
+      if (!answer.answered || answer.status !== 402) {
+        if (answer.answered && answer.status < 500)
+          toReverse.delete(declinedId);
+        return `${said(answer)} to a charge of ${amount} from a balance of ${current}; expected 402`;
+      }
+      toReverse.delete(declinedId);
+      const moved = await expectBalance(0, "the declined charge");
+      if (moved) return moved;
+      const said402 = bodyBalance(answer.body);
+      return said402 === void 0 || said402 === current ? null : `the 402 answered balance ${said402}, but credits.get says ${current}`;
+    });
+    const lateId = randomId("ch_check_never_sent");
+    let reversedFirst = false;
+    await walletCheck(UNKNOWN_REVERSAL, async () => {
+      const answer = await signed(
+        {
+          type: "credits.reverse",
+          userId,
+          reversalId: randomId("rv_check"),
+          partnerCredits: CHECK_CHARGE_CREDITS,
+          relumeCredits: CHECK_CHARGE_CREDITS,
+          chargeId: lateId,
+          reason: "charge_unknown"
+        },
+        REVERSE_TIMEOUT_MS
+      );
+      if (!isOk(answer)) {
+        return `${said(answer)}; expected 200, crediting nothing (Relume retries any other answer for 72 hours)`;
+      }
+      reversedFirst = true;
+      const problem = optionalBalanceProblem(answer.body);
+      if (problem) return problem;
+      const moved = await expectBalance(0, "the reversal");
+      return moved && `${moved}: it credited a charge it never debited`;
+    });
+    if (!reversedFirst) {
+      skip([LATE_CHARGE], "needs the reversal of an unknown charge to succeed");
+    } else {
+      await walletCheck(LATE_CHARGE, async () => {
+        toReverse.set(lateId, {
+          partnerCredits: CHECK_CHARGE_CREDITS,
+          relumeCredits: CHECK_CHARGE_CREDITS
+        });
+        const answer = await signed(
+          {
+            type: "credits.charge",
+            userId,
+            chargeId: lateId,
+            partnerCredits: CHECK_CHARGE_CREDITS,
+            relumeCredits: CHECK_CHARGE_CREDITS,
+            action: "chat.message",
+            description: "Relume conformance check (should be refused)"
+          },
+          CHARGE_TIMEOUT_MS
+        );
+        const moved = await expectBalance(0, "the late charge");
+        if (moved) {
+          return `${moved}: it debited a charge it had already answered a reversal for; record a reversed chargeId as declined`;
+        }
+        toReverse.delete(lateId);
+        return isOk(answer) ? `${said(answer)}; expected 402, debiting nothing` : null;
+      });
+    }
+    const reversal = JSON.stringify({
+      type: "credits.reverse",
+      userId,
+      reversalId: randomId("rv_check"),
+      partnerCredits: 1,
+      relumeCredits: 1,
+      chargeId,
+      reason: "work_failed"
+    });
+    if (charged === null) {
+      skip([REVERSAL, REPEAT_REVERSAL], "needs the first charge to succeed");
+    } else {
+      await walletCheck(REVERSAL, async () => {
+        const answer = await post(
+          reversal,
+          await signCall(secretKey, nowSeconds(), reversal),
+          REVERSE_TIMEOUT_MS
+        );
+        if (!isOk(answer)) return `${said(answer)}; expected 200`;
+        found.reversed = true;
+        toReverse.set(chargeId, {
+          partnerCredits: CHECK_CHARGE_CREDITS - 1,
+          relumeCredits: CHECK_CHARGE_CREDITS - 1
+        });
+        return optionalBalanceProblem(answer.body) ?? await expectBalance(1, "a reversal of 1 credit");
+      });
+      if (!found.reversed) {
+        skip([REPEAT_REVERSAL], "needs the reversal to succeed");
+      } else {
+        await walletCheck(REPEAT_REVERSAL, async () => {
+          const answer = await post(
+            reversal,
+            await signCall(secretKey, nowSeconds(), reversal),
+            REVERSE_TIMEOUT_MS
+          );
+          if (!isOk(answer)) return `the repeat ${said(answer)}; expected 200`;
+          const moved = await expectBalance(0, "the repeat");
+          return moved && `${moved}: it credited the same reversalId twice`;
+        });
+      }
+    }
+  } finally {
+    for (const id of [...toReverse.keys()]) await giveBack(id);
+  }
+  const end = await readBalance();
+  if ("failure" in end) {
+    notes.push(`Couldn't read the final balance: ${end.failure}.`);
+  } else if (end.balance !== start) {
+    notes.push(
+      `User "${userId}" has a balance of ${end.balance}; it was ${start} before the check. Correct it in your wallet.`
+    );
+  }
+  const ok = results.every((result) => result.status === "pass");
+  return { ok, results, notes };
+}
+
+// src/cli.ts
+var USAGE = `Usage: npx @relume_io/partner-node check --url <endpoint> --user <userId> [--secret-key <sk_test_\u2026>]
+
+Checks your partner endpoint against the Relume partner protocol: signatures,
+user.get, credits.get, and the idempotency and decline rules for charges and
+reversals.
+
+  --url         The endpoint Relume calls, e.g. https://partner.example/relume/calls
+  --user        A user your wallet knows, with at least ${CHECK_CHARGE_CREDITS} credits. The check
+                charges that user and gives every credit back.
+  --secret-key  Your test secret key. Defaults to $RELUME_SECRET_KEY, which
+                keeps the key out of your shell history and CI logs.
+  --live        Allow an sk_live_ key. The check then charges a real wallet.
+  -h, --help    Show this help.
+
+Exits 0 when every check passes, 1 when any fails or can't run, and 2 for
+bad arguments.`;
+var LABEL = {
+  pass: "PASS",
+  fail: "FAIL",
+  skip: "SKIP"
+};
+async function runCli(args, io) {
+  const usageError = (message) => {
+    io.error(`${message}
+
+${USAGE}`);
+    return 2;
+  };
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        url: { type: "string" },
+        user: { type: "string" },
+        "secret-key": { type: "string" },
+        live: { type: "boolean" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+  } catch (error) {
+    return usageError(error instanceof Error ? error.message : String(error));
+  }
+  const { values, positionals } = parsed;
+  if (values.help) {
+    io.log(USAGE);
+    return 0;
+  }
+  if (positionals.length !== 1 || positionals[0] !== "check") {
+    return usageError(
+      positionals.length === 0 ? "Missing the command: check." : `Unknown command: ${positionals.join(" ")}.`
+    );
+  }
+  const url = values.url?.trim() ?? "";
+  let endpoint;
+  try {
+    endpoint = new URL(url);
+  } catch {
+    return usageError(
+      url === "" ? "--url is required." : `--url isn't a URL: ${url}`
+    );
+  }
+  if (endpoint.protocol !== "https:" && endpoint.protocol !== "http:") {
+    return usageError("--url must be an http or https URL.");
+  }
+  const userId = values.user ?? "";
+  if (userId.length < 1 || userId.length > 128) {
+    return usageError("--user is required: a user id of 1 to 128 characters.");
+  }
+  const secretKey = (values["secret-key"] ?? io.env.RELUME_SECRET_KEY ?? "").trim();
+  if (secretKey === "") {
+    return usageError("Pass --secret-key or set RELUME_SECRET_KEY.");
+  }
+  if (secretKey.startsWith("pk_")) {
+    return usageError(
+      "That is a publishable key. Pass the secret key (sk_test_\u2026)."
+    );
+  }
+  if (secretKey.startsWith("sk_live_") && !values.live) {
+    return usageError(
+      "That is a live key, and the check charges the user. Use your test key, or pass --live to run it against a live wallet."
+    );
+  }
+  io.log(`Checking ${endpoint.href} as user "${userId}"
+`);
+  const report = await checkEndpoint({
+    url: endpoint.href,
+    secretKey,
+    userId,
+    fetch: io.fetch,
+    onResult: (result) => {
+      io.log(`${LABEL[result.status]}  ${result.name}`);
+      if (result.detail) io.log(`      ${result.detail}`);
+    }
+  });
+  const count = (status) => report.results.filter((result) => result.status === status).length;
+  const skipped = count("skip");
+  io.log(
+    `
+${count("pass")} passed, ${count("fail")} failed${skipped ? `, ${skipped} skipped` : ""}`
+  );
+  for (const note of report.notes) io.log(`NOTE  ${note}`);
+  return report.ok ? 0 : 1;
+}
+
+// src/bin.ts
+void runCli(process.argv.slice(2), {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+  env: process.env
+}).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    console.error(
+      `The check stopped: ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exitCode = 1;
+  }
+);
+//# sourceMappingURL=bin.js.map