@lanes-sh/link 0.3.2 → 0.4.1

package/src/providers/bunq/specs/vendor.ts

@@ -0,0 +1,396 @@
+/**
+ * Vendor a trimmed OpenAPI spec for bunq.
+ *
+ * The output is **committed**, for the reason the Google script gives and then
+ * some: a spec decides which paths get called with the operator's credential,
+ * and this credential moves money. `connect` grants everything a provider
+ * discovers, so the reviewable surface has to be a file in the repository
+ * rather than a document fetched from GitHub at connect time.
+ *
+ * bunq's published spec cannot be used as it stands, and not marginally. It is
+ * 1.37 MB across 271 paths, and generating tools from it fails on **55
+ * operations with `Maximum call stack size exceeded`** — including every single
+ * payment endpoint, because `Payment` recurses through `RequestInquiry` and
+ * `RequestResponse` and `mcp-from-openapi` inlines `$ref`s. `cutCycles` is what
+ * makes this provider possible at all; without it there is nothing here worth
+ * shipping.
+ *
+ *   bun run vendor:bunq
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { OpenAPIToolGenerator, type McpOpenAPITool } from 'mcp-from-openapi';
+import { cutCycles, referenced, type Spec } from '../../shared/openapi.ts';
+import { projectRequestBody } from '../../shared/vendor-operations.ts';
+
+const SOURCE = 'https://raw.githubusercontent.com/bunq/doc/master/swagger.json';
+const OUT = 'bunq.v1.json';
+
+/** Kept in step with `BUDGET_KB` in `src/cli/tools.test.ts`, which enforces it. */
+const BUDGET_KB = 64;
+
+/**
+ * Everything this provider can reach, and nothing else.
+ *
+ * The list *is* the security boundary, ahead of policy and ahead of the
+ * connection's bundles: an operation absent here has no tool, so no rule can
+ * allow it and no agent can find it. Adding a line is the decision worth
+ * arguing about, which is why each one says why it is here.
+ *
+ * Reading: what an agent needs to know before it can pay anything — which
+ * accounts exist, what is in them, and what has already gone out.
+ *
+ * Writing: the three shapes bunq offers for sending money. `Payment` executes
+ * immediately. `DraftPayment` does not — it waits for approval in the bunq app,
+ * which is the human checkpoint, and `UPDATE_DraftPayment` is how one is
+ * cancelled or accepted. `PaymentBatch` is up to 350 payments in one call,
+ * which is the whole point of automating a payment run rather than a payment.
+ */
+const OPERATIONS = [
+  // Read. `List_all_User` first because every other path is addressed under a
+  // userID, and nothing reports it but this.
+  'List_all_User',
+  'List_all_MonetaryAccount_for_User',
+  'List_all_Payment_for_User_MonetaryAccount',
+  'READ_Payment_for_User_MonetaryAccount',
+  'List_all_DraftPayment_for_User_MonetaryAccount',
+  'READ_DraftPayment_for_User_MonetaryAccount',
+  'List_all_PaymentBatch_for_User_MonetaryAccount',
+  // Write.
+  'CREATE_Payment_for_User_MonetaryAccount',
+  'CREATE_DraftPayment_for_User_MonetaryAccount',
+  'UPDATE_DraftPayment_for_User_MonetaryAccount',
+  'CREATE_PaymentBatch_for_User_MonetaryAccount',
+  //
+  // Not vendored, deliberately:
+  //
+  // `CREATE_RequestInquiry_*` — 355 KB generated, 5.5x the per-tool budget on
+  // its own, and it asks *for* money rather than sending it. Neither half of
+  // that is worth solving for a capability nobody asked for.
+  //
+  // `schedule-payment` and `schedule` — recurring payments. They fail cycle
+  // cutting as well, and a standing order that an agent can create is a
+  // different risk from a payment it can make: one is a decision taken once,
+  // the other repeats without anybody looking. The bunq app does this well.
+  //
+  // Every `monetary-account-*` creation path — opening and closing accounts is
+  // not paying bills, and `CREATE_MonetaryAccountBank` is a 15 KB body whose
+  // only purpose here would be to widen what a compromised session can do.
+  //
+  // `card-*` — ordering and freezing cards, same argument.
+] as const;
+
+const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head'];
+
+/**
+ * Drop every referenced parameter, which for bunq means every protocol header.
+ *
+ * bunq declares seven headers on almost every operation — `Cache-Control`,
+ * `User-Agent`, `X-Bunq-Language`, `X-Bunq-Region`, `X-Bunq-Geolocation`,
+ * `X-Bunq-Client-Request-Id` and `X-Bunq-Client-Authentication` — and the
+ * generator turns each into a tool argument. That is wrong twice over. They are
+ * noise on every schema, and the last one is the **session token**: leaving it
+ * as an argument invites a model to fill it in, and means a tool call could
+ * carry a credential the strategy is supposed to own.
+ *
+ * Every parameter bunq puts in `components.parameters` is one of these, so
+ * dropping referenced parameters wholesale is exact rather than a heuristic —
+ * the path parameters that must survive are declared inline. Google's script
+ * needs a name list for the same job because Google mixes the two.
+ */
+function dropProtocolParameters(item: Record<string, unknown>): number {
+  let dropped = 0;
+
+  const filter = (holder: Record<string, unknown>): void => {
+    const parameters = holder['parameters'];
+    if (!Array.isArray(parameters)) return;
+
+    const kept = parameters.filter((parameter) => {
+      const reference = (parameter as { $ref?: string }).$ref;
+      if (typeof reference !== 'string' || !reference.startsWith('#/components/parameters/')) {
+        return true;
+      }
+      dropped++;
+      return false;
+    });
+
+    if (kept.length > 0) holder['parameters'] = kept;
+    else delete holder['parameters'];
+  };
+
+  filter(item);
+  for (const [method, operation] of Object.entries(item)) {
+    if (!METHODS.includes(method)) continue;
+    filter(operation as Record<string, unknown>);
+  }
+
+  return dropped;
+}
+
+/**
+ * Strip the properties OpenAPI already marks as response-only.
+ *
+ * bunq describes a request body by pointing at the *whole* resource, so the
+ * body schema for creating a payment carries `id`, `created`, `updated`,
+ * `balance_after_mutation` and two dozen more — fields bunq computes and
+ * ignores on the way in. The document says so itself: they carry
+ * `readOnly: true`, which the specification defines as "MAY be sent as part of
+ * a response and SHOULD NOT be sent as part of the request".
+ *
+ * So this is the document's own judgement applied rather than ours invented,
+ * which is the difference between this and a hand-written field list that would
+ * go stale. It is safe only because responses have already been replaced above:
+ * these schemas are now reachable from request bodies alone.
+ *
+ * **A schema left with nothing is opened rather than emptied.** Nine of bunq's
+ * are, `LabelMonetaryAccount` among them — and that one is `counterparty_alias`
+ * on a payment, which is to say the single field that decides who gets the
+ * money. Every property of it is marked read-only because the document points
+ * the *request* at the response type; what a payment actually takes there is a
+ * `Pointer`, `{ type, value, name }`, as bunq's own guide says and as this
+ * provider's `hints` repeat. Neither shape is worth asserting from here. What
+ * matters is the difference between `{}` — which reads as "this field takes
+ * nothing", and is the one thing that is certainly false — and an open object,
+ * which reads as "send what the description says".
+ */
+function dropReadOnly(node: unknown): number {
+  if (node === null || typeof node !== 'object') return 0;
+  if (Array.isArray(node)) return node.reduce<number>((total, item) => total + dropReadOnly(item), 0);
+
+  let dropped = 0;
+  const record = node as Record<string, unknown>;
+  const properties = record['properties'];
+
+  if (properties && typeof properties === 'object') {
+    const fields = properties as Record<string, unknown>;
+    const writable = Object.entries(fields).filter(
+      ([, schema]) => (schema as { readOnly?: boolean })?.readOnly !== true,
+    );
+
+    if (writable.length === 0 && Object.keys(fields).length > 0) {
+      delete record['properties'];
+      record['additionalProperties'] = true;
+      record['description'] =
+        `${record['description'] ?? ''} Every field bunq documents here is read-only, so its request shape is not described by the specification — send the object the tool description names.`.trim();
+      return dropped;
+    }
+
+    for (const [name, schema] of Object.entries(fields)) {
+      if ((schema as { readOnly?: boolean })?.readOnly === true) {
+        delete fields[name];
+        dropped++;
+      }
+    }
+  }
+
+  for (const value of Object.values(record)) dropped += dropReadOnly(value);
+  return dropped;
+}
+
+/**
+ * The operations bunq describes with the schema of a *different* operation.
+ *
+ * `PUT .../draft-payment/{itemId}` points at `DraftPayment`, the same schema as
+ * the `POST` that creates one, which requires `entries` and
+ * `number_of_required_accepts`. For a create those two *are* the payment. For an
+ * update bunq refuses both as superfluous — its own generated SDK sends only
+ * `status`, `previous_updated_timestamp` and `schedule` here — so the tool asked
+ * for exactly what the bank rejects and every accept failed. Worse than the
+ * error: made to send `entries` for a draft that has them, a model reaches for
+ * the array echoed back or for `[]`, and both ask bunq to rewrite what the draft
+ * pays on the way to approving it. A hint cannot fix a required argument, which
+ * is the difference between this and the `payments`-is-really-an-array note
+ * above: nothing stops an agent sending an array, and nothing lets it omit a
+ * required field. `required` is asserted here rather than projected because
+ * bunq's own is the one written for the create.
+ *
+ * `schedule` is deliberately not projected: it carries `recurrence_unit` and
+ * `recurrence_size`, so approving a one-off draft would be a place to acquire a
+ * standing order — the risk `OPERATIONS` gives for leaving the scheduling
+ * *endpoints* out. Not the whole of that risk, though: `CREATE_DraftPayment`
+ * still offers the same field, because it comes with bunq's create schema.
+ * Closing that changes what the provider can do rather than whether a call
+ * works, and is not done here.
+ */
+const UPDATE_BODIES: Record<string, readonly string[]> = {
+  UPDATE_DraftPayment_for_User_MonetaryAccount: ['status', 'previous_updated_timestamp'],
+};
+
+async function vendor(): Promise<void> {
+  const response = await fetch(SOURCE);
+  if (!response.ok) throw new Error(`${SOURCE}: HTTP ${response.status}`);
+  const spec = (await response.json()) as Spec;
+
+  const wanted = new Set<string>(OPERATIONS);
+  const paths: Spec['paths'] = {};
+  const seen = new Set<string>();
+
+  for (const [path, item] of Object.entries(spec.paths)) {
+    const kept: Record<string, unknown> = {};
+
+    for (const [method, operation] of Object.entries(item)) {
+      // Path-level keys are not operations and must survive — `parameters`
+      // here holds what every method on the path shares.
+      if (!METHODS.includes(method)) {
+        kept[method] = operation;
+        continue;
+      }
+      const operationId = operation.operationId;
+      if (!operationId || !wanted.has(operationId)) continue;
+      kept[method] = operation;
+      seen.add(operationId);
+    }
+
+    if (!Object.keys(kept).some((key) => METHODS.includes(key))) continue;
+    paths[path] = kept as Spec['paths'][string];
+  }
+
+  // Drop response schemas, before `referenced` so nothing they reach is kept.
+  //
+  // The same two reasons as Google's, in the same order of importance. Nothing
+  // reads them — the connector hands the body back as text. And bunq's response
+  // schemas are where most of the recursion lives, so keeping them would drag
+  // the whole `Payment`/`RequestInquiry` cycle into a document that does not
+  // otherwise need it.
+  for (const item of Object.values(paths)) {
+    for (const [method, operation] of Object.entries(item)) {
+      if (!METHODS.includes(method)) continue;
+      (operation as { responses?: unknown }).responses = {
+        '200': { description: 'Success. The response body is returned verbatim.' },
+      };
+    }
+  }
+
+  let headers = 0;
+  for (const item of Object.values(paths)) {
+    headers += dropProtocolParameters(item as unknown as Record<string, unknown>);
+  }
+
+  const missing = OPERATIONS.filter((operationId) => !seen.has(operationId));
+  if (missing.length > 0) {
+    // Loudly: an upstream rename should fail the refresh rather than quietly
+    // shrinking what this provider can do.
+    throw new Error(`these operations are not in the spec — ${missing.join(', ')}`);
+  }
+
+  const schemas = spec.components?.schemas ?? {};
+
+  const projected = new Set<string>();
+  for (const item of Object.values(paths)) {
+    for (const [method, operation] of Object.entries(item)) {
+      if (!METHODS.includes(method)) continue;
+      const fields = operation.operationId ? UPDATE_BODIES[operation.operationId] : undefined;
+      if (!fields || !operation.operationId) continue;
+
+      projectRequestBody(
+        operation as unknown as Record<string, unknown>,
+        operation.operationId,
+        schemas,
+        fields,
+        'The whole of what this call takes. bunq refuses any other field here as superfluous — the rest ' +
+          'of the schema it shares belongs to the call that creates one.',
+      );
+      projected.add(operation.operationId);
+    }
+  }
+
+  // The same refusal as `missing` above, and for a sharper reason: an entry that
+  // matches nothing narrows nothing, and what is left is the wide body this
+  // exists to remove — printed as a success.
+  const unprojected = Object.keys(UPDATE_BODIES).filter((id) => !projected.has(id));
+  if (unprojected.length > 0) {
+    throw new Error(`UPDATE_BODIES names operations the spec does not have — ${unprojected.join(', ')}`);
+  }
+
+  const keep = referenced(paths, schemas);
+  const trimmedSchemas = Object.fromEntries(
+    Object.entries(schemas).filter(([name]) => keep.has(name)),
+  );
+  const cuts = cutCycles(trimmedSchemas);
+  const readOnly = dropReadOnly(trimmedSchemas);
+
+  const trimmed: Spec = {
+    openapi: spec.openapi,
+    info: {
+      ...spec.info,
+      // Replaced, not carried. bunq's own `description` is 73 KB of product
+      // tour — 78% of what this file would otherwise weigh — and it is
+      // documentation of the bank rather than of the API. It also carries
+      // example addresses at bunq's own registrable domain, which
+      // `architecture.test.ts` refuses anywhere a reader of this repository can
+      // see. Both problems are the same field, and dropping it is better than
+      // exempting the file: an exemption would also cover whatever the next
+      // refresh brings in.
+      description:
+        'Trimmed from the published bunq specification. See x-vendored-from for the original, and https://doc.bunq.com for the reference.',
+      'x-vendored-from': SOURCE,
+      'x-vendored-note':
+        'Trimmed by src/providers/bunq/specs/vendor.ts. Committed deliberately: a spec decides which paths are called with the operator credential, and this one can move money.',
+    },
+    // Rewritten rather than carried over. bunq's document declares both the
+    // sandbox and production servers with a templated `{basePath}`, and the
+    // manifest names one concrete `base_url` — leaving two in the spec invites
+    // a reader to think the choice is made here. It is made by the strategy.
+    servers: [{ url: 'https://api.bunq.com/v1' }],
+    paths,
+    // Schemas only. Carrying `...spec.components` kept bunq's `parameters`,
+    // `responses` and `headers` — none of them referenced by a surviving path,
+    // and among them the definition of `X-Bunq-Client-Authentication`, which
+    // `dropProtocolParameters` above exists to make unreachable. A committed
+    // spec is committed so it can be read; dead definitions of the session
+    // header are the opposite of that.
+    components: { schemas: trimmedSchemas },
+  };
+
+  const directory = import.meta.dir;
+  await mkdir(directory, { recursive: true });
+  await writeFile(join(directory, OUT), `${JSON.stringify(trimmed, null, 2)}\n`);
+
+  const size = Math.round(JSON.stringify(trimmed).length / 1024);
+  console.log(
+    `  bunq   ${String(Object.keys(paths).length).padStart(2)} paths, ` +
+      `${seen.size} operations, ${Object.keys(trimmedSchemas).length} schemas, ` +
+      `${cuts} cycle${cuts === 1 ? '' : 's'} cut, ${headers} protocol params dropped, ` +
+      `${readOnly} read-only fields dropped, ${projected.size} update ` +
+      `bod${projected.size === 1 ? 'y' : 'ies'} projected, ${size}KB`,
+  );
+
+  await report(trimmed);
+}
+
+/**
+ * What the budget is actually about: the **generated** input schema.
+ *
+ * Orders of magnitude away from the spec size on the line above, because
+ * `$ref`s are inlined. Printed so a refresh that adds an operation shows what
+ * it costs, rather than leaving `cli/tools.test.ts` to say so afterwards.
+ */
+async function report(trimmed: Spec): Promise<void> {
+  try {
+    const generator = await OpenAPIToolGenerator.fromJSON(trimmed);
+    const tools = await generator.generateTools();
+
+    const measured = tools
+      .map((tool: McpOpenAPITool) => ({
+        name: tool.metadata.operationId ?? tool.name,
+        kb: JSON.stringify(tool.inputSchema).length / 1024,
+      }))
+      .sort((a, b) => b.kb - a.kb);
+
+    for (const { name, kb } of measured.slice(0, 4)) {
+      const over = kb > BUDGET_KB ? `  ✗ over the ${BUDGET_KB}KB budget` : '';
+      console.log(`         ${name.padEnd(46)} ${kb.toFixed(1).padStart(7)}KB${over}`);
+    }
+
+    const surface = tools.reduce(
+      (total, tool) => total + JSON.stringify({ description: tool.description, inputSchema: tool.inputSchema }).length,
+      0,
+    );
+    console.log(`         ${'whole advertised surface'.padEnd(46)} ${(surface / 1024).toFixed(1).padStart(7)}KB`);
+  } catch (error) {
+    console.log(`         (could not measure generated schemas: ${String(error)})`);
+  }
+}
+
+await vendor();

