@paybond/kit 0.4.0 → 0.5.0

package/README.md

@@ -1,13 +1,15 @@
 # `@paybond/kit`
 
-Paybond Kit for TypeScript provides a tenant-bound Harbor client, gateway-backed service-account sessions, capability verification, canonical signing helpers for intent creation and evidence submission, x402 / USDC-on-Base intent funding helpers, tenant-scoped ledger provenance reads, and tenant-scoped Signal analytics and reputation reads.
+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.
 
-Install the public package with:
+## Install
 
 ```bash
 npm install @paybond/kit
 ```
 
+`@paybond/kit` is an ESM-only package for modern Node.js runtimes. Use `import` from a Node ESM / `NodeNext` project or a compatible bundler.
+
 ## Open source
 
 `@paybond/kit` is distributed as open-source software under the Apache 2.0 license. The published npm package includes the full license text in `LICENSE`.
@@ -17,6 +19,23 @@ npm install @paybond/kit
 - 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
+- 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"
+```
 
 ## Tenant isolation
 
@@ -31,22 +50,37 @@ Every session is bound to the tenant realm echoed by gateway-authenticated servi
 ```ts
 import { Paybond } from "@paybond/kit";
 
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`missing ${name}`);
+  }
+  return value;
+}
+
 const paybond = await Paybond.open({
-  gatewayBaseUrl: "https://gateway.example.com",
-  apiKey: process.env.PAYBOND_API_KEY!,
-  harborBaseUrl: "https://harbor.example.com",
+  gatewayBaseUrl: requiredEnv("PAYBOND_GATEWAY_URL"),
+  apiKey: requiredEnv("PAYBOND_API_KEY"),
+  harborBaseUrl: requiredEnv("PAYBOND_HARBOR_URL"),
 });
 
 try {
-  const verified = await paybond.harbor.verifyCapability({
-    intentId: process.env.PAYBOND_INTENT_ID!,
-    token: process.env.PAYBOND_CAPABILITY!,
-    operation: "payments.capture",
-    requestedSpendCents: 18_700,
-  });
-
-  if (!verified.allow) {
-    throw new Error(`verify denied: ${verified.code ?? "deny"} ${verified.message ?? ""}`);
+  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();
@@ -55,14 +89,25 @@ try {
 
 ## What the package includes
 
+Core SDK:
+
 - `Paybond.open(...)` for gateway-authenticated, tenant-derived Harbor sessions
 - `HarborClient` for capability verification, intent creation, x402 funding, evidence submission, and ledger reads
-- Protocol-v2 helpers for mandate verification, replay-safe recognition proof verification, receipt reads, and A2A discovery
-- `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads and signed portfolio artifacts
-- `paybond.signal` on `Paybond` sessions opened from one service-account API key
+- `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
+
+Gateway and trust helpers:
+
+- `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads and signed portfolio artifacts
+- `GatewayFraudClient` and `ServiceAccountFraudSession` for tenant-scoped fraud assessments, review queues, review events, metrics, and release-gate config
+- Protocol-v2 helpers for mandate verification, replay-safe recognition proof verification, receipt reads, and A2A discovery
 - `paybond-mcp-server` for tenant-bound MCP tool exposure to any MCP-compatible host
-- Low-level signing helpers exported for advanced callers
+
+Agent-facing surfaces are model-provider agnostic. Paybond verifies tool operations and tenant scope, not whether a tool call came from OpenAI, Anthropic, Gemini, a local model, or another runtime.
+
+Advanced exports:
+
+- Low-level signing helpers for callers that need to pre-build signed request bodies or evidence payloads
 
 `allowedTools` values are your own tool or operation names, not a Paybond-owned catalog. Harbor enforces string matching against whatever names you chose when creating the intent.
 
@@ -75,21 +120,21 @@ Gateway-backed protocol helpers throw `ProtocolHttpError` with parsed `errorCode
 ## What it does not include
 
 - No operator-tier settlement or console workflows
+- No model-provider-specific TypeScript agent wrapper; use the documented app-side wrapper pattern with `PaybondCapabilityBinding`
 - No model-provider-specific MCP wrapper; the MCP server is host-agnostic and works with any MCP-compatible runtime
 
 ## Docs
 
-- Long-form docs: `docs/kit/`
-- MCP server guide: `docs/kit/mcp-server.md`
-- Agents SDK tutorial: `docs/kit/openai-agents.md`
-- TypeScript quickstart: `docs/kit/quickstart-typescript.md`
-- TypeScript SDK reference: `docs/kit/sdk-reference-typescript.md`
-- Example app: `examples/paybond-kit-typescript/`
-- OpenAI Agents example: `examples/paybond-kit-openai-agents-typescript/`
+- Long-form docs: https://paybond.ai/docs/kit
+- TypeScript quickstart: https://paybond.ai/docs/kit/quickstart-typescript
+- TypeScript SDK reference: https://paybond.ai/docs/kit/sdk-reference-typescript
+- MCP server guide: https://paybond.ai/docs/kit/mcp-server
+- Agent runtime tutorial: https://paybond.ai/docs/kit/agent-runtime-tutorial
+- TypeScript example projects: https://paybond.ai/docs/kit/examples-typescript
 
 ## Release verification
 
-From `kit/ts`:
+For maintainers working from a source checkout, release verification lives in this package directory:
 
 ```bash
 npm run verify:release

package/dist/index.d.ts

@@ -199,6 +199,198 @@ export type SignalPortfolioSummary = {
     total_receipted_volume_cents: number;
     operators_under_review: number;
 };
+export type SignalFraudSeverity = "elevated" | "high" | "critical";
+export type SignalReviewState = "none" | "open" | "in_review" | "closed" | "all";
+export type SignalFraudSignal = {
+    code: string;
+    severity: SignalFraudSeverity | string;
+    category: string;
+    window: string;
+    evidence_count: number;
+    summary: string;
+    affects_score: false;
+    signal_source?: string;
+    first_seen_at?: string;
+    last_seen_at?: string;
+    evidence_binding_strength?: string;
+    provider_event_refs?: string[];
+    intent_refs?: string[];
+};
+export type SignalFraudAssessment = {
+    fraud_signal_version: string;
+    level: "none" | SignalFraudSeverity | string;
+    highest_severity: "none" | SignalFraudSeverity | string;
+    review_priority: "normal" | "elevated" | "high" | "urgent" | string;
+    signal_count: number;
+    severe_signal_count: number;
+    summary: string;
+};
+export type SignalFraudReleaseGateMode = "review_only" | "critical_hold";
+export type SignalFraudReleaseGateConfig = {
+    mode: SignalFraudReleaseGateMode | string;
+};
+export type SignalFraudSignalFamilyReliability = {
+    signal_family: string;
+    reliable: boolean;
+    stale: boolean;
+    sparse: boolean;
+    reviewed_count: number;
+    labeled_outcome_count: number;
+    review_precision_bps: number;
+    min_signal_family_labeled_outcome_count: number;
+    last_labeled_at?: string;
+    reasons: string[];
+    summary: string;
+};
+export type SignalFraudReleaseGateMetricsReliability = {
+    reliable: boolean;
+    stale: boolean;
+    sparse: boolean;
+    reviewed_count: number;
+    labeled_outcome_count: number;
+    review_precision_bps: number;
+    min_reviewed_count: number;
+    min_labeled_outcome_count: number;
+    min_signal_family_labeled_outcome_count: number;
+    min_review_precision_bps: number;
+    last_labeled_at?: string;
+    signal_families?: SignalFraudSignalFamilyReliability[];
+    reasons: string[];
+    summary: string;
+};
+export type SignalFraudReleaseGateDecision = {
+    mode: SignalFraudReleaseGateMode | string;
+    enforcement_enabled: boolean;
+    metrics_reliable: boolean;
+    release_allowed: boolean;
+    hold_required: boolean;
+    critical_signal_count: number;
+    critical_signal_codes: string[];
+    blocking_signal_codes?: string[];
+    blocking_evidence_refs?: string[];
+    reliability_reasons?: string[];
+    reasons: string[];
+    summary: string;
+};
+export type SignalFraudAssessmentResponse = {
+    schema_version: number;
+    tenant_id: string;
+    operator_did: string;
+    score_model_version: string;
+    review_state: string;
+    review_outcome: string;
+    review_reasons: string[];
+    fraud_signals: SignalFraudSignal[];
+    fraud_assessment: SignalFraudAssessment;
+    release_gate?: SignalFraudReleaseGateDecision;
+    [key: string]: unknown;
+};
+export type SignalFraudReviewQueueItem = {
+    operator_did: string;
+    review_state: string;
+    review_outcome: string;
+    review_reasons: string[];
+    anomaly_flagged: boolean;
+    opened_at: string;
+    reviewed_at: string;
+    updated_at: string;
+    last_receipt_message_digest_hex: string;
+    fraud_signals: SignalFraudSignal[];
+    fraud_assessment: SignalFraudAssessment;
+    release_gate?: SignalFraudReleaseGateDecision;
+    [key: string]: unknown;
+};
+export type SignalFraudReviewQueueResponse = {
+    schema_version: number;
+    tenant_id: string;
+    score_model_version: string;
+    items: SignalFraudReviewQueueItem[];
+};
+export type SignalFraudMetricsWindow = "24h" | "7d" | "30d";
+export type SignalFraudMetricsResponse = {
+    schema_version: number;
+    tenant_id: string;
+    score_model_version: string;
+    fraud_signal_version: string;
+    window: SignalFraudMetricsWindow | string;
+    window_started_at: string;
+    window_ended_at: string;
+    generated_at: string;
+    flagged_operator_count: number;
+    critical_signal_count: number;
+    high_signal_count: number;
+    elevated_signal_count: number;
+    review_open_count: number;
+    review_load_count: number;
+    reviewed_count: number;
+    labeled_outcome_count: number;
+    confirmed_risk_count: number;
+    false_positive_count: number;
+    needs_more_evidence_count: number;
+    review_precision_bps: number;
+    false_positive_rate_bps: number;
+    confirmed_risk_rate_bps: number;
+    labeled_coverage_bps: number;
+    median_time_to_review_seconds: number;
+    refund_burst_count: number;
+    dispute_cluster_count: number;
+    replay_appeal_abuse_count: number;
+    critical_signal_hold_candidate_count: number;
+    provider_signal_count: number;
+    stale_label_gap_seconds: number;
+    stale_signal_family_label_gap_count: number;
+    backtest_summary: string;
+    release_gate_config?: SignalFraudReleaseGateConfig;
+    release_gate_metrics_reliability?: SignalFraudReleaseGateMetricsReliability;
+};
+export type SignalFraudReleaseGateConfigResponse = {
+    schema_version: number;
+    tenant_id: string;
+    score_model_version: string;
+    fraud_signal_version: string;
+    generated_at: string;
+    config: SignalFraudReleaseGateConfig;
+    metrics_reliability: SignalFraudReleaseGateMetricsReliability;
+};
+export type SignalFraudReviewEventType = "review_open_requested" | "appeal_requested" | "replay_requested" | "review_outcome_recorded" | SignalFraudReviewOutcome;
+export type SignalFraudReviewOutcome = "confirmed_risk" | "false_positive" | "needs_more_evidence";
+export type SignalFraudReviewEventInput = {
+    eventType: SignalFraudReviewEventType | string;
+    reviewOutcome?: SignalFraudReviewOutcome | string;
+    review_outcome?: SignalFraudReviewOutcome | string;
+    signalCode?: string;
+    signal_code?: string;
+    intentId?: string;
+    intent_id?: string;
+    providerEventId?: string;
+    provider_event_id?: string;
+    summary: string;
+};
+export type SignalFraudReviewEventResponse = {
+    schema_version: number;
+    tenant_id: string;
+    operator_did: string;
+    score_model_version: string;
+    requested_event_type: string;
+    recorded_event_type: string;
+    review_outcome?: string;
+    signal_code?: string;
+    intent_id?: string;
+    provider_event_id?: string;
+    accepted: boolean;
+    next_eligible_at?: string;
+    [key: string]: unknown;
+};
+export type ListFraudReviewQueueOptions = {
+    state?: SignalReviewState | string;
+    severity?: SignalFraudSeverity | string;
+    limit?: number;
+    scoreVersion?: string;
+};
+export type GetFraudMetricsOptions = {
+    window?: SignalFraudMetricsWindow | string;
+    scoreVersion?: string;
+};
 export type A2AAgentCard = {
     name: string;
     description: string;
@@ -616,6 +808,10 @@ type GatewaySignalClientOptions = {
     staticGatewayBearerToken: string;
     maxRetries?: number;
 };
+type GatewayFraudClientOptions = {
+    staticGatewayBearerToken: string;
+    maxRetries?: number;
+};
 /**
  * Tenant-bound reader for gateway Signal routes.
  */
@@ -634,6 +830,34 @@ export declare class GatewaySignalClient {
     getOperatorExplanation(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
     getOperatorReviewStatus(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
 }
+/**
+ * Tenant-bound client for gateway fraud review and metrics routes.
+ */
+export declare class GatewayFraudClient {
+    private readonly base;
+    readonly tenantId: string;
+    private readonly bearerToken;
+    private readonly maxRetries;
+    constructor(gatewayBaseUrl: string, tenantId: string, options: GatewayFraudClientOptions);
+    private fetchGetWithRetries;
+    private fetchPostJSON;
+    private fetchPutJSON;
+    private assertTenant;
+    private assertOperator;
+    private query;
+    private normalizedSeverity;
+    private normalizedWindow;
+    private normalizedReleaseGateMode;
+    private normalizedReviewEventType;
+    private normalizedReviewOutcome;
+    private optionalReviewContext;
+    getFraudAssessment(operatorDid: string, scoreVersion?: string): Promise<SignalFraudAssessmentResponse | null>;
+    listFraudReviewQueue(options?: ListFraudReviewQueueOptions): Promise<SignalFraudReviewQueueResponse>;
+    getFraudMetrics(options?: GetFraudMetricsOptions): Promise<SignalFraudMetricsResponse>;
+    getFraudReleaseGateConfig(scoreVersion?: string): Promise<SignalFraudReleaseGateConfigResponse>;
+    setFraudReleaseGateMode(mode: SignalFraudReleaseGateMode | string): Promise<SignalFraudReleaseGateConfigResponse>;
+    recordFraudReviewEvent(operatorDid: string, event: SignalFraudReviewEventInput, scoreVersion?: string): Promise<SignalFraudReviewEventResponse>;
+}
 type GatewayA2AClientOptions = {
     staticGatewayBearerToken?: string;
     maxRetries?: number;
@@ -701,6 +925,7 @@ export type ServiceAccountSignalSessionInit = {
     principalPath?: string;
     maxRetries?: number;
 };
+export type ServiceAccountFraudSessionInit = ServiceAccountSignalSessionInit;
 /**
  * Read-only tenant-bound Signal session for one service-account API key.
  */
@@ -710,6 +935,15 @@ export declare class ServiceAccountSignalSession {
     static open(init: ServiceAccountSignalSessionInit): Promise<ServiceAccountSignalSession>;
     aclose(): Promise<void>;
 }
+/**
+ * Tenant-bound fraud review and metrics session for one service-account API key.
+ */
+export declare class ServiceAccountFraudSession {
+    readonly fraud: GatewayFraudClient;
+    private constructor();
+    static open(init: ServiceAccountFraudSessionInit): Promise<ServiceAccountFraudSession>;
+    aclose(): Promise<void>;
+}
 /**
  * Parameters for {@link PaybondIntents.create} (tenant is taken from the bound Harbor client).
  * `settlementRail`, when set, requests one allowed rail; Harbor still resolves the destination
@@ -754,6 +988,7 @@ export declare class PaybondIntents {
 export declare class Paybond {
     readonly harbor: HarborClient;
     readonly signal: GatewaySignalClient;
+    readonly fraud: GatewayFraudClient;
     readonly a2a: GatewayA2AClient;
     readonly protocol: GatewayProtocolClient;
     readonly intents: PaybondIntents;

package/dist/index.js

@@ -659,6 +659,16 @@ export class HarborClient {
 }
 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([
+    "review_open_requested",
+    "appeal_requested",
+    "replay_requested",
+    "review_outcome_recorded",
+    "confirmed_risk",
+    "false_positive",
+    "needs_more_evidence",
+]);
+const FRAUD_REVIEW_OUTCOMES = new Set(["confirmed_risk", "false_positive", "needs_more_evidence"]);
 function assertJSONObject(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("expected JSON object");
@@ -884,6 +894,286 @@ export class GatewaySignalClient {
         return body;
     }
 }
+/**
+ * Tenant-bound client for gateway fraud review and metrics routes.
+ */
+export class GatewayFraudClient {
+    base;
+    tenantId;
+    bearerToken;
+    maxRetries;
+    constructor(gatewayBaseUrl, tenantId, options) {
+        this.base = normalizeBase(gatewayBaseUrl) + "/";
+        this.tenantId = tenantId.trim();
+        this.bearerToken = options.staticGatewayBearerToken.trim();
+        this.maxRetries = Math.max(1, options.maxRetries ?? 3);
+    }
+    async fetchGetWithRetries(url) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: "GET",
+                    headers: {
+                        accept: "application/json",
+                        authorization: `Bearer ${this.bearerToken}`,
+                    },
+                });
+            }
+            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)) {
+                if (attempt + 1 >= this.maxRetries) {
+                    return res;
+                }
+                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 fetchPostJSON(url, payload) {
+        return fetch(url, {
+            method: "POST",
+            headers: {
+                accept: "application/json",
+                authorization: `Bearer ${this.bearerToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    async fetchPutJSON(url, payload) {
+        return fetch(url, {
+            method: "PUT",
+            headers: {
+                accept: "application/json",
+                authorization: `Bearer ${this.bearerToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    assertTenant(body, url) {
+        const tid = String(body.tenant_id ?? "");
+        if (tid !== this.tenantId) {
+            throw new Error(`fraud tenant mismatch: client=${this.tenantId} gateway=${tid} url=${url}`);
+        }
+    }
+    assertOperator(body, operatorDid, label) {
+        const echoedOperator = String(body.operator_did ?? "");
+        if (echoedOperator !== operatorDid) {
+            throw new Error(`fraud ${label} operator mismatch: requested=${operatorDid} gateway=${echoedOperator}`);
+        }
+    }
+    query(params) {
+        const qs = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (typeof value === "number") {
+                qs.set(key, String(value));
+                continue;
+            }
+            if (typeof value === "string" && value.trim()) {
+                qs.set(key, value.trim());
+            }
+        }
+        const raw = qs.toString();
+        return raw ? `?${raw}` : "";
+    }
+    normalizedSeverity(severity) {
+        const normalized = severity?.trim();
+        if (!normalized) {
+            return undefined;
+        }
+        if (!["elevated", "high", "critical"].includes(normalized)) {
+            throw new Error("fraud severity must be one of elevated, high, or critical");
+        }
+        return normalized;
+    }
+    normalizedWindow(window) {
+        const normalized = window?.trim();
+        if (!normalized) {
+            return undefined;
+        }
+        if (!["24h", "7d", "30d"].includes(normalized)) {
+            throw new Error("fraud metrics window must be one of 24h, 7d, or 30d");
+        }
+        return normalized;
+    }
+    normalizedReleaseGateMode(mode) {
+        const normalized = mode.trim();
+        if (!["review_only", "critical_hold"].includes(normalized)) {
+            throw new Error("fraud release gate mode must be one of review_only or critical_hold");
+        }
+        return normalized;
+    }
+    normalizedReviewEventType(eventType) {
+        const normalized = eventType.trim();
+        if (!FRAUD_REVIEW_EVENT_TYPES.has(normalized)) {
+            throw new Error("fraud review eventType must be one of review_open_requested, appeal_requested, replay_requested, review_outcome_recorded, confirmed_risk, false_positive, or needs_more_evidence");
+        }
+        return normalized;
+    }
+    normalizedReviewOutcome(outcome) {
+        const normalized = outcome.trim();
+        if (!FRAUD_REVIEW_OUTCOMES.has(normalized)) {
+            throw new Error("fraud review outcome must be one of confirmed_risk, false_positive, or needs_more_evidence");
+        }
+        return normalized;
+    }
+    optionalReviewContext(value) {
+        const normalized = value?.trim();
+        return normalized || undefined;
+    }
+    async getFraudAssessment(operatorDid, scoreVersion) {
+        const enc = encodeURIComponent(operatorDid);
+        const url = `${this.base}signal/v1/operators/${enc}/review-status${this.query({
+            score_version: scoreVersion,
+        })}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (res.status === 404) {
+            return null;
+        }
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud assessment HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        this.assertOperator(body, operatorDid, "assessment");
+        return body;
+    }
+    async listFraudReviewQueue(options = {}) {
+        let rawLimit;
+        if (options.limit !== undefined) {
+            if (!Number.isFinite(options.limit)) {
+                throw new Error("fraud review queue limit must be a finite number");
+            }
+            rawLimit = Math.max(1, Math.min(Math.floor(options.limit), 500));
+        }
+        const url = `${this.base}signal/v1/review-queue${this.query({
+            state: options.state,
+            fraud_severity: this.normalizedSeverity(options.severity),
+            limit: rawLimit,
+            score_version: options.scoreVersion,
+        })}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud review queue HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
+    async getFraudMetrics(options = {}) {
+        const url = `${this.base}signal/v1/fraud/metrics${this.query({
+            window: this.normalizedWindow(options.window),
+            score_version: options.scoreVersion,
+        })}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud metrics HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
+    async getFraudReleaseGateConfig(scoreVersion) {
+        const url = `${this.base}signal/v1/fraud/release-gate${this.query({
+            score_version: scoreVersion,
+        })}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud release gate HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
+    async setFraudReleaseGateMode(mode) {
+        const normalized = this.normalizedReleaseGateMode(mode);
+        const url = `${this.base}signal/v1/fraud/release-gate`;
+        const res = await this.fetchPutJSON(url, { mode: normalized });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Fraud release gate update HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
+    async recordFraudReviewEvent(operatorDid, event, scoreVersion) {
+        let eventType = this.normalizedReviewEventType(event.eventType);
+        let reviewOutcome = event.reviewOutcome ?? event.review_outcome;
+        if (FRAUD_REVIEW_OUTCOMES.has(eventType)) {
+            reviewOutcome = eventType;
+            eventType = "review_outcome_recorded";
+        }
+        const normalizedOutcome = reviewOutcome === undefined ? undefined : this.normalizedReviewOutcome(reviewOutcome);
+        if (eventType === "review_outcome_recorded" && normalizedOutcome === undefined) {
+            throw new Error("fraud review outcome must be one of confirmed_risk, false_positive, or needs_more_evidence");
+        }
+        const signalCode = this.optionalReviewContext(event.signalCode ?? event.signal_code);
+        const intentId = this.optionalReviewContext(event.intentId ?? event.intent_id);
+        const providerEventId = this.optionalReviewContext(event.providerEventId ?? event.provider_event_id);
+        const enc = encodeURIComponent(operatorDid);
+        const url = `${this.base}signal/v1/operators/${enc}/review-events${this.query({
+            score_version: scoreVersion,
+        })}`;
+        const res = await this.fetchPostJSON(url, {
+            event_type: eventType,
+            ...(normalizedOutcome ? { review_outcome: normalizedOutcome } : {}),
+            ...(signalCode ? { signal_code: signalCode } : {}),
+            ...(intentId ? { intent_id: intentId } : {}),
+            ...(providerEventId ? { provider_event_id: providerEventId } : {}),
+            summary: event.summary,
+        });
+        const text = await res.text();
+        if (!res.ok && res.status !== 429) {
+            throw new SignalHttpError(`Fraud review event HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        this.assertOperator(body, operatorDid, "review event");
+        return body;
+    }
+}
 /**
  * Public or optionally authenticated reader for the gateway's A2A discovery surface.
  */
@@ -1218,6 +1508,25 @@ export class ServiceAccountSignalSession {
         await Promise.resolve();
     }
 }
+/**
+ * Tenant-bound fraud review and metrics session for one service-account API key.
+ */
+export class ServiceAccountFraudSession {
+    fraud;
+    constructor(fraud) {
+        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, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries: init.maxRetries ?? 3,
+        }));
+    }
+    async aclose() {
+        await Promise.resolve();
+    }
+}
 /**
  * Ergonomic intent helpers: principal-signed intent create, x402 funding, and payee-signed evidence.
  */
@@ -1267,14 +1576,16 @@ export class PaybondIntents {
 export class Paybond {
     harbor;
     signal;
+    fraud;
     a2a;
     protocol;
     intents;
     session;
-    constructor(session, signal, a2a, protocol) {
+    constructor(session, signal, fraud, a2a, protocol) {
         this.session = session;
         this.harbor = session.harbor;
         this.signal = signal;
+        this.fraud = fraud;
         this.a2a = a2a;
         this.protocol = protocol;
         this.intents = new PaybondIntents(session.harbor);
@@ -1286,6 +1597,10 @@ export class Paybond {
             staticGatewayBearerToken: init.apiKey,
             maxRetries: init.maxRetries ?? 3,
         });
+        const fraud = new GatewayFraudClient(init.gatewayBaseUrl, session.harbor.tenantId, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries: init.maxRetries ?? 3,
+        });
         const a2a = new GatewayA2AClient(init.gatewayBaseUrl, {
             staticGatewayBearerToken: init.apiKey,
             maxRetries: init.maxRetries ?? 3,
@@ -1294,7 +1609,7 @@ export class Paybond {
             staticGatewayBearerToken: init.apiKey,
             maxRetries: init.maxRetries ?? 3,
         });
-        return new Paybond(session, signal, a2a, protocol);
+        return new Paybond(session, signal, fraud, a2a, protocol);
     }
     async rotateHarborToken() {
         await this.session.rotateHarborToken();

package/dist/mcp-server.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { GatewayAuthError, GatewaySignalClient, HarborHttpError, ServiceAccountHarborSession, SignalHttpError, } from "./index.js";
+import { GatewayAuthError, GatewayFraudClient, GatewaySignalClient, HarborHttpError, ServiceAccountHarborSession, SignalHttpError, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
-const SERVER_VERSION = "0.4.0";
+const SERVER_VERSION = "0.5.0";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_HARBOR_ACCESS_PATH = "/v1/auth/harbor-access";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
@@ -114,6 +114,7 @@ class PaybondMCPRuntime {
     gateway;
     principalValue = null;
     signalValue = null;
+    fraudValue = null;
     harborValue = null;
     constructor(settings) {
         this.settings = {
@@ -150,6 +151,13 @@ class PaybondMCPRuntime {
         }))();
         return this.signalValue;
     }
+    async fraud() {
+        this.fraudValue ??= (async () => new GatewayFraudClient(this.settings.gatewayBaseUrl, await this.tenantId(), {
+            staticGatewayBearerToken: this.settings.apiKey,
+            maxRetries: this.settings.maxRetries,
+        }))();
+        return this.fraudValue;
+    }
     async harbor() {
         if (!this.settings.harborBaseUrl) {
             throw new Error("PAYBOND_HARBOR_URL is required for direct Harbor mutation tools");
@@ -529,6 +537,27 @@ export class PaybondMCPServer {
                 }),
                 call: async (args) => (await this.runtime.signal()).getSignedPortfolioArtifact(optionalString(args.score_version)),
             },
+            {
+                name: "paybond_get_fraud_assessment",
+                description: "Fetch the read-only fraud assessment for one tenant-scoped operator DID.",
+                inputSchema: objectSchema({
+                    operator_did: { type: "string" },
+                    score_version: { type: "string" },
+                }, ["operator_did"]),
+                call: async (args) => (await this.runtime.fraud()).getFraudAssessment(stringArg(args.operator_did, "operator_did"), optionalString(args.score_version)),
+            },
+            {
+                name: "paybond_get_fraud_metrics",
+                description: "Fetch tenant-scoped read-only fraud backtesting and monitoring metrics for a supported active window.",
+                inputSchema: objectSchema({
+                    window: { type: "string", enum: ["24h", "7d", "30d"] },
+                    score_version: { type: "string" },
+                }),
+                call: async (args) => (await this.runtime.fraud()).getFraudMetrics({
+                    window: optionalString(args.window),
+                    scoreVersion: optionalString(args.score_version),
+                }),
+            },
             {
                 name: "paybond_get_a2a_agent_card",
                 description: "Fetch the published Paybond A2A discovery card for protocol-trust delegation.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paybond/kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Paybond Kit for TypeScript: tenant-bound Harbor sessions, capability verification, and signed intent/evidence flows.",
   "license": "Apache-2.0",
   "type": "module",
@@ -38,11 +38,20 @@
   "keywords": [
     "paybond",
     "harbor",
+    "kit",
     "agents",
-    "typescript",
+    "agent-runtime",
+    "agent-payments",
     "escrow",
+    "intent-escrow",
     "capabilities",
-    "mcp"
+    "capability-verification",
+    "tenant-bound",
+    "x402",
+    "usdc",
+    "mcp",
+    "reputation",
+    "typescript"
   ],
   "publishConfig": {
     "access": "public",