@naulon/wayfarer-mcp 0.2.1 → 0.3.0

package/README.md

@@ -26,10 +26,17 @@ spend) — but mock settlement is not a mock catalog: `discover` / `research` /
 `verify` need a real place to look, so with nothing configured they refuse
 (they never fabricate sources). To actually find and read something, pick one:
 
-- **Turnkey (hosted):** point a client at the hosted endpoint with an agent
-  token — real corpus, no local wallet. See [Hosted endpoint](#hosted-endpoint-no-local-wallet).
-- **Bring your own publisher:** set `RSS_URL`, `PUBLISHER_URL`, or `CATALOG_URL`
-  to a site's feed/catalog, plus `TOLLGATE_URL` to pay. See [Configuration](#configuration).
+- **Buy from the fleet (hosted):** point a client at the hosted endpoint with an
+  agent token and use `naulon_ask` — it buys across the whole naulon fleet
+  directory, real corpus, no local wallet. See [Hosted endpoint](#hosted-endpoint-no-local-wallet).
+- **Single publisher (stdio):** set `RSS_URL`, `PUBLISHER_URL`, or `CATALOG_URL`
+  to that site's feed/catalog, plus `TOLLGATE_URL` to pay. A lone `TOLLGATE_URL`
+  pins **every** payment to one gate — that's single-publisher by design.
+- **Fleet / many publishers (stdio):** to buy across more than one publisher
+  locally, set `WAYFARER_ALLOW_DOMAINS` to the publisher hosts you trust (and
+  point discovery at a fleet directory via `CATALOG_URL`) instead of pinning a
+  single `TOLLGATE_URL` — each discovered publisher is then paid at its own gate,
+  bounded by the allowlist. See [Configuration](#configuration).
 - **Full loop offline:** run the repo's `make demo` (or `make dev`) to drive the
   whole discover → toll → pay → settle loop against a local stub publisher.
 
@@ -132,10 +139,10 @@ command: npx   args: ["-y", "@naulon/wayfarer-mcp"]
 
 ## Hosted endpoint (no local wallet)
 
-naulon-cloud exposes the same brain over **Streamable HTTP** at `/_naulon/mcp`,
-authenticated with an agent token — tolls are signed by naulon's custody-free
-session key, so **no private key ever touches your machine**. This endpoint also
-adds the cloud-only `naulon_ask` tool + its `ask` prompt.
+The hosted naulon service exposes the same brain over **Streamable HTTP** at
+`/_naulon/mcp`, authenticated with an agent token — tolls are signed by naulon's
+custody-free session key, so **no private key ever touches your machine**. This
+endpoint also adds the hosted-only `naulon_ask` tool + its `ask` prompt.
 
 Clients that support remote/HTTP MCP with headers:
 
@@ -175,7 +182,7 @@ Env read by the stdio server (all optional — omit for the offline mock):
 | `BUYER_PRIVATE_KEY` | The wallet the toll is paid from. BYO-key path; a hosted deploy signs through a cloud signer instead. |
 | `TOLLGATE_URL` | The gate every payment resolves against. Payments only ever flow here — a prompt-injected model cannot redirect them. |
 | `WAYFARER_BUDGET_USDC` | The session spend ceiling. The model can never raise it. |
-| `WAYFARER_ALLOW_DOMAINS` / `WAYFARER_DENY_DOMAINS` | Publisher allow/deny lists for `naulon_research`. |
+| `WAYFARER_ALLOW_DOMAINS` / `WAYFARER_DENY_DOMAINS` | Publisher allow/deny lists applied to **every paid tool** (`naulon_quote`, `naulon_pay_and_read`, `naulon_research`) — not just research. A stated `ALLOW_DOMAINS` *replaces* the single-gate identity pin, so one server can buy across many publishers. Blank/malformed reads as **unset** (no restriction); comma-separated hosts to allow. (Internally, a defined-but-empty allowlist denies all — a blank env var can only ever read as unset, never empty.) |
 | `WAYFARER_PER_DOMAIN_CAP` | Max paid reads per publisher per session. |
 | `WAYFARER_KILL_SWITCH` | Hard stop — refuse all spend. |
 

package/dist/server.d.ts

@@ -103,6 +103,17 @@ export interface BuildServerOptions {
     railSigners?: RailSigners;
     /** This session's spend ceiling in USDC (else `WAYFARER_BUDGET_USDC`). */
     budgetUsdc?: number;
+    /**
+     * Spend ALREADY made by this caller before this server instance was built — the
+     * running total `spentSessionUsdc`/`remainingUsdc` start from (else 0). The stdio
+     * funnel leaves it unset (one process = one lifetime, the closure is the whole truth).
+     * The cloud host injects the caller's durable spend-in-window so the counter is
+     * MONOTONIC across reconnects: an MCP session that the edge idle-closed and the client
+     * silently re-`initialize`d no longer resets the budget to zero (the reset that let a
+     * per-call ceiling look like a session cap while the running total quietly restarted).
+     * Server-config, never a tool arg — the model cannot lower its own prior spend.
+     */
+    initialSpentUsdc?: number;
     /** This session's decision policy (else the env-derived policy over DEFAULT_POLICY). */
     policy?: DecisionPolicy;
     /**
@@ -147,6 +158,30 @@ export interface BuildServerOptions {
      * the hosted path the cloud injects its portal wallet URL; the stdio funnel leaves it at the
      * `/buyer/wallet` default. Server-config, never a tool arg. */
     buyerWalletUrl?: string;
+    /**
+     * WP-3a — when set (non-empty), this mount's 4 config-dependent tools (naulon_discover,
+     * naulon_quote, naulon_pay_and_read, naulon_research) are inert BY DESIGN: each short-circuits
+     * BEFORE touching discover()/gateBase()/any tollgate, returning a CONTROLLED refusal (never a
+     * throw, never a fabricated success) whose message is this string verbatim. This is how the
+     * hosted fleet endpoint (WP-3c sets this only on its ask-only mount) stays HONEST about
+     * naulon_ask being the sole fleet-buy path there, instead of surfacing a raw config error for
+     * tools that were never meant to run on that mount. `naulon_status` and `naulon_ask` are never
+     * steered — only these 4. Absent/empty (every stdio/self-host caller, unchanged): a no-op.
+     */
+    hostedInertSteer?: string;
+    /**
+     * Per-payment payee authorization for the spend tools (`naulon_pay_and_read`, `naulon_research`).
+     * Given the fetched `url` and the 402's advertised `payTo`, return false to REFUSE the pay before
+     * any leg is signed (the buyer resolves `payee_refused`, nothing moves). The cloud host binds this to
+     * "is this an owner-authorized payee for this origin?" — resolving the tenant from the url and the
+     * owner-declared payee set from its own resolver — so a compromised/buggy gate cannot redirect a toll
+     * to a wallet no owner declared. Endpoint identity (host==gate) is a separate concern (`authorizeOrigin`);
+     * this owns payee identity. Absent (every stdio/self-host caller) ⇒ no payee check, unchanged.
+     */
+    authorizePayee?: (input: {
+        url: string;
+        payTo: string;
+    }) => boolean | Promise<boolean>;
 }
 /**
  * Build a fresh, unconnected MCP server with the tool surface registered. The

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA2BpE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAgB,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIrI,eAAO,MAAM,WAAW,wBAAwB,CAAC;AACjD;iDACiD;AACjD,eAAO,MAAM,cAAc,UAAU,CAAC;AAgGtC;;;;;;;;GAQG;AACH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,gIAAgI;IAChI,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAC7C,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC;IACpC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAChD;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;mEAI+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,SAAS,CAwyBpE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8BpE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAgB,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIrI,eAAO,MAAM,WAAW,wBAAwB,CAAC;AACjD;iDACiD;AACjD,eAAO,MAAM,cAAc,UAAU,CAAC;AA0HtC;;;;;;;;GAQG;AACH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,gIAAgI;IAChI,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAC7C,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC;IACpC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wFAAwF;IACxF,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAChD;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;mEAI+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,SAAS,CA8lCpE"}