@relume_io/partner-node 2.0.0 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Relume Tech PTY LTD
+
+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

@@ -95,6 +95,7 @@ trust where the builder is embedded.
 | Bad or missing signature, or stale `t`       | `401 invalid_signature`; your callback isn't called          |
 | Unknown `type`, or no callback registered    | `400 unsupported_call_type`                                  |
 | Body that isn't valid for its `type`         | `400 invalid_request`                                        |
+| `environment` isn't your secret key's        | `400 environment_mismatch`; your callback isn't called       |
 | `onGetUser` returns `null`                   | `404 user_not_found`                                         |
 | `onChargeCredits` returns `{ ok: false }`    | `402 insufficient_credits`, with `balance`                   |
 | A callback throws, or returns a bad shape    | `500 internal_error`, and `onHandlerError` gets the error    |
@@ -107,8 +108,12 @@ Every response is JSON with `Cache-Control: no-store`.
 
 ## The callbacks
 
-Each callback gets a second argument, `{ type, requestId }`. Quote the
-`requestId` to Relume support.
+Each callback gets a second argument, `{ type, environment, requestId }`.
+Quote the `requestId` to Relume support. `environment` is always your secret
+key's (`'test'` for `sk_test_…`, `'live'` for `sk_live_…`): every call Relume
+signs says which environment it is for, and one for the other environment is
+refused before a callback runs, so a test call can never move a live wallet.
+Still give test and live their own endpoint URLs, each with its own client.
 
 ### `onChargeCredits(charge) → { ok, balance? }`
 
@@ -192,7 +197,7 @@ body, the call is answered `500` and `onHandlerError` explains why.
 
 ```ts
 Relume.init({
-  secretKey: 'sk_test_…', // required; test or live
+  secretKey: 'sk_test_…', // required; sk_test_… or sk_live_…
   apiBaseUrl: 'https://…', // defaults to production; http only for localhost
   apiTimeoutMs: 15_000, // per partner API request attempt
   maxRetries: 2, // retries for 429s, 5xx answers and failed connections
@@ -303,6 +308,8 @@ It calls your endpoint the way Relume does, and checks that it:
 - rejects another key's signature, a body changed after signing, a timestamp
   more than 5 minutes off either way, and a call with no signature, with
   `401`;
+- refuses a correctly signed call whose `environment` isn't the key's, with
+  `400`;
 - answers `user.get` and `credits.get` with bodies Relume accepts, and
   `user.get` with `404` for a user id it has never seen;
 - debits a charge, and only once when the same `chargeId` comes again, with
@@ -320,7 +327,11 @@ It calls your endpoint the way Relume does, and checks that it:
   signed-in user.
 
 It finds the session route next to a `--url` ending in `/calls`; pass
-`--session-url` if yours is elsewhere.
+`--session-url` if yours is elsewhere. If a login answers that route before
+the SDK does, give the check a test user's cookie so it gets past it: in
+`RELUME_SESSION_HEADERS` (one `Name: value` a line), or with
+`--session-header "Cookie: …"` (repeatable). Prefer the variable: a cookie on
+the command line leaks like a key does.
 
 Give it the key in `RELUME_SECRET_KEY`, not `--secret-key`: a key on the
 command line lands in your shell history, CI logs and the process list.
@@ -360,3 +371,7 @@ npm run test:dist   # builds, then loads the ESM and CJS output
 
 Releases go out from CI on a `partner-sdk/v*` tag, together with
 `@relume_io/partner-embed`: see [Releasing](../README.md#releasing).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/bin.cjs

@@ -30,6 +30,13 @@ function isHttpsUrl(value) {
   }
 }
 
+// src/calls.ts
+function keyEnvironment(secretKey) {
+  if (secretKey.startsWith("sk_test_")) return "test";
+  if (secretKey.startsWith("sk_live_")) return "live";
+  return null;
+}
+
 // src/session.ts
 var EMBED_HEADER = "Relume-Embed";
 var EMBED_HEADER_VALUE = "1";
@@ -116,6 +123,7 @@ 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 OTHER_ENVIRONMENT = "refuses a call for the other environment";
 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";
@@ -192,6 +200,11 @@ function networkReason(error) {
 }
 async function checkEndpoint(options) {
   const { url, secretKey, userId } = options;
+  const environment = keyEnvironment(secretKey);
+  if (environment === null) {
+    throw new TypeError("The secret key must start with sk_test_ or sk_live_.");
+  }
+  const otherEnvironment = environment === "test" ? "live" : "test";
   const fetchImpl = options.fetch ?? ((...args) => fetch(...args));
   const now = options.now ?? Date.now;
   const nowSeconds = () => Math.floor(now() / 1e3);
@@ -260,7 +273,7 @@ async function checkEndpoint(options) {
   }
   async function readBalance() {
     const answer = await signed(
-      { type: "credits.get", userId },
+      { type: "credits.get", environment, userId },
       READ_TIMEOUT_MS
     );
     if (!isOk(answer)) {
@@ -282,6 +295,7 @@ async function checkEndpoint(options) {
     try {
       const response = await fetchImpl(sessionUrl2, {
         ...init,
+        headers: { ...options.sessionHeaders, ...init.headers },
         redirect: "manual",
         signal: AbortSignal.timeout(READ_TIMEOUT_MS)
       });
@@ -354,7 +368,7 @@ async function checkEndpoint(options) {
     });
     if (answer.answered && answer.status === status) return null;
     if (answer.answered && answer.status === 401) {
-      return `${said(answer)}: it looked for a signed-in user first. Answer ${status} ${code} before reading the user`;
+      return options.sessionHeaders ? `${said(answer)} with the session headers: they didn't get past the login (an expired cookie?), or the route looked for a signed-in user first. Answer ${status} ${code} before reading the user` : `${said(answer)}: something asked for a signed-in user first. If that's a login in front of the route, pass --session-header with a test user's cookie so the check gets past it; otherwise answer ${status} ${code} before reading the user`;
     }
     return `${said(answer)}; expected ${status} ${code}`;
   }
