@lanes-sh/link 0.3.2 → 0.4.1

package/src/dispatch/dispatch.ts

@@ -6,8 +6,14 @@ import type { RuntimeState } from '#stores/state';
 import type { PolicyDocument } from '#policy';
 import { RateLimiter, evaluate } from '#policy';
 import type { BlobStore } from '#stores/blobs';
-import type { AnyConnector, CapabilityResult, ConnectorContext, Logger } from '#connectivity';
-import { isToolResult } from '#connectivity';
+import type {
+  AnyConnector,
+  AuthStrategyContext,
+  CapabilityResult,
+  ConnectorContext,
+  Logger,
+} from '#connectivity';
+import { isToolResult, strategyContextFrom, strategyFor } from '#connectivity';
 import type { Config } from '#profile';
 import { buildProviderContext, createProviderLogger } from './context.ts';
 import { stageAttachment, type StagedAttachment, type StageRequest } from './staging.ts';
@@ -252,13 +258,38 @@ export class Dispatcher {
         },
       };
 
+      // A provider whose authentication is code rather than a manifest field.
+      // The strategy stands in for the credential resolver completely: it holds
+      // whatever session the vendor issues, signs the outbound request, and
+      // checks the reply. Looked up once, because both halves of the connector
+      // context come from the same one.
+      const strategy =
+        entry.manifest.auth.kind === 'strategy'
+          ? strategyFor(entry.manifest, this.#deps.registry)
+          : undefined;
+
+      // Derived from the provider context — which is handed the closure below,
+      // so it cannot exist yet. Both are only ever *called* after this block
+      // finishes, and memoising keeps one context per invocation rather than
+      // one per outbound request.
+      let strategyContext: AuthStrategyContext | undefined;
+      const forStrategy = (): AuthStrategyContext =>
+        (strategyContext ??= strategyContextFrom({
+          source: providerContext,
+          manifest: entry.manifest,
+          connectionId: declared.id,
+          profile: this.#deps.config.instance.profile,
+        }));
+
       // One closure, handed to both contexts. A provider that authors a
       // capability its transport cannot express still calls the vendor through
       // the same authorizer the transport would have used.
       const authorize = (outbound: Request): Promise<Request> =>
-        this.#deps.authorizeRequest
-          ? this.#deps.authorizeRequest(providerId, declared.id, outbound)
-          : Promise.resolve(outbound);
+        strategy
+          ? strategy.authorize(outbound, forStrategy())
+          : this.#deps.authorizeRequest
+            ? this.#deps.authorizeRequest(providerId, declared.id, outbound)
+            : Promise.resolve(outbound);
 
       const providerContext = buildProviderContext({
         manifest: entry.manifest,
@@ -288,10 +319,18 @@ export class Dispatcher {
         });
       }
 
+      // Only where the strategy asks for it. A vendor that signs its replies
+      // expects them verified, and the transport clones the response so the
+      // check costs the caller nothing.
+      const verifyResponse = strategy?.verify?.bind(strategy);
+
       const connectorContext: ConnectorContext = {
         manifest: entry.manifest,
         provider: providerContext,
         authorize,
+        ...(verifyResponse
+          ? { verify: (response: Response) => verifyResponse(response, forStrategy()) }
+          : {}),
       };
 
       // The connector owns argument validation: a local provider validates

package/src/providers/bunq/hints.ts

@@ -0,0 +1,45 @@
+/**
+ * What bunq's own descriptions leave out, and an agent has to know.
+ *
+ * Appended to the generated description at discovery. Three things earn a line
+ * here: the distinction that decides whether money moves, the shape of an
+ * amount, and the identifier an agent cannot guess.
+ */
+export const BUNQ_HINTS: Record<string, string> = {
+  List_all_User:
+    'Call this first. Every other bunq tool is addressed under a userID, and this is the only thing that reports it.',
+
+  List_all_MonetaryAccount_for_User:
+    'Returns every account: current, savings, joint, and closed ones. Each is wrapped in a type key ' +
+    '(MonetaryAccountBank, MonetaryAccountSavings, …) and the id inside it is the `monetary-accountID` ' +
+    'the payment tools take. Check `status` is ACTIVE before paying from one.',
+
+  CREATE_Payment_for_User_MonetaryAccount:
+    'This executes immediately and is not reversible. The money leaves the account as soon as bunq accepts the call — ' +
+    'there is no confirmation step, in the app or anywhere else. Use draft-payment instead when a human should see it first. ' +
+    'amount is { "value": "10.00", "currency": "EUR" } — a decimal string, not a number, and never cents. ' +
+    'counterparty_alias is { "type": "IBAN", "value": "<iban>", "name": "<account holder>" }, and for IBAN the name must match ' +
+    'the one on the receiving account. type may also be EMAIL or PHONE_NUMBER for another bunq user.',
+
+  CREATE_DraftPayment_for_User_MonetaryAccount:
+    'Prepares a payment without sending it: it waits in the bunq app until a human approves it, which is the checkpoint ' +
+    'a direct payment does not have. Takes `entries`, an array of { amount, counterparty_alias, description } shaped exactly ' +
+    'like a direct payment, plus number_of_required_accepts (1 for a personal account).',
+
+  UPDATE_DraftPayment_for_User_MonetaryAccount:
+    'Changes a draft that is still pending — status ACCEPTED sends it, REJECTED cancels it. ' +
+    'previous_updated_timestamp is required and comes from reading the draft first; it is what stops two ' +
+    'callers acting on the same draft. Those two fields are the entire call — bunq refuses entries and ' +
+    'number_of_required_accepts here as superfluous — so changing what a draft pays means rejecting it and ' +
+    'creating another.',
+
+  CREATE_PaymentBatch_for_User_MonetaryAccount:
+    'Up to 350 payments in one call. Executes immediately, like a direct payment, and is all-or-nothing: bunq rejects ' +
+    'the whole batch if any entry is invalid. `payments` must be an ARRAY of { amount, counterparty_alias, description } ' +
+    'objects, each shaped exactly like a direct payment — bunq\'s specification declares the field as an object rather ' +
+    'than an array, which is wrong, so the schema here cannot tell you that and this line has to.',
+
+  List_all_Payment_for_User_MonetaryAccount:
+    'Newest first, one page at a time. bunq pages with `count`, `older_id` and `newer_id` rather than an offset, ' +
+    'but its specification does not declare them, so this tool returns the most recent page and no more.',
+};

package/src/providers/bunq/index.ts

@@ -0,0 +1,87 @@
+import { defineProvider, defineProviderWithStrategy } from '#connectivity';
+import { BUNQ_HINTS } from './hints.ts';
+import { BUNQ_REDACT } from './redact.ts';
+import { createBunqStrategy } from './strategy/index.ts';
+
+const specPath = (name: string): string => new URL(`./specs/${name}`, import.meta.url).pathname;
+
+/**
+ * bunq — accounts, transaction history, and payments.
+ *
+ * The one provider here whose authentication is code. Everything else about it
+ * is declared like any other manifest, and the eleven operations it can reach
+ * come from a vendored OpenAPI document rather than from anything written by
+ * hand. What earns the exception is the handshake: bunq generates nothing for
+ * you, it wants a keypair you made, an installation, a registered device, and a
+ * session, and then it wants every request body signed. No manifest field
+ * describes that. See ADR-008 and `./strategy/`.
+ *
+ * `base_url` carries the version in the **path**, like Sheets and unlike Drive.
+ * `https://api.bunq.com` alone 404s on every call.
+ *
+ * Sandbox is not a second provider and not a flag either: the strategy reads
+ * its host from `base_url`, so a manifest in `providers.d/` naming
+ * `public-api.sandbox.bunq.com` handshakes and pays there, borrowing this
+ * strategy through `strategyFor`. That is where anything touching this should
+ * be proven before it is pointed at a real account.
+ *
+ * No `identity` block, and that is not an omission. The generic HTTP identity
+ * probe sends `Authorization: Bearer <token>`, which bunq does not accept and
+ * would fail in a way that reads as a bad credential rather than as an
+ * inapplicable probe. `connect` asks what to call the connection instead.
+ */
+const manifest = defineProvider({
+  id: 'bunq',
+  name: 'bunq',
+  description:
+    'Bank accounts, balances, transaction history, and payments — including batches and drafts that wait for approval in the bunq app.',
+  connector: {
+    kind: 'http',
+    base_url: 'https://api.bunq.com/v1',
+    openapi: specPath('bunq.v1.json'),
+  },
+  auth: {
+    kind: 'strategy',
+    strategy: 'bunq',
+    // No `credential_ref`, so it derives per connection — `bunq/<id>`. bunq
+    // issues one API key per account, and a declared ref would mean every
+    // connection sharing one, which is the opposite of true here.
+  },
+  redact: BUNQ_REDACT,
+  hints: BUNQ_HINTS,
+  setup: {
+    summary:
+      'bunq issues an API key from inside the app, not from a web console. The key is bound to the IP addresses ' +
+      'it is used from unless you mark it as a wildcard key — which you must do in the app if this endpoint will ' +
+      'ever run anywhere but this machine.',
+    docs: 'docs/detailed/setup/bunq.md',
+    docs_url: 'https://doc.bunq.com/basics/authentication/api-keys',
+    steps: [
+      'In the bunq app: Profile → Security & Settings → Developers → API keys → Add API key.',
+      'Name it "Lanes Link", so you can revoke this one later without touching your others.',
+      'Set a spending limit on the key while you are there. It is the only bound that does not depend on this software being correct — policy rules and tool lists are ours to get wrong, and a limit at the bank is not.',
+      'If this endpoint will run deployed rather than on this machine, mark the key as a wildcard key in the same screen. bunq refuses to set that over the API, deliberately, so it cannot be done for you.',
+      'Copy the key and paste it below. Nothing is sent anywhere until you do — the handshake that registers this device runs immediately afterwards.',
+      'You will be asked what to call this connection. bunq has no endpoint that reports whose account a key belongs to, so the label is yours to choose.',
+      'To try this without a real account first, use bunq\'s sandbox: https://public-api.sandbox.bunq.com issues a test key and needs no bank account at all. Put a manifest of your own in providers.d/ naming that base_url — see docs/detailed/setup/bunq.md.',
+    ],
+    troubleshooting:
+      'bunq refused the key. The usual causes are a key that was revoked in the app, a request from an address the key ' +
+      'does not permit (mark it as a wildcard key if this runs deployed), or a session that ended because the account\'s ' +
+      'auto-logout elapsed — that last one recovers by itself on the next call. Generate a new key in the app and re-run: ' +
+      'lanes link connect bunq --replace.',
+    prompts: [
+      {
+        key: 'api_key',
+        label: 'bunq API key',
+        secret: true,
+        scope: 'connection' as const,
+      },
+    ],
+  },
+});
+
+export const bunq = defineProviderWithStrategy({
+  manifest,
+  strategy: createBunqStrategy(),
+});

package/src/providers/bunq/redact.ts

@@ -0,0 +1,75 @@
+/**
+ * A payment log that can answer "what moved, and to whom".
+ *
+ * The default is wrong here, and actively so. It withholds every value, which
+ * for mail is the right instinct — the body is the private part — and for a
+ * bank produces an audit log recording that a payment happened without
+ * recording its amount or its recipient. That is not a redaction, it is an
+ * erasure of the only facts anyone would ever go looking for.
+ *
+ * So the judgement runs the other way round from every other provider here: a
+ * payment argument is a *fact about a transaction*, not a piece of the user's
+ * content, and every one of them is kept. There is no equivalent of a message
+ * body in this provider's write surface — the nearest thing is `description`,
+ * which is the reference that appears on the recipient's statement and is
+ * therefore already shared with a third party.
+ *
+ * The reads are listed for the same reason Sheets lists its own: they carry
+ * identifiers and a page size, no query, and nothing worth protecting. Leaving
+ * them out would mean a log that cannot distinguish reading one payment from
+ * enumerating the account.
+ *
+ * Names are the generated argument names, which the OpenAPI generator prefixes
+ * where a body field and a path parameter would otherwise collide.
+ */
+export const BUNQ_REDACT: Record<string, string[]> = {
+  // Reads.
+  List_all_User: [],
+  List_all_MonetaryAccount_for_User: ['userID'],
+  List_all_Payment_for_User_MonetaryAccount: ['userID', 'monetary-accountID'],
+  READ_Payment_for_User_MonetaryAccount: ['userID', 'monetary-accountID', 'itemId'],
+  List_all_DraftPayment_for_User_MonetaryAccount: ['userID', 'monetary-accountID'],
+  READ_DraftPayment_for_User_MonetaryAccount: ['userID', 'monetary-accountID', 'itemId'],
+  List_all_PaymentBatch_for_User_MonetaryAccount: ['userID', 'monetary-accountID'],
+
+  // Writes. Everything, because everything is a fact worth reconstructing: the
+  // account it left, the amount, who received it, and what the reference said.
+  CREATE_Payment_for_User_MonetaryAccount: [
+    'userID',
+    'monetary-accountID',
+    'amount',
+    'counterparty_alias',
+    'description',
+    'merchant_reference',
+    'allow_bunqto',
+  ],
+  CREATE_DraftPayment_for_User_MonetaryAccount: [
+    'userID',
+    'monetary-accountID',
+    'entries',
+    'number_of_required_accepts',
+    'status',
+    'schedule',
+  ],
+  // Five, not seven: `entries` and `number_of_required_accepts` are no longer
+  // arguments at all. This is the one write here whose event cannot name an
+  // amount or a counterparty, because the call does not carry them — it says
+  // which draft was accepted and against which version of it, and that is
+  // everything there is to keep.
+  //
+  // Not everything a reader wants, though, and worth being honest that the gap
+  // is real rather than closed. The entries are on the event that *created* the
+  // draft, and nothing joins the two: an `AuditEvent` records arguments only,
+  // and bunq returns the draft id in the create's response. Reconstructing what
+  // an ACCEPTED draft paid means matching by hand. `context.audit.annotate`,
+  // which `gmail.send_message` uses to record resolved facts, is the shape of a
+  // fix and is a change to dispatch rather than to this list.
+  UPDATE_DraftPayment_for_User_MonetaryAccount: [
+    'userID',
+    'monetary-accountID',
+    'itemId',
+    'status',
+    'previous_updated_timestamp',
+  ],
+  CREATE_PaymentBatch_for_User_MonetaryAccount: ['userID', 'monetary-accountID', 'payments'],
+};