@paybond/kit 0.6.1 → 0.7.1

package/README.md

@@ -1,6 +1,6 @@
 # `@paybond/kit`
 
-Paybond Kit for TypeScript is the npm package for tenant-bound Paybond integrations. It opens gateway-authenticated Harbor sessions, verifies capability tokens, signs intent and evidence payloads, funds x402 / USDC-on-Base intents, and reads tenant-scoped Signal, fraud, ledger, protocol, and A2A data.
+Paybond Kit for TypeScript is the npm package for tenant-bound Paybond integrations. It opens hosted Gateway sessions, verifies capability tokens, signs intent and evidence payloads, uses Stripe Connect or x402 / USDC-on-Base settlement rails, and reads tenant-scoped Signal, fraud, ledger, protocol, and A2A data.
 
 ## Install
 
@@ -17,29 +17,18 @@ npm install @paybond/kit
 ## Requirements
 
 - Node.js 22+
-- A `paybond_sk_...` service-account API key
-- Reachable Gateway and Harbor base URLs
-- For capability verification: a funded intent id and a capability token minted for that intent
+- A `paybond_sk_sandbox_...` or `paybond_sk_live_...` service-account API key
 - For intent creation or evidence submission: 32-byte Ed25519 signing seeds owned by your application
 
 Minimal environment for the quick start:
 
 ```bash
-export PAYBOND_GATEWAY_URL="https://gateway.example.com"
-export PAYBOND_HARBOR_URL="https://harbor.example.com"
-export PAYBOND_API_KEY="paybond_sk_..."
-```
-
-Optional, if you want the quick start to verify a capability:
-
-```bash
-export PAYBOND_INTENT_ID="00000000-0000-0000-0000-000000000000"
-export PAYBOND_CAPABILITY="base64-biscuit-token"
+export PAYBOND_API_KEY="paybond_sk_sandbox_..."
 ```
 
 ## Tenant isolation
 
-Every session is bound to the tenant realm echoed by gateway-authenticated service-account introspection and Harbor access exchange flows.
+Every session is bound to the tenant realm echoed by gateway-authenticated service-account introspection.
 
 - Do not pass tenant ids by hand for normal SDK usage.
 - Construct one `Paybond` session per tenant/service account.
@@ -59,29 +48,12 @@ function requiredEnv(name: string): string {
 }
 
 const paybond = await Paybond.open({
-  gatewayBaseUrl: requiredEnv("PAYBOND_GATEWAY_URL"),
   apiKey: requiredEnv("PAYBOND_API_KEY"),
-  harborBaseUrl: requiredEnv("PAYBOND_HARBOR_URL"),
+  expectedEnvironment: "sandbox",
 });
 
 try {
   console.log("tenant realm:", paybond.harbor.tenantId);
-
-  const intentId = process.env.PAYBOND_INTENT_ID;
-  const capability = process.env.PAYBOND_CAPABILITY;
-  if (intentId && capability) {
-    const verified = await paybond.harbor.verifyCapability({
-      intentId,
-      token: capability,
-      operation: "payments.capture",
-      requestedSpendCents: 18_700,
-    });
-
-    if (!verified.allow) {
-      throw new Error(`verify denied: ${verified.code ?? "deny"} ${verified.message ?? ""}`);
-    }
-    console.log("capability verified:", verified.auditId);
-  }
 } finally {
   await paybond.aclose();
 }
@@ -91,7 +63,7 @@ try {
 
 Core SDK:
 
-- `Paybond.open(...)` for gateway-authenticated, tenant-derived Harbor sessions
+- `Paybond.open(...)` for API-key-only, tenant-derived hosted sessions
 - `HarborClient` for capability verification, intent creation, x402 funding, evidence submission, and ledger reads
 - `paybond.signal` and `paybond.fraud` on `Paybond` sessions opened from one service-account API key
 - `PaybondIntents` helpers for principal-signed intent creation, x402 funding, and payee-signed evidence submission

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
- * Paybond Kit — TypeScript Harbor client with tenant binding, retries, optional upstream JWT,
- * and gateway service-account token exchange (`POST /v1/auth/harbor-access`).
+ * Paybond Kit — TypeScript Gateway client with tenant binding, retries, capability verification,
+ * and signed intent/evidence helpers.
  */
 import { type BuildSignedCreateIntentParams, type SettlementRail } from "./principal-intent.js";
 import { type SignPayeeEvidenceParams } from "./payee-evidence.js";
@@ -56,7 +56,8 @@ export type FundIntentResult = {
     capabilityToken?: string;
     funding?: IntentFundingResult;
 };
-/** Async supplier for short-lived Harbor JWTs minted by the Paybond gateway. */
+export declare const DEFAULT_PAYBOND_GATEWAY_BASE_URL = "https://api.paybond.ai";
+/** Async supplier for upstream Harbor bearer tokens on low-level direct clients. */
 export type HarborBearerSupplier = () => Promise<string | null | undefined>;
 /**
  * Structured HTTP failure from Harbor with operator-facing diagnostics.
@@ -72,7 +73,7 @@ export declare class HarborHttpError extends Error {
     });
 }
 /**
- * Gateway rejected the service-account exchange or returned an unusable harbor-access payload.
+ * Gateway rejected service-account credentials or returned an unusable tenant-principal payload.
  */
 export declare class GatewayAuthError extends Error {
     readonly statusCode: number | undefined;
@@ -642,72 +643,23 @@ export declare class ProtocolHttpError extends Error {
         errorMessage?: string;
     });
 }