package/src/providers/bunq/strategy/handshake.ts

@@ -0,0 +1,211 @@
+import { signBody } from './keys.ts';
+
+/**
+ * bunq's three-step API context, which is why this provider needs code at all.
+ *
+ * Most APIs take a key and are done. bunq takes a key and then wants an
+ * *installation* (here is my public key), a *device* (this key may be used, from
+ * these addresses), and a *session* (and now let me in) — three round trips
+ * producing three different tokens, of which only the last one authenticates an
+ * ordinary call. No manifest field describes that, which is the whole argument
+ * for `AuthStrategy` in ADR-008.
+ *
+ * Nothing in this file names an operation. It knows how to open a session and
+ * nothing about what the session is then used for.
+ */
+
+export const PRODUCTION = 'https://api.bunq.com/v1';
+export const SANDBOX = 'https://public-api.sandbox.bunq.com/v1';
+
+/**
+ * Which bunq this connection talks to: whatever its manifest says.
+ *
+ * One provider serves both environments, because they are the same API and the
+ * same tool list — a second provider id would duplicate the manifest, the
+ * vendored spec, and every policy rule written against it. The built-in names
+ * production; a workspace manifest in `providers.d/` naming the sandbox gets
+ * the sandbox, and borrows this strategy through `strategyFor`.
+ *
+ * This used to be a `sandbox: true` option on the strategy, with `authorize`
+ * rewriting the request origin to match. That was a second source of truth for
+ * something `base_url` already states, and the two could disagree — a manifest
+ * pointed at the sandbox but missing the flag (or carrying `sandbox: "true"`,
+ * which is not `true`) would have spent against production while its own
+ * `base_url` said otherwise. Reading the manifest makes the disagreement
+ * impossible rather than documented, and the transport and the handshake now
+ * cannot end up on different hosts because neither chooses.
+ */
+export function hostFor(manifest: { connector: { kind: string } }): string {
+  const connector = manifest.connector as { kind: string; base_url?: string };
+  if (connector.kind !== 'http' || !connector.base_url) {
+    throw new Error('The bunq strategy needs an http connector with a base_url.');
+  }
+
+  return connector.base_url.replace(/\/$/, '');
+}
+
+export interface Installation {
+  /** Authenticates device-server and session-server, and nothing else. */
+  readonly token: string;
+  /** bunq's half, for checking that a reply is bunq's. */
+  readonly serverPublicKey: string;
+}
+
+/**
+ * Everything bunq requires on a request that is not the signature.
+ *
+ * `X-Bunq-Client-Request-Id` must differ per request; bunq uses it to
+ * de-duplicate, so reusing one would make a retried payment silently a no-op —
+ * which is the behaviour you want, but only if the id is genuinely fresh when
+ * the payment is genuinely new.
+ */
+export function baseHeaders(): Record<string, string> {
+  return {
+    // No `content-type`. Every handshake call below adds it because every one
+    // of them posts JSON, but `authorize` applies this set to reads too, and a
+    // GET that carries no body should not claim one.
+    'cache-control': 'no-cache',
+    'user-agent': 'lanes-link/1.0',
+    'x-bunq-language': 'en_US',
+    'x-bunq-region': 'en_US',
+    'x-bunq-geolocation': '0 0 0 0 000',
+    'x-bunq-client-request-id': crypto.randomUUID(),
+  };
+}
+
+/**
+ * bunq answers everything as `{ Response: [ { Key: value }, … ] }`.
+ *
+ * An array of single-key objects rather than one object, so reading a field
+ * means searching for the wrapper that holds it.
+ */
+function pick(payload: unknown, wrapper: string): Record<string, unknown> | undefined {
+  const entries = (payload as { Response?: unknown[] } | null)?.Response;
+  if (!Array.isArray(entries)) return undefined;
+
+  for (const entry of entries) {
+    const found = (entry as Record<string, unknown>)?.[wrapper];
+    if (found && typeof found === 'object') return found as Record<string, unknown>;
+  }
+
+  return undefined;
+}
+
+async function call(
+  url: string,
+  body: unknown,
+  headers: Record<string, string>,
+  fetcher: typeof globalThis.fetch,
+): Promise<unknown> {
+  const payload = JSON.stringify(body);
+  const response = await fetcher(url, {
+    method: 'POST',
+    headers: { ...headers, 'content-type': 'application/json' },
+    body: payload,
+  });
+  const text = await response.text();
+
+  if (!response.ok) {
+    // bunq's errors are readable and specific — a wrong key, an IP that is not
+    // permitted, a session created too soon. Passing the text through is what
+    // makes the difference visible; swallowing it leaves "connect failed".
+    throw new Error(`bunq ${new URL(url).pathname} answered ${response.status}: ${text}`);
+  }
+
+  return JSON.parse(text);
+}
+
+/**
+ * Step one: hand bunq the public key. The only call needing no authentication
+ * and no signature, because bunq has nothing to check one against yet.
+ */
+export async function createInstallation(
+  host: string,
+  publicKey: string,
+  fetcher: typeof globalThis.fetch,
+): Promise<Installation> {
+  const payload = await call(
+    `${host}/installation`,
+    { client_public_key: publicKey },
+    baseHeaders(),
+    fetcher,
+  );
+
+  const token = pick(payload, 'Token')?.['token'];
+  const serverPublicKey = pick(payload, 'ServerPublicKey')?.['server_public_key'];
+
+  if (typeof token !== 'string' || typeof serverPublicKey !== 'string') {
+    throw new Error('bunq /installation returned no token or no server public key.');
+  }
+
+  return { token, serverPublicKey };
+}
+
+/**
+ * Step two: register the key against the addresses it may be used from.
+ *
+ * `permitted_ips` is deliberately not passed. bunq refuses the wildcard `*` over
+ * the API — it can only be set in the app — and any list written here would be
+ * this machine's address at connect time, which is wrong the moment the
+ * endpoint is deployed or the operator's ISP renumbers. Omitting it lets bunq
+ * default to the calling address, and the setup doc says plainly that a
+ * deployment needs a key marked wildcard in the app.
+ *
+ * Idempotent in practice: re-registering an existing device answers 200.
+ */
+export async function registerDevice(
+  host: string,
+  installationToken: string,
+  apiKey: string,
+  description: string,
+  privateKey: string,
+  fetcher: typeof globalThis.fetch,
+): Promise<void> {
+  const body = { secret: apiKey, description };
+
+  await call(
+    `${host}/device-server`,
+    body,
+    {
+      ...baseHeaders(),
+      'x-bunq-client-authentication': installationToken,
+      'x-bunq-client-signature': signBody(JSON.stringify(body), privateKey),
+    },
+    fetcher,
+  );
+}
+
+/**
+ * Step three, and the only one that runs again later.
+ *
+ * A session lasts as long as the account's auto-logout setting — a week by
+ * default — and `/session-server` is rate-limited to **one call per thirty
+ * seconds**. That limit is the reason the token is persisted in shared state
+ * rather than held per instance: a deployed endpoint that opened a session per
+ * cold start would spend most of its life being refused.
+ */
+export async function createSession(
+  host: string,
+  installationToken: string,
+  apiKey: string,
+  privateKey: string,
+  fetcher: typeof globalThis.fetch,
+): Promise<string> {
+  const body = { secret: apiKey };
+
+  const payload = await call(
+    `${host}/session-server`,
+    body,
+    {
+      ...baseHeaders(),
+      'x-bunq-client-authentication': installationToken,
+      'x-bunq-client-signature': signBody(JSON.stringify(body), privateKey),
+    },
+    fetcher,
+  );
+
+  const token = pick(payload, 'Token')?.['token'];
+  if (typeof token !== 'string') throw new Error('bunq /session-server returned no token.');
+
+  return token;
+}