@@ -389,9 +403,10 @@ async function checkEndpoint(options) {
     }
   }
   const found = { wrongKey: false, balance: null, charged: null, reversed: false };
-  const read = JSON.stringify({ type: "credits.get", userId });
+  const read = JSON.stringify({ type: "credits.get", environment, userId });
   const tampered = JSON.stringify({
     type: "credits.get",
+    environment,
     userId,
     note: "changed after signing"
   });
@@ -419,6 +434,7 @@ async function checkEndpoint(options) {
         STALE,
         FUTURE,
         UNSIGNED,
+        OTHER_ENVIRONMENT,
         USER_GET,
         UNKNOWN_USER,
         CREDITS_GET,
@@ -453,8 +469,22 @@ async function checkEndpoint(options) {
       return `${said(answer)}; expected 401 invalid_signature`;
     });
   }
+  await run(OTHER_ENVIRONMENT, async () => {
+    const answer = await signed(
+      { type: "credits.get", environment: otherEnvironment, userId },
+      READ_TIMEOUT_MS
+    );
+    if (answer.answered && answer.status === 400) return null;
+    if (isOk(answer)) {
+      return `${said(answer)} to a ${otherEnvironment} call signed with your ${environment} key: check the body's environment is your key's, and answer 400 environment_mismatch`;
+    }
+    return `${said(answer)}; expected 400 environment_mismatch`;
+  });
   await run(USER_GET, async () => {
-    const answer = await signed({ type: "user.get", userId }, READ_TIMEOUT_MS);
+    const answer = await signed(
+      { type: "user.get", environment, 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`;
     }
@@ -465,7 +495,7 @@ async function checkEndpoint(options) {
   });
   await run(UNKNOWN_USER, async () => {
     const answer = await signed(
-      { type: "user.get", userId: randomId("u_check_unknown") },
+      { type: "user.get", environment, 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`;
@@ -505,6 +535,7 @@ async function checkEndpoint(options) {
     const answer = await signed(
       {
         type: "credits.reverse",
+        environment,
         userId,
         reversalId: randomId("rv_check"),
         ...left,
@@ -524,6 +555,7 @@ async function checkEndpoint(options) {
     const chargeId = randomId("ch_check");
     const charge = JSON.stringify({
       type: "credits.charge",
+      environment,
       userId,
       chargeId,
       partnerCredits: CHECK_CHARGE_CREDITS,
@@ -580,6 +612,7 @@ async function checkEndpoint(options) {
       const answer = await signed(
         {
           type: "credits.charge",
+          environment,
           userId,
           chargeId: declinedId,
           partnerCredits: amount,
@@ -610,6 +643,7 @@ async function checkEndpoint(options) {
       const answer = await signed(
         {
           type: "credits.reverse",
+          environment,
           userId,
           reversalId: randomId("rv_check"),
           partnerCredits: CHECK_CHARGE_CREDITS,
@@ -639,6 +673,7 @@ async function checkEndpoint(options) {
         const answer = await signed(
           {
             type: "credits.charge",
+            environment,
             userId,
             chargeId: lateId,
             partnerCredits: CHECK_CHARGE_CREDITS,
@@ -658,6 +693,7 @@ async function checkEndpoint(options) {
     }
     const reversal = JSON.stringify({
       type: "credits.reverse",
+      environment,
       userId,
       reversalId: randomId("rv_check"),
       partnerCredits: 1,
@@ -724,6 +760,12 @@ reversals. It also checks that another site can't read your session route.
                  charges that user and gives every credit back.
   --session-url  The session route your page's embed calls. Defaults to
                  /session next to a --url ending in /calls.
+  --session-header
+                 A header for every request to the session route, as
+                 "Name: value". Repeatable. Pass a test user's cookie when a
+                 login answers that route before the SDK does. Prefer
+                 $RELUME_SESSION_HEADERS, one header a line: a cookie is a
+                 credential too.
   --secret-key   Your test secret key. Prefer $RELUME_SECRET_KEY, the default:
                  a key on the command line lands in your shell history, CI
                  logs and the process list.
@@ -732,6 +774,9 @@ reversals. It also checks that another site can't read your session route.
 
 Exits 0 when every check passes, 1 when any fails or can't run, and 2 for
 bad arguments.`;
+var HEADER_NAME = /^[!#$%&'*+.^`|~\w-]+$/;
+var HEADER_VALUE = /^[\t\x20-\x7e\x80-\xff]*$/;
+var PROBE_HEADERS = /^(relume-embed|origin|sec-fetch-.*|access-control-request-.*)$/i;
 var LABEL = {
   pass: "PASS",
   fail: "FAIL",
@@ -753,6 +798,7 @@ ${USAGE}`);
         url: { type: "string" },
         user: { type: "string" },
         "session-url": { type: "string" },
+        "session-header": { type: "string", multiple: true },
         "secret-key": { type: "string" },
         live: { type: "boolean" },
         help: { type: "boolean", short: "h" }
@@ -796,6 +842,27 @@ ${USAGE}`);
     }
     sessionUrl = parsed2.href;
   }
+  const headerLines = values["session-header"] ?? (io.env.RELUME_SESSION_HEADERS ?? "").split("\n").filter((line) => line.trim() !== "");
+  let sessionHeaders;
+  for (const header of headerLines) {
+    const colon = header.indexOf(":");
+    const name = header.slice(0, colon).trim();
+    const value = header.slice(colon + 1).trim();
+    if (colon < 0 || !HEADER_NAME.test(name)) {
+      return usageError('Each session header must be "Name: value".');
+    }
+    if (!HEADER_VALUE.test(value)) {
+      return usageError(
+        `The ${name} session header's value has characters a header can't carry.`
+      );
+    }
+    if (PROBE_HEADERS.test(name)) {
+      return usageError(
+        `A session header can't set ${name}: the check sets it to test the route.`
+      );
+    }
+    sessionHeaders = { ...sessionHeaders, [name]: value };
+  }
   const userId = values.user ?? "";
   if (userId.length < 1 || userId.length > 128) {
     return usageError("--user is required: a user id of 1 to 128 characters.");
@@ -809,6 +876,11 @@ ${USAGE}`);
       "That is a publishable key. Pass the secret key (sk_test_\u2026)."
     );
   }
+  if (keyEnvironment(secretKey) === null) {
+    return usageError(
+      "The secret key must start with sk_test_ (or sk_live_ with --live)."
+    );
+  }
   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."
@@ -821,6 +893,7 @@ ${USAGE}`);
     secretKey,
     userId,
     sessionUrl,
+    sessionHeaders,
     fetch: io.fetch,
     onResult: (result) => {
       io.log(`${LABEL[result.status]}  ${result.name}`);