-/**
- * Exchanges a `paybond_sk_` API key for short-lived Harbor JWTs and caches tenant realm from the
- * gateway response (no separate tenant env var for the default path).
- */
-export declare class GatewayHarborTokenProvider {
-    private readonly gatewayBase;
-    private readonly apiKey;
-    private readonly path;
-    private readonly skewMs;
-    private readonly clock;
-    private token;
-    private tenantIdValue;
-    private notAfterMonotonic;
-    private refreshTail;
-    constructor(init: {
-        gatewayBaseUrl: string;
-        apiKey: string;
-        harborAccessPath?: string;
-        clockSkewSeconds?: number;
-        /** Injectable monotonic clock (milliseconds) for tests. */
-        clock?: () => number;
-    });
-    get tenantId(): string | null;
-    /**
-     * First exchange; returns tenant realm echoed by the gateway.
-     */
-    ensureInitial(): Promise<string>;
-    /** Return a valid Harbor JWT, refreshing when near expiry. */
-    bearer(): Promise<string>;
-    /** Force rotation (credential rotation drills). */
-    forceRotate(): Promise<void>;
-    private refresh;
-    private refreshInner;
-}
+export type PaybondEnvironment = "live" | "sandbox";
 /**
  * Tenant-scoped Harbor binding for one funded intent and one Biscuit capability token.
  */
 export declare class PaybondCapabilityBinding {
-    readonly harbor: HarborClient;
+    readonly harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability">;
     readonly intentId: string;
     readonly capabilityToken: string;
-    constructor(harbor: HarborClient, intentId: string, capabilityToken: string);
+    constructor(harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability">, intentId: string, capabilityToken: string);
 }
-export type ServiceAccountHarborSessionInit = {
-    gatewayBaseUrl: string;
+export type PaybondOpenOptions = {
     apiKey: string;
-    harborBaseUrl: string;
-    harborAccessPath?: string;
-    clockSkewSeconds?: number;
+    gatewayBaseUrl?: string;
+    principalPath?: string;
+    expectedEnvironment?: PaybondEnvironment;
     maxRetries?: number;
 };
-/**
- * Harbor client plus gateway token lifecycle for one service account.
- */
-export declare class ServiceAccountHarborSession {
-    readonly harbor: HarborClient;
-    private readonly tokens;
-    private constructor();
-    /**
-     * Build a tenant-bound {@link HarborClient} using gateway-derived tenant id and JWT supplier.
-     */
-    static open(init: ServiceAccountHarborSessionInit): Promise<ServiceAccountHarborSession>;
-    rotateHarborToken(): Promise<void>;
-    /** Reserved for future HTTP client cleanup; safe to call after work completes. */
-    aclose(): Promise<void>;
-}
 type HarborClientOptions = {
     harborBearerSupplier?: HarborBearerSupplier;
     staticHarborBearerToken?: string;
@@ -804,6 +756,43 @@ export declare class HarborClient {
      */
     getLedgerMerkleLatest(): Promise<Record<string, unknown>>;
 }
+type GatewayHarborClientOptions = {
+    staticGatewayBearerToken: string;
+    maxRetries?: number;
+};
+type GatewayHarborMutationOptions = {
+    idempotencyKey?: string;
+    recognitionProof?: AgentRecognitionProofV1 | Record<string, unknown>;
+};
+/**
+ * Gateway-backed Harbor surface for hosted Paybond integrations.
+ *
+ * This client sends the service-account API key to the public Gateway. Gateway derives tenant,
+ * mints upstream Harbor credentials internally, and applies recognition/guardrail checks before
+ * forwarding state-changing Harbor requests.
+ */
+export declare class GatewayHarborClient {
+    private readonly base;
+    readonly tenantId: string;
+    private readonly staticGatewayBearerToken;
+    private readonly maxRetries;
+    constructor(gatewayBaseUrl: string, tenantId: string, options: GatewayHarborClientOptions);
+    private headers;
+    private fetchWithRetries;
+    private postJSON;
+    private mutationHeaders;
+    verifyCapability(input: {
+        intentId: string;
+        token: string;
+        operation: string;
+        requestedSpendCents?: number;
+    }): Promise<VerifyCapabilityResult>;
+    createIntent(body: Record<string, unknown>, options: GatewayHarborMutationOptions): Promise<Record<string, unknown>>;
+    fundIntent(intentId: string, options: GatewayHarborMutationOptions & {
+        paymentSignature?: string;
+    }): Promise<FundIntentResult>;
+    submitEvidence(intentId: string, evidenceBody: Record<string, unknown>, options: GatewayHarborMutationOptions): Promise<SubmitEvidenceResult>;
+}
 type GatewaySignalClientOptions = {
     staticGatewayBearerToken: string;
     maxRetries?: number;
@@ -920,9 +909,10 @@ export declare class GatewayProtocolClient {
     }): Promise<Record<string, unknown>>;
 }
 export type ServiceAccountSignalSessionInit = {
-    gatewayBaseUrl: string;
     apiKey: string;
+    gatewayBaseUrl?: string;
     principalPath?: string;
+    expectedEnvironment?: PaybondEnvironment;
     maxRetries?: number;
 };
 export type ServiceAccountFraudSessionInit = ServiceAccountSignalSessionInit;
@@ -951,18 +941,20 @@ export declare class ServiceAccountFraudSession {
  */
 export type PaybondCreateIntentParams = Omit<BuildSignedCreateIntentParams, "tenantId" | "intentId"> & {
     intentId?: string;
+    recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
 };
 /** Parameters for {@link PaybondIntents.submitEvidence} (tenant is taken from the bound Harbor client). */
 export type PaybondSubmitEvidenceParams = Omit<SignPayeeEvidenceParams, "tenantId" | "artifactsBlake3Hex" | "submittedAtRfc3339"> & {
     artifactsBlake3Hex?: string[];
     submittedAtRfc3339?: string;
+    recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
 };
 /**
  * Ergonomic intent helpers: principal-signed intent create, x402 funding, and payee-signed evidence.
  */
 export declare class PaybondIntents {
     private readonly harbor;
-    constructor(harbor: HarborClient);
+    constructor(harbor: HarborClient | GatewayHarborClient);
     /**
      * Build a principal-signed `POST /intents` body and submit it. `principalSigningSeed` must be
      * 32 bytes. `settlementRail` is signed as the requested rail; destinations stay server-owned.
@@ -975,6 +967,7 @@ export declare class PaybondIntents {
      */
     fund(params: {
         intentId: string;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
         paymentSignature?: string;
         idempotencyKey?: string;
     }): Promise<FundIntentResult>;
@@ -986,21 +979,19 @@ export declare class PaybondIntents {
     }): Promise<SubmitEvidenceResult>;
 }
 /**
- * High-level Kit entrypoint: same session lifecycle as {@link ServiceAccountHarborSession}, plus {@link PaybondIntents}.
+ * High-level Kit entrypoint: tenant-bound Gateway clients plus ergonomic intent helpers.
  */
 export declare class Paybond {
-    readonly harbor: HarborClient;
+    readonly harbor: GatewayHarborClient;
     readonly signal: GatewaySignalClient;
     readonly fraud: GatewayFraudClient;
     readonly a2a: GatewayA2AClient;
     readonly protocol: GatewayProtocolClient;
     readonly intents: PaybondIntents;
-    private readonly session;
     private constructor();
-    /** Open a tenant-bound session via gateway `harbor-access` exchange. */
-    static open(init: ServiceAccountHarborSessionInit): Promise<Paybond>;
-    rotateHarborToken(): Promise<void>;
-    /** Release HTTP resources (Harbor client + gateway token provider). */
+    /** Open a tenant-bound hosted Paybond session from a service-account API key. */
+    static open(init: PaybondOpenOptions): Promise<Paybond>;
+    /** Reserved for future HTTP client cleanup; safe to call after work completes. */
     aclose(): Promise<void>;
 }
 export { normalizeJson, jsonValueDigest } from "./json-digest.js";

package/dist/index.js

@@ -1,9 +1,14 @@
 /**
- * Paybond Kit — TypeScript Harbor client with tenant binding, retries, optional upstream JWT,
- * and gateway service-account token exchange (`POST /v1/auth/harbor-access`).
+ * Paybond Kit — TypeScript Gateway client with tenant binding, retries, capability verification,
+ * and signed intent/evidence helpers.
  */
 import { buildSignedCreateIntentBody, } from "./principal-intent.js";
 import { signPayeeEvidenceBinding } from "./payee-evidence.js";
+export const DEFAULT_PAYBOND_GATEWAY_BASE_URL = "https://api.paybond.ai";
+function defaultGatewayBaseUrl(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : DEFAULT_PAYBOND_GATEWAY_BASE_URL;
+}
 /**
  * Structured HTTP failure from Harbor with operator-facing diagnostics.
  */
@@ -20,7 +25,7 @@ export class HarborHttpError extends Error {
     }
 }
 /**
- * Gateway rejected the service-account exchange or returned an unusable harbor-access payload.
+ * Gateway rejected service-account credentials or returned an unusable tenant-principal payload.
  */
 export class GatewayAuthError extends Error {
     statusCode;
@@ -117,103 +122,26 @@ function parseRetryAfterSeconds(v) {
         return null;
     return Math.min(n, 30);
 }
-const DEFAULT_HARBOR_ACCESS_PATH = "/v1/auth/harbor-access";
-/**
- * Exchanges a `paybond_sk_` API key for short-lived Harbor JWTs and caches tenant realm from the
- * gateway response (no separate tenant env var for the default path).
- */
-export class GatewayHarborTokenProvider {
-    gatewayBase;
-    apiKey;
-    path;
-    skewMs;
-    clock;
-    token = null;
-    tenantIdValue = null;
-    notAfterMonotonic = 0;
-    refreshTail = Promise.resolve();
-    constructor(init) {
-        this.gatewayBase = normalizeBase(init.gatewayBaseUrl);
-        this.apiKey = init.apiKey.trim();
-        const rawPath = (init.harborAccessPath ?? DEFAULT_HARBOR_ACCESS_PATH).trim();
-        this.path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
-        this.skewMs = Math.max(0, (init.clockSkewSeconds ?? 90) * 1000);
-        this.clock = init.clock ?? (() => performance.now());
-    }
-    get tenantId() {
-        return this.tenantIdValue;
-    }
-    /**
-     * First exchange; returns tenant realm echoed by the gateway.
-     */
-    async ensureInitial() {
-        await this.refresh(true);
-        if (!this.tenantIdValue) {
-            throw new GatewayAuthError("harbor-access response missing tenant_id; upgrade gateway (PAYBOND-V1-008)");
-        }
-        return this.tenantIdValue;
-    }
-    /** Return a valid Harbor JWT, refreshing when near expiry. */
-    async bearer() {
-        await this.refresh(false);
-        if (!this.token) {
-            throw new GatewayAuthError("harbor-access did not return access_token");
-        }
-        return this.token;
-    }
-    /** Force rotation (credential rotation drills). */
-    async forceRotate() {
-        await this.refresh(true);
-    }
-    async refresh(force) {
-        const job = this.refreshTail.then(() => this.refreshInner(force));
-        this.refreshTail = job.then(() => undefined, () => undefined);
-        await job;
+function normalizeExpectedEnvironment(value) {
+    if (value === undefined)
+        return null;
+    const env = String(value).trim();
+    if (env === "live" || env === "sandbox") {
+        return env;
     }
-    async refreshInner(force) {
-        const now = this.clock();
-        if (!force && this.token && now < this.notAfterMonotonic) {
-            return;
-        }
-        const url = `${this.gatewayBase}${this.path}`;
-        const res = await fetch(url, {
-            method: "POST",
-            headers: {
-                authorization: `Bearer ${this.apiKey}`,
-                accept: "application/json",
-            },
+    throw new GatewayAuthError(`expectedEnvironment must be "live" or "sandbox", got ${JSON.stringify(value)}`);
+}
+function assertExpectedEnvironment(source, actualRaw, expected, bodyText) {
+    if (!expected)
+        return;
+    const actual = typeof actualRaw === "string" ? actualRaw.trim() : "";
+    if (!actual) {
+        throw new GatewayAuthError(`${source} response missing environment`, { bodyText });
+    }
+    if (actual !== expected) {
+        throw new GatewayAuthError(`${source} environment mismatch: expected=${expected} gateway=${actual}`, {
+            bodyText,
         });
-        const text = await res.text();
-        if (!res.ok) {
-            throw new GatewayAuthError(`harbor-access HTTP ${res.status}`, {
-                statusCode: res.status,
-                bodyText: text,
-            });
-        }
-        let body;
-        try {
-            body = JSON.parse(text);
-        }
-        catch {
-            throw new GatewayAuthError("harbor-access response was not JSON", { bodyText: text });
-        }
-        const access = String(body.access_token ?? "").trim();
-        if (!access) {
-            throw new GatewayAuthError("harbor-access JSON missing access_token", { bodyText: text });
-        }
-        const expIn = Number(body.expires_in ?? 0);
-        if (!Number.isFinite(expIn) || expIn <= 0) {
-            throw new GatewayAuthError("harbor-access JSON missing expires_in", { bodyText: text });
-        }
-        const tidRaw = body.tenant_id;
-        if (typeof tidRaw === "string" && tidRaw.trim()) {
-            this.tenantIdValue = tidRaw.trim();
-        }
-        if (!this.tenantIdValue) {
-            throw new GatewayAuthError("harbor-access response missing tenant_id; upgrade gateway (PAYBOND-V1-008)", { bodyText: text });
-        }
-        this.token = access;
-        this.notAfterMonotonic = now + Math.max(1000, expIn * 1000 - this.skewMs);
     }
 }
 /**
@@ -229,41 +157,6 @@ export class PaybondCapabilityBinding {
         this.capabilityToken = capabilityToken;
     }
 }
-/**
- * Harbor client plus gateway token lifecycle for one service account.
- */
-export class ServiceAccountHarborSession {
-    harbor;
-    tokens;
-    constructor(harbor, tokens) {
-        this.harbor = harbor;
-        this.tokens = tokens;
-    }
-    /**
-     * Build a tenant-bound {@link HarborClient} using gateway-derived tenant id and JWT supplier.
-     */
-    static async open(init) {
-        const tokens = new GatewayHarborTokenProvider({
-            gatewayBaseUrl: init.gatewayBaseUrl,
-            apiKey: init.apiKey,
-            harborAccessPath: init.harborAccessPath,
-            clockSkewSeconds: init.clockSkewSeconds,
-        });
-        const tenant = await tokens.ensureInitial();
-        const harbor = new HarborClient(init.harborBaseUrl, tenant, {
-            harborBearerSupplier: () => tokens.bearer(),
-            maxRetries: init.maxRetries ?? 3,
-        });
-        return new ServiceAccountHarborSession(harbor, tokens);
-    }
-    async rotateHarborToken() {
-        await this.tokens.forceRotate();
-    }
-    /** Reserved for future HTTP client cleanup; safe to call after work completes. */
-    async aclose() {
-        await Promise.resolve();
-    }
-}
 /**
  * HTTP client for Harbor: capability verify, intents, evidence, and tenant-scoped ledger reads
  * (`GET /ledger/v1/*`, PAYBOND-007).
@@ -657,6 +550,152 @@ export class HarborClient {
         return body;
     }
 }
+/**
+ * Gateway-backed Harbor surface for hosted Paybond integrations.
+ *
+ * This client sends the service-account API key to the public Gateway. Gateway derives tenant,
+ * mints upstream Harbor credentials internally, and applies recognition/guardrail checks before
+ * forwarding state-changing Harbor requests.
+ */
+export class GatewayHarborClient {
+    base;
+    tenantId;
+    staticGatewayBearerToken;
+    maxRetries;
+    constructor(gatewayBaseUrl, tenantId, options) {
+        this.base = `${normalizeBase(gatewayBaseUrl)}/`;
+        this.tenantId = tenantId.trim();
+        this.staticGatewayBearerToken = options.staticGatewayBearerToken.trim();
+        this.maxRetries = Math.max(1, options.maxRetries ?? 3);
+    }
+    headers(extra) {
+        const headers = new Headers(extra);
+        headers.set("accept", "application/json");
+        headers.set("x-tenant-id", this.tenantId);
+        headers.set("authorization", `Bearer ${this.staticGatewayBearerToken}`);
+        return headers;
+    }
+    async fetchWithRetries(url, init) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, init);
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt + 1 >= this.maxRetries)
+                    throw e;
+                await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+                continue;
+            }
+            if ([429, 500, 502, 503, 504].includes(res.status) && attempt + 1 < this.maxRetries) {
+                const raSec = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                const delayMs = raSec != null ? raSec * 1000 : backoffMs(attempt);
+                await new Promise((r) => setTimeout(r, delayMs));
+                continue;
+            }
+            return res;
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    async postJSON(path, payload, extraHeaders) {
+        const url = `${this.base}${path.replace(/^\/+/, "")}`;
+        const res = await this.fetchWithRetries(url, {
+            method: "POST",
+            headers: this.headers({
+                "content-type": "application/json",
+                ...(extraHeaders ?? {}),
+            }),
+            body: JSON.stringify(payload),
+        });
+        const text = await res.text();
+        return { res, text, url };
+    }
+    mutationHeaders(operation, options, headers) {
+        const proof = options?.recognitionProof;
+        if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
+            throw new Error(`${operation} requires recognitionProof`);
+        }
+        return gatewayMutationHeaders(proof, {
+            ...(headers ?? {}),
+            ...(options?.idempotencyKey?.trim() ? { "idempotency-key": options.idempotencyKey.trim() } : {}),
+        });
+    }
+    async verifyCapability(input) {
+        const payload = {
+            intent_id: input.intentId,
+            token: input.token,
+            operation: input.operation,
+            requested_spend_cents: input.requestedSpendCents ?? 0,
+        };
+        const { res, text, url } = await this.postJSON("/verify", payload);
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway verify HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = JSON.parse(text);
+        if (body.tenant !== this.tenantId) {
+            throw new Error(`verify tenant mismatch: client=${this.tenantId} gateway=${body.tenant}`);
+        }
+        if (body.intent_id !== input.intentId) {
+            throw new Error(`verify intent mismatch: requested=${input.intentId} gateway=${body.intent_id}`);
+        }
+        return {
+            allow: body.allow,
+            auditId: body.audit_id,
+            tenant: body.tenant,
+            intentId: body.intent_id,
+            code: body.code,
+            message: body.message,
+        };
+    }
+    async createIntent(body, options) {
+        const { res, text, url } = await this.postJSON("/harbor/intents", body, this.mutationHeaders("createIntent", options));
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway Harbor create intent HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return JSON.parse(text);
+    }
+    async fundIntent(intentId, options) {
+        const { res, text, url } = await this.postJSON(`/harbor/intents/${encodeURIComponent(intentId)}/fund`, {}, this.mutationHeaders("fundIntent", options, {
+            ...(options.paymentSignature?.trim() ? { "payment-signature": options.paymentSignature.trim() } : {}),
+        }));
+        if (![200, 202, 402].includes(res.status)) {
+            throw new HarborHttpError(`Gateway Harbor fund intent HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return parseFundIntentResponse(assertJSONObject(JSON.parse(text)), {
+            tenantId: this.tenantId,
+            intentId,
+            statusCode: res.status,
+            paymentRequired: res.headers.get("payment-required") ?? undefined,
+            paymentResponse: res.headers.get("payment-response") ?? undefined,
+            source: "gateway",
+        });
+    }
+    async submitEvidence(intentId, evidenceBody, options) {
+        const { res, text, url } = await this.postJSON(`/harbor/intents/${encodeURIComponent(intentId)}/evidence`, evidenceBody, this.mutationHeaders("submitEvidence", options));
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway Harbor evidence HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        return parseSubmitEvidenceResponse(JSON.parse(text));
+    }
+}
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const SETTLEMENT_RAIL_VALUES = new Set(["stripe_connect", "x402_usdc_base"]);
 const FRAUD_REVIEW_EVENT_TYPES = new Set([
@@ -687,6 +726,53 @@ function readStringArrayValue(value, field) {
     }
     return [...value];
 }
+function parseFundIntentResponse(body, init) {
+    const tenant = String(body.tenant ?? "");
+    if (tenant !== init.tenantId) {
+        throw new Error(`fund tenant mismatch: client=${init.tenantId} ${init.source}=${tenant}`);
+    }
+    const echoedIntentId = String(body.intent_id ?? "");
+    if (echoedIntentId !== init.intentId) {
+        throw new Error(`fund intent mismatch: requested=${init.intentId} ${init.source}=${echoedIntentId}`);
+    }
+    if (typeof body.state !== "string" || !body.state.trim()) {
+        throw new Error("fund response missing state");
+    }
+    if (typeof body.currency !== "string" || !body.currency.trim()) {
+        throw new Error("fund response missing currency");
+    }
+    const amountCents = Number(body.amount_cents);
+    if (!Number.isFinite(amountCents)) {
+        throw new Error("fund response missing amount_cents");
+    }
+    return {
+        statusCode: init.statusCode,
+        paymentRequired: init.paymentRequired,
+        paymentResponse: init.paymentResponse,
+        intentId: echoedIntentId,
+        tenant,
+        state: body.state,
+        settlementRail: readSettlementRailValue(body.settlement_rail, "fund settlement_rail"),
+        currency: body.currency,
+        amountCents,
+        funded: Boolean(body.funded),
+        capabilityToken: typeof body.capability_token === "string" && body.capability_token.trim()
+            ? body.capability_token
+            : undefined,
+        funding: body.funding === undefined || body.funding === null
+            ? undefined
+            : parseIntentFundingResult(body.funding),
+    };
+}
+function parseSubmitEvidenceResponse(value) {
+    const body = assertJSONObject(value);
+    return {
+        intentId: String(body.intent_id ?? ""),
+        tenant: String(body.tenant ?? ""),
+        state: String(body.state ?? ""),
+        predicatePassed: typeof body.predicate_passed === "boolean" ? body.predicate_passed : undefined,
+    };
+}
 function parseIntentFundingResult(value) {
     const body = assertJSONObject(value);
     const onchainRaw = body.onchain_transaction_hashes;
@@ -1441,10 +1527,11 @@ function gatewayMutationHeaders(recognitionProof, headers) {
 function encodeRecognitionProofHeader(proof) {
     return Buffer.from(JSON.stringify(proof), "utf8").toString("base64url");
 }
-async function resolveGatewayTenantId(gatewayBaseUrl, apiKey, principalPath, maxRetries) {
+async function resolveGatewayTenantId(gatewayBaseUrl, apiKey, principalPath, maxRetries, expectedEnvironment) {
     const base = normalizeBase(gatewayBaseUrl);
     const path = principalPath.startsWith("/") ? principalPath : `/${principalPath}`;
     const url = `${base}${path}`;
+    const expected = normalizeExpectedEnvironment(expectedEnvironment);
     let lastErr;
     for (let attempt = 0; attempt < maxRetries; attempt++) {
         let res;
@@ -1485,6 +1572,7 @@ async function resolveGatewayTenantId(gatewayBaseUrl, apiKey, principalPath, max
                 bodyText: text,
             });
         }
+        assertExpectedEnvironment("gateway principal", body.environment, expected, text);
         return tenant;
     }
     throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
@@ -1498,8 +1586,9 @@ export class ServiceAccountSignalSession {
         this.signal = signal;
     }
     static async open(init) {
-        const tenantId = await resolveGatewayTenantId(init.gatewayBaseUrl, init.apiKey, init.principalPath ?? DEFAULT_PRINCIPAL_PATH, Math.max(1, init.maxRetries ?? 3));
-        return new ServiceAccountSignalSession(new GatewaySignalClient(init.gatewayBaseUrl, tenantId, {
+        const gatewayBaseUrl = defaultGatewayBaseUrl(init.gatewayBaseUrl);
+        const tenantId = await resolveGatewayTenantId(gatewayBaseUrl, init.apiKey, init.principalPath ?? DEFAULT_PRINCIPAL_PATH, Math.max(1, init.maxRetries ?? 3), init.expectedEnvironment);
+        return new ServiceAccountSignalSession(new GatewaySignalClient(gatewayBaseUrl, tenantId, {
             staticGatewayBearerToken: init.apiKey,
             maxRetries: init.maxRetries ?? 3,
         }));
@@ -1517,8 +1606,9 @@ export class ServiceAccountFraudSession {
         this.fraud = fraud;
     }
     static async open(init) {
-        const tenantId = await resolveGatewayTenantId(init.gatewayBaseUrl, init.apiKey, init.principalPath ?? DEFAULT_PRINCIPAL_PATH, Math.max(1, init.maxRetries ?? 3));
-        return new ServiceAccountFraudSession(new GatewayFraudClient(init.gatewayBaseUrl, tenantId, {
+        const gatewayBaseUrl = defaultGatewayBaseUrl(init.gatewayBaseUrl);
+        const tenantId = await resolveGatewayTenantId(gatewayBaseUrl, init.apiKey, init.principalPath ?? DEFAULT_PRINCIPAL_PATH, Math.max(1, init.maxRetries ?? 3), init.expectedEnvironment);
+        return new ServiceAccountFraudSession(new GatewayFraudClient(gatewayBaseUrl, tenantId, {
             staticGatewayBearerToken: init.apiKey,
             maxRetries: init.maxRetries ?? 3,
         }));
@@ -1543,14 +1633,14 @@ export class PaybondIntents {
      * 32 bytes. `settlementRail` is signed as the requested rail; destinations stay server-owned.
      */
     async create(params) {
-        const { idempotencyKey, intentId: maybeIntentId, ...fields } = params;
+        const { idempotencyKey, intentId: maybeIntentId, recognitionProof, ...fields } = params;
         const intentId = maybeIntentId ?? globalThis.crypto.randomUUID();
         const body = buildSignedCreateIntentBody({
             tenantId: this.harbor.tenantId,
             intentId,
             ...fields,
         });
-        return this.harbor.createIntent(body, { idempotencyKey });
+        return this.harbor.createIntent(body, { idempotencyKey, recognitionProof });
     }
     /**
      * Advance Harbor `/intents/{id}/fund` for x402 / USDC-on-Base intents.
@@ -1559,24 +1649,25 @@ export class PaybondIntents {
         return this.harbor.fundIntent(params.intentId, {
             paymentSignature: params.paymentSignature,
             idempotencyKey: params.idempotencyKey,
+            recognitionProof: params.recognitionProof,
         });
     }
     /**
      * Sign payee evidence and POST it. `payeeSigningSeed` must be 32 bytes.
      */
     async submitEvidence(params) {
-        const { idempotencyKey, artifactsBlake3Hex = [], submittedAtRfc3339 = nowRfc3339Seconds(), ...rest } = params;
+        const { idempotencyKey, artifactsBlake3Hex = [], submittedAtRfc3339 = nowRfc3339Seconds(), recognitionProof, ...rest } = params;
         const wire = signPayeeEvidenceBinding({
             tenantId: this.harbor.tenantId,
             artifactsBlake3Hex,
             submittedAtRfc3339,
             ...rest,
         });
-        return this.harbor.submitEvidence(rest.intentId, wire, { idempotencyKey });
+        return this.harbor.submitEvidence(rest.intentId, wire, { idempotencyKey, recognitionProof });
     }
 }
 /**
- * High-level Kit entrypoint: same session lifecycle as {@link ServiceAccountHarborSession}, plus {@link PaybondIntents}.
+ * High-level Kit entrypoint: tenant-bound Gateway clients plus ergonomic intent helpers.
  */
 export class Paybond {
     harbor;
@@ -1585,43 +1676,44 @@ export class Paybond {
     a2a;
     protocol;
     intents;
-    session;
-    constructor(session, signal, fraud, a2a, protocol) {
-        this.session = session;
-        this.harbor = session.harbor;
+    constructor(harbor, signal, fraud, a2a, protocol) {
+        this.harbor = harbor;
         this.signal = signal;
         this.fraud = fraud;
         this.a2a = a2a;
         this.protocol = protocol;
-        this.intents = new PaybondIntents(session.harbor);
+        this.intents = new PaybondIntents(harbor);
     }
-    /** Open a tenant-bound session via gateway `harbor-access` exchange. */
+    /** Open a tenant-bound hosted Paybond session from a service-account API key. */
     static async open(init) {
-        const session = await ServiceAccountHarborSession.open(init);
-        const signal = new GatewaySignalClient(init.gatewayBaseUrl, session.harbor.tenantId, {
+        const gatewayBaseUrl = defaultGatewayBaseUrl(init.gatewayBaseUrl);
+        const maxRetries = Math.max(1, init.maxRetries ?? 3);
+        const tenantId = await resolveGatewayTenantId(gatewayBaseUrl, init.apiKey, init.principalPath ?? DEFAULT_PRINCIPAL_PATH, maxRetries, init.expectedEnvironment);
+        const harbor = new GatewayHarborClient(gatewayBaseUrl, tenantId, {
             staticGatewayBearerToken: init.apiKey,
-            maxRetries: init.maxRetries ?? 3,
+            maxRetries,
         });
-        const fraud = new GatewayFraudClient(init.gatewayBaseUrl, session.harbor.tenantId, {
+        const signal = new GatewaySignalClient(gatewayBaseUrl, tenantId, {
             staticGatewayBearerToken: init.apiKey,
-            maxRetries: init.maxRetries ?? 3,
+            maxRetries,
         });
-        const a2a = new GatewayA2AClient(init.gatewayBaseUrl, {
+        const fraud = new GatewayFraudClient(gatewayBaseUrl, tenantId, {
             staticGatewayBearerToken: init.apiKey,
-            maxRetries: init.maxRetries ?? 3,
+            maxRetries,
         });
-        const protocol = new GatewayProtocolClient(init.gatewayBaseUrl, session.harbor.tenantId, {
+        const a2a = new GatewayA2AClient(gatewayBaseUrl, {
             staticGatewayBearerToken: init.apiKey,
-            maxRetries: init.maxRetries ?? 3,
+            maxRetries,
         });
-        return new Paybond(session, signal, fraud, a2a, protocol);
-    }
-    async rotateHarborToken() {
-        await this.session.rotateHarborToken();
+        const protocol = new GatewayProtocolClient(gatewayBaseUrl, tenantId, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries,
+        });
+        return new Paybond(harbor, signal, fraud, a2a, protocol);
     }
-    /** Release HTTP resources (Harbor client + gateway token provider). */
+    /** Reserved for future HTTP client cleanup; safe to call after work completes. */
     async aclose() {
-        await this.session.aclose();
+        await Promise.resolve();
     }
 }
 export { normalizeJson, jsonValueDigest } from "./json-digest.js";

package/dist/mcp-server.d.ts

@@ -24,13 +24,10 @@ type MCPCallToolResult = {
     isError?: boolean;
 };
 export type PaybondMCPSettings = {
-    gatewayBaseUrl: string;
     apiKey: string;
-    harborBaseUrl?: string;
-    harborAccessPath?: string;
+    gatewayBaseUrl?: string;
     principalPath?: string;
     maxRetries?: number;
-    clockSkewSeconds?: number;
 };
 export declare class PaybondMCPServer {
     private readonly runtime;

package/dist/mcp-server.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
-import { GatewayAuthError, GatewayFraudClient, GatewaySignalClient, HarborHttpError, ServiceAccountHarborSession, SignalHttpError, } from "./index.js";
+import { GatewayAuthError, GatewayFraudClient, GatewaySignalClient, SignalHttpError, DEFAULT_PAYBOND_GATEWAY_BASE_URL, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
 const SERVER_VERSION = "0.6.0";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
-const DEFAULT_HARBOR_ACCESS_PATH = "/v1/auth/harbor-access";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const DEFAULT_RECOGNITION_VERIFIER_ID = "paybond-gateway";
 const agentRecognitionProofHeader = "x-paybond-agent-recognition-proof";
@@ -115,16 +114,12 @@ class PaybondMCPRuntime {
     principalValue = null;
     signalValue = null;
     fraudValue = null;
-    harborValue = null;
     constructor(settings) {
         this.settings = {
-            gatewayBaseUrl: settings.gatewayBaseUrl,
+            gatewayBaseUrl: settings.gatewayBaseUrl ?? DEFAULT_PAYBOND_GATEWAY_BASE_URL,
             apiKey: settings.apiKey,
-            harborBaseUrl: settings.harborBaseUrl,
-            harborAccessPath: settings.harborAccessPath ?? DEFAULT_HARBOR_ACCESS_PATH,
             principalPath: settings.principalPath ?? DEFAULT_PRINCIPAL_PATH,
             maxRetries: Math.max(1, settings.maxRetries ?? 3),
-            clockSkewSeconds: Math.max(0, settings.clockSkewSeconds ?? 90),
         };
         this.gateway = new GatewayAPIClient({
             gatewayBaseUrl: this.settings.gatewayBaseUrl,
@@ -158,20 +153,6 @@ class PaybondMCPRuntime {
         }))();
         return this.fraudValue;
     }
-    async harbor() {
-        if (!this.settings.harborBaseUrl) {
-            throw new Error("PAYBOND_HARBOR_URL is required for direct Harbor mutation tools");
-        }
-        this.harborValue ??= ServiceAccountHarborSession.open({
-            gatewayBaseUrl: this.settings.gatewayBaseUrl,
-            apiKey: this.settings.apiKey,
-            harborBaseUrl: this.settings.harborBaseUrl,
-            harborAccessPath: this.settings.harborAccessPath,
-            clockSkewSeconds: this.settings.clockSkewSeconds,
-            maxRetries: this.settings.maxRetries,
-        });
-        return this.harborValue;
-    }
     async listIntents(init) {
         const params = new URLSearchParams({
             limit: String(Math.max(1, Math.min(intArg(init.limit ?? 20, "limit"), 200))),
@@ -319,9 +300,6 @@ export class PaybondMCPServer {
     tools;
     initialized = false;
     constructor(settings) {
-        if (!settings.gatewayBaseUrl.trim()) {
-            throw new Error("PAYBOND_GATEWAY_URL is required");
-        }
         if (!settings.apiKey.trim()) {
             throw new Error("PAYBOND_API_KEY is required");
         }
@@ -701,68 +679,27 @@ export class PaybondMCPServer {
                 }),
             },
         ];
-        if (settings.harborBaseUrl?.trim()) {
-            tools.push({
-                name: "paybond_create_intent_legacy",
-                description: "Legacy direct-Harbor fallback for POST /intents. Prefer paybond_create_intent unless you explicitly need PAYBOND_HARBOR_URL direct mode.",
-                inputSchema: objectSchema({
-                    body: { type: "object", additionalProperties: true },
-                    idempotency_key: { type: "string" },
-                }, ["body"]),
-                call: async (args) => (await this.runtime.harbor()).harbor.createIntent(ensureObject(args.body, "body"), { idempotencyKey: optionalString(args.idempotency_key) }),
-            }, {
-                name: "paybond_fund_intent_legacy",
-                description: "Legacy direct-Harbor fallback for POST /intents/{intent_id}/fund.",
-                inputSchema: objectSchema({
-                    intent_id: { type: "string" },
-                    payment_signature: { type: "string" },
-                    idempotency_key: { type: "string" },
-                }, ["intent_id"]),
-                call: async (args) => jsonObjectFromValue(await (await this.runtime.harbor()).harbor.fundIntent(uuidArg(args.intent_id, "intent_id"), {
-                    paymentSignature: optionalString(args.payment_signature),
-                    idempotencyKey: optionalString(args.idempotency_key),
-                })),
-            }, {
-                name: "paybond_submit_evidence_legacy",
-                description: "Legacy direct-Harbor fallback for POST /intents/{intent_id}/evidence.",
-                inputSchema: objectSchema({
-                    intent_id: { type: "string" },
-                    body: { type: "object", additionalProperties: true },
-                    idempotency_key: { type: "string" },
-                }, ["intent_id", "body"]),
-                call: async (args) => (await this.runtime.harbor()).harbor.submitEvidence(uuidArg(args.intent_id, "intent_id"), ensureObject(args.body, "body"), { idempotencyKey: optionalString(args.idempotency_key) }),
-            });
-        }
         return tools;
     }
 }
 export function settingsFromEnv(env = process.env) {
-    const gatewayBaseUrl = String(env.PAYBOND_GATEWAY_URL ?? "").trim();
     const apiKey = String(env.PAYBOND_API_KEY ?? "").trim();
-    if (!gatewayBaseUrl) {
-        throw new Error("PAYBOND_GATEWAY_URL is required");
-    }
     if (!apiKey) {
         throw new Error("PAYBOND_API_KEY is required");
     }
     return {
-        gatewayBaseUrl,
+        gatewayBaseUrl: DEFAULT_PAYBOND_GATEWAY_BASE_URL,
         apiKey,
-        harborBaseUrl: optionalEnv(env.PAYBOND_HARBOR_URL),
-        harborAccessPath: optionalEnv(env.PAYBOND_HARBOR_ACCESS_PATH) ?? DEFAULT_HARBOR_ACCESS_PATH,
         principalPath: optionalEnv(env.PAYBOND_PRINCIPAL_PATH) ?? DEFAULT_PRINCIPAL_PATH,
         maxRetries: optionalEnv(env.PAYBOND_MCP_MAX_RETRIES)
             ? intArg(optionalEnv(env.PAYBOND_MCP_MAX_RETRIES), "PAYBOND_MCP_MAX_RETRIES")
             : 3,
-        clockSkewSeconds: optionalEnv(env.PAYBOND_MCP_CLOCK_SKEW_SECONDS)
-            ? numberArg(optionalEnv(env.PAYBOND_MCP_CLOCK_SKEW_SECONDS), "PAYBOND_MCP_CLOCK_SKEW_SECONDS")
-            : 90,
     };
 }
 export function main(argv = process.argv.slice(2)) {
     if (argv.includes("--help")) {
         process.stderr.write("Usage: paybond-mcp-server\n\n" +
-            "Runs the tenant-bound Paybond MCP server over stdio using PAYBOND_GATEWAY_URL and PAYBOND_API_KEY.\n");
+            "Runs the tenant-bound Paybond MCP server over stdio using PAYBOND_API_KEY.\n");
         return 0;
     }
     if (argv.length > 0) {
@@ -817,17 +754,6 @@ function intArg(value, field) {
     }
     return parsed;
 }
-function numberArg(value, field) {
-    const parsed = typeof value === "number"
-        ? value
-        : typeof value === "string" && value.trim()
-            ? Number(value)
-            : Number.NaN;
-    if (!Number.isFinite(parsed)) {
-        throw new Error(`${field} must be numeric`);
-    }
-    return parsed;
-}
 function uuidArg(value, field) {
     const raw = stringArg(value, field);
     if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(raw)) {
@@ -909,7 +835,6 @@ function formatError(err) {
     if (err instanceof Error ||
         err instanceof GatewayAuthError ||
         err instanceof GatewayHTTPError ||
-        err instanceof HarborHttpError ||
         err instanceof SignalHttpError) {
         return err.message;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@paybond/kit",
-  "version": "0.6.1",
-  "description": "Paybond Kit for TypeScript: tenant-bound Harbor sessions, capability verification, and signed intent/evidence flows.",
+  "version": "0.7.1",
+  "description": "Paybond Kit for TypeScript: hosted Gateway sessions, capability verification, signed intent/evidence flows, and Stripe Connect or x402 / USDC-on-Base settlement.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",