@relume_io/partner-node 1.0.0 → 2.0.1

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

@@ -60,10 +60,10 @@ Then, in Relume's partner settings, set your endpoint URL to
 
 ## What it mounts
 
-| Route                 | Called by                  | Does                                                                                                                  |
-| --------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `GET /relume/session` | `@relume_io/partner-embed` | Resolves the user with `getUserIdFromRequest`, calls `POST /sessions`, returns `{ clientSecret, expiresAt }`.         |
-| `POST /relume/calls`  | Relume                     | Verifies `Relume-Signature` and the 5-minute window, routes by `type`, runs your callback, validates what it returns. |
+| Route                 | Called by                  | Does                                                                                                                                |
+| --------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /relume/session` | `@relume_io/partner-embed` | Refuses another site, resolves the user with `getUserIdFromRequest`, calls `POST /sessions`, returns `{ clientSecret, expiresAt }`. |
+| `POST /relume/calls`  | Relume                     | Verifies `Relume-Signature` and the 5-minute window, routes by `type`, runs your callback, validates what it returns.               |
 
 `relume.express()` answers exactly `/session` and `/calls` under its mount
 path (`app.use('/relume', …)`), or `/relume/session` and `/relume/calls` when
@@ -75,20 +75,33 @@ CORS preflights (`OPTIONS`) are left to your app: `express()` passes them on
 to the next middleware, and `fetchHandler` answers `204` with no CORS headers.
 
 If your backend is on another origin from your page, pass `sessionUrl` to
-`Relume.init` in the embed and allow your page's origin, with credentials, in
-that route's CORS response. Use an exact allowlist: never reflect the request
-`Origin` and never use `*`.
-
-| Situation                                 | Answer                                                       |
-| ----------------------------------------- | ------------------------------------------------------------ |
-| 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`                                        |
-| `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    |
-| Nobody signed in (session route)          | `401 not_signed_in`                                          |
-| `POST /sessions` refused (session route)  | Relume's status and `{ error }`, e.g. `403 user_deactivated` |
+`Relume.init` in the embed and allow your page's origin, with credentials and
+the `Relume-Embed` header, in that route's CORS response. Use an exact
+allowlist: never reflect the request `Origin` and never use `*`.
+
+Any site can make a signed-in user's browser call the session route, so it
+refuses two things before it looks at the user: a request with
+`Sec-Fetch-Site: cross-site`, which only another site's page sends, and one
+without the `Relume-Embed: 1` header `@relume_io/partner-embed` sends. The
+header makes a cross-origin request need a CORS preflight, so a link or form
+on another site can't get one. Neither helps against a script on your own
+page: any script there can ask the route for a session for the signed-in
+user, or answer the builder's session request with a client secret for
+another of your users, which opens the builder as them. Load only scripts you
+trust where the builder is embedded.
+
+| Situation                                    | Answer                                                       |
+| -------------------------------------------- | ------------------------------------------------------------ |
+| 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`                                        |
+| `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    |
+| No `Relume-Embed: 1` header (session route)  | `400 embed_header_missing`, and `onHandlerError` says why    |
+| `Sec-Fetch-Site: cross-site` (session route) | `403 cross_site_request`                                     |
+| Nobody signed in (session route)             | `401 not_signed_in`                                          |
+| `POST /sessions` refused (session route)     | Relume's status and `{ error }`, e.g. `403 user_deactivated` |
 
 Every response is JSON with `Cache-Control: no-store`.
 
@@ -135,7 +148,8 @@ A whole number of your own credits, zero or more.
 Read the user from your own session. Never take a user id from the query
 string or body. Gets the Express/Node request for `express()`, or the
 `Request` for `fetchHandler`. Pass that type to `Relume.init<…>` to type
-`req`; it is `unknown` otherwise.
+`req`; it must have `headers` (`SessionRequest`), which every framework's
+request does, and is `{ headers: unknown }` otherwise.
 
 ## Other frameworks
 
@@ -164,6 +178,8 @@ export default { fetch: (request: Request) => relume.fetchHandler(request) };
 
 **Anything else:** call `relume.handleCall({ rawBody, signatureHeader, requestId })`
 and `relume.handleSession(request)`. Each returns `{ status, headers, body }`.
+`handleSession` reads the request's headers, so pass it the fetch `Request`,
+the Node request, or an object with `headers`.
 
 ### Raw bodies
 
@@ -177,7 +193,7 @@ body, the call is answered `500` and `onHandlerError` explains why.
 ```ts
 Relume.init({
   secretKey: 'sk_test_…', // required; test or live
-  apiBaseUrl: 'https://…', // defaults to production
+  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
   fetch, // custom fetch for partner API requests
@@ -186,7 +202,9 @@ Relume.init({
 ```
 
 `Relume.init` returns a new client every time, with no global state, so test
-and live clients can run side by side.
+and live clients can run side by side. It throws for an `apiBaseUrl` that
+isn't `https`, except `http://localhost`, `127.0.0.1` and `[::1]`: every request
+carries your secret key.
 
 ## Calling the partner API
 
@@ -293,8 +311,23 @@ It calls your endpoint the way Relume does, and checks that it:
 - changes nothing when a charge it never debited is reversed, and debits
   nothing if that charge arrives afterwards (record a reversed `chargeId` as
   declined, see `onReverseCharge` above);
-- credits a reversal, and only once per `reversalId`.
-
+- credits a reversal, and only once per `reversalId`;
+- doesn't let another site read the session route: it asks for a session from
+  `https://evil.example`, preflight and `GET`, and fails if the CORS response
+  grants that origin;
+- refuses a session request without the `Relume-Embed` header with `400`, and
+  one with `Sec-Fetch-Site: cross-site` with `403`, before looking for a
+  signed-in user.
+
+It finds the session route next to a `--url` ending in `/calls`; pass
+`--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.
 `--user` must be a user your wallet knows, holding at least 2 credits. The
 check charges them 2 and reverses everything it charged, and it prints a
 `NOTE` if the balance doesn't end where it started. Each check prints `PASS`,
@@ -331,3 +364,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,10 @@ function isHttpsUrl(value) {
   }
 }
 
+// src/session.ts
+var EMBED_HEADER = "Relume-Embed";
+var EMBED_HEADER_VALUE = "1";
+
 // src/signing.ts
 var SIGNATURE_HEADER = "Relume-Signature";
 var REQUEST_ID_HEADER = "Relume-Request-Id";
@@ -100,6 +104,11 @@ var READ_TIMEOUT_MS = 4e3;
 var CHARGE_TIMEOUT_MS = 4e3;
 var REVERSE_TIMEOUT_MS = 1e4;
 var SKEW_SECONDS = 600;
+var FOREIGN_ORIGIN = "https://evil.example";
+var SESSION_CORS = "doesn't let another site read the session route";
+var SESSION_HEADER = "refuses a session request without the Relume-Embed header";
+var SESSION_CROSS_SITE = "refuses a session request from another site";
+var SESSION_CHECKS = [SESSION_CORS, SESSION_HEADER, SESSION_CROSS_SITE];
 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";
@@ -166,6 +175,13 @@ function optionalBalanceProblem(body) {
 function bodyBalance(body) {
   return body !== MALFORMED && isWhole(body.balance, 0) ? body.balance : void 0;
 }
+function sessionUrlFor(callsUrl) {
+  const url = new URL(callsUrl);
+  if (!/\/calls\/?$/.test(url.pathname)) return null;
+  url.pathname = url.pathname.replace(/calls\/?$/, "session");
+  url.search = "";
+  return url.href;
+}
 function randomId(prefix) {
   return `${prefix}_${crypto.randomUUID().replaceAll("-", "")}`;
 }
@@ -262,6 +278,117 @@ async function checkEndpoint(options) {
     }
     return { balance: answer.body.balance };
   }
+  async function askSession(sessionUrl2, init) {
+    try {
+      const response = await fetchImpl(sessionUrl2, {
+        ...init,
+        headers: { ...options.sessionHeaders, ...init.headers },
+        redirect: "manual",
+        signal: AbortSignal.timeout(READ_TIMEOUT_MS)
+      });
+      const text = await response.text();
+      return {
+        answer: {
+          answered: true,
+          status: response.status,
+          ok: response.status >= 200 && response.status < 300,
+          body: parseBody(text)
+        },
+        allowOrigin: response.headers.get("access-control-allow-origin")?.trim() ?? null
+      };
+    } catch (error) {
+      const reason = error instanceof Error && error.name === "TimeoutError" ? `timed out after ${READ_TIMEOUT_MS / 1e3}s` : networkReason(error);
+      return { answer: { answered: false, reason }, allowOrigin: null };
+    }
+  }
+  const session = { answered: false };
+  async function sessionCorsProblem(sessionUrl2) {
+    const probes = [
+      [
+        "the preflight",
+        {
+          method: "OPTIONS",
+          headers: {
+            Origin: FOREIGN_ORIGIN,
+            "Access-Control-Request-Method": "GET",
+            "Access-Control-Request-Headers": EMBED_HEADER.toLowerCase()
+          }
+        }
+      ],
+      [
+        "GET",
+        {
+          method: "GET",
+          headers: {
+            Origin: FOREIGN_ORIGIN,
+            [EMBED_HEADER]: EMBED_HEADER_VALUE,
+            "Sec-Fetch-Site": "cross-site",
+            "Sec-Fetch-Mode": "cors"
+          }
+        }
+      ]
+    ];
+    let problem = null;
+    for (const [what, init] of probes) {
+      const { answer, allowOrigin } = await askSession(sessionUrl2, init);
+      if (!answer.answered) return `${what} to ${sessionUrl2} ${answer.reason}`;
+      if (allowOrigin === FOREIGN_ORIGIN) {
+        problem ??= `${what} to ${sessionUrl2} from ${FOREIGN_ORIGIN} answered Access-Control-Allow-Origin: ${FOREIGN_ORIGIN}, so a page on any site can read what this route answers for a signed-in user. Allow only your own page origins, never the request's Origin`;
+      }
+      if (init.method === "GET") {
+        session.answered = true;
+      }
+    }
+    return problem;
+  }
+  async function sessionRouteMissing(sessionUrl2) {
+    const { answer } = await askSession(sessionUrl2, {
+      method: "GET",
+      headers: { [EMBED_HEADER]: EMBED_HEADER_VALUE }
+    });
+    return answer.answered && answer.status === 404;
+  }
+  async function sessionRefusalProblem(sessionUrl2, headers, status, code) {
+    const { answer } = await askSession(sessionUrl2, {
+      method: "GET",
+      headers
+    });
+    if (answer.answered && answer.status === status) return null;
+    if (answer.answered && answer.status === 401) {
+      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}`;
+  }
+  const sessionUrl = options.sessionUrl ?? sessionUrlFor(url);
+  const notFound = sessionUrl && await sessionRouteMissing(sessionUrl);
+  if (sessionUrl === null || notFound) {
+    skip(
+      SESSION_CHECKS,
+      sessionUrl === null ? "--url doesn't end in /calls; pass --session-url with the session route your page's embed calls" : `GET ${sessionUrl} answered 404; pass --session-url with the session route your page's embed calls`
+    );
+  } else {
+    await run(SESSION_CORS, () => sessionCorsProblem(sessionUrl));
+    if (!session.answered) {
+      skip(SESSION_CHECKS.slice(1), "needs the session route to answer");
+    } else {
+      await run(
+        SESSION_HEADER,
+        () => sessionRefusalProblem(sessionUrl, {}, 400, "embed_header_missing")
+      );
+      await run(
+        SESSION_CROSS_SITE,
+        () => sessionRefusalProblem(
+          sessionUrl,
+          {
+            [EMBED_HEADER]: EMBED_HEADER_VALUE,
+            "Sec-Fetch-Site": "cross-site"
+          },
+          403,
+          "cross_site_request"
+        )
+      );
+    }
+  }
   const found = { wrongKey: false, balance: null, charged: null, reversed: false };
   const read = JSON.stringify({ type: "credits.get", userId });
   const tampered = JSON.stringify({
@@ -587,22 +714,34 @@ async function checkEndpoint(options) {
 }
 
 // src/cli.ts
-var USAGE = `Usage: npx @relume_io/partner-node check --url <endpoint> --user <userId> [--secret-key <sk_test_\u2026>]
+var USAGE = `Usage: RELUME_SECRET_KEY=sk_test_\u2026 npx @relume_io/partner-node check --url <endpoint> --user <userId>
 
 Checks your partner endpoint against the Relume partner protocol: signatures,
 user.get, credits.get, and the idempotency and decline rules for charges and
-reversals.
+reversals. It also checks that another site can't read your session route.
 
-  --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.
+  --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.
+  --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.
+  --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 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",
@@ -623,6 +762,8 @@ ${USAGE}`);
       options: {
         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" }
@@ -653,6 +794,40 @@ ${USAGE}`);
   if (endpoint.protocol !== "https:" && endpoint.protocol !== "http:") {
     return usageError("--url must be an http or https URL.");
   }
+  let sessionUrl;
+  if (values["session-url"] !== void 0) {
+    const value = values["session-url"].trim();
+    let parsed2 = null;
+    try {
+      parsed2 = new URL(value);
+    } catch {
+    }
+    if (parsed2?.protocol !== "https:" && parsed2?.protocol !== "http:") {
+      return usageError(`--session-url must be an http or https URL: ${value}`);
+    }
+    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.");
@@ -677,6 +852,8 @@ ${USAGE}`);
     url: endpoint.href,
     secretKey,
     userId,
+    sessionUrl,
+    sessionHeaders,
     fetch: io.fetch,
     onResult: (result) => {
       io.log(`${LABEL[result.status]}  ${result.name}`);