@capxul/mcp 3.0.0 → 3.1.0

package/dist/main.mjs

@@ -21,6 +21,42 @@ import { EventEmitter } from "events";
 import http2 from "http2";
 import zlib from "zlib";
 import { McpServer, createMcpHandler } from "@modelcontextprotocol/server";
+//#region ../../packages/errors/src/secret-material.ts
+const SENSITIVE_MATERIAL_PATTERNS = [
+	/(?:^|[^a-fA-F0-9])(?<!0[xX])[a-fA-F0-9]{64}(?:$|[^a-fA-F0-9])/u,
+	/eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/u,
+	/(?:(?:sk|pk|rk)_(?:live|test)|(?:phc|phx|ghp|gho|ghu|ghs|ghr|whsec)_|github_pat_|xox[baprs]-|AKIA[0-9A-Z]{16}|AIza)[A-Za-z0-9_-]*/iu,
+	/\bBearer\s+[^\s,;]+/iu,
+	/https?:\/\/[^\s"']+?\/v[0-9]\/[A-Za-z0-9_-]{16,}/iu,
+	/\b(?:api[ _-]?key|access[ _-]?token|token|secret|password|passphrase|private[ _-]?key|authorization|cookie|signature|request[ _-]?body|credential|otp|one[ _-]?time[ _-]?(?:password|code)|verification[ _-]?code)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;&]+)/iu
+];
+const MASKS = [
+	[/\bBearer\s+[^\s,;]+/giu, "Bearer [REDACTED]"],
+	[/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[REDACTED]"],
+	[/(^|[^a-fA-F0-9])(?<!0[xX])[a-fA-F0-9]{64}(?=$|[^a-fA-F0-9])/gu, "$1[REDACTED]"],
+	[/(?:(?:sk|pk|rk)_(?:live|test)|(?:phc|phx|ghp|gho|ghu|ghs|ghr|whsec)_|github_pat_|xox[baprs]-|AKIA[0-9A-Z]{16}|AIza)[A-Za-z0-9_-]*/giu, "[REDACTED]"],
+	[/(https?:\/\/[^\s"']+?\/v[0-9]\/)[A-Za-z0-9_-]{16,}/giu, "$1[REDACTED]"],
+	[/\b(api[ _-]?key|access[ _-]?token|token|secret|password|passphrase|private[ _-]?key|authorization|cookie|signature|request[ _-]?body|credential|otp|one[ _-]?time[ _-]?(?:password|code)|verification[ _-]?code)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;&]+)/giu, "$1=[REDACTED]"]
+];
+/**
+* Reject: does the value carry any known secret material? Best effort — callers
+* drop the whole value on a match; a false negative is a leak, a false positive
+* merely omits an observation field.
+*/
+function containsSensitiveMaterial(value) {
+	return SENSITIVE_MATERIAL_PATTERNS.some((pattern) => pattern.test(value));
+}
+/**
+* Mask: return the value with every known secret rewritten to `[REDACTED]`,
+* preserving surrounding text. Used where a value must still be shown (log
+* lines, provider messages, PostHog rows) but must not carry live credentials.
+*/
+function redactSecrets(value) {
+	let text = value;
+	for (const [pattern, replacement] of MASKS) text = text.replace(pattern, replacement);
+	return text;
+}
+//#endregion
 //#region ../../packages/errors/src/chain-cause.ts
 /**
 * Why an operation failed — the one flat vocabulary. The first four are the
@@ -43,6 +79,9 @@ const FAILURE_MODES$1 = [
 	"insufficient-allowance",
 	"rejected",
 	"unauthorized",
+	"forbidden",
+	"bad-request",
+	"method-unsupported",
 	"unknown"
 ];
 function isFailureMode(value) {
@@ -59,6 +98,33 @@ const CHAIN_UPSTREAMS = [
 function isChainUpstream(value) {
 	return typeof value === "string" && CHAIN_UPSTREAMS.includes(value);
 }
+/**
+* The response headers that name a refusal or let provider support find the
+* request. Nothing else crosses: a header can carry a session or a key.
+*/
+const RESPONSE_HEADER_ALLOWLIST = [
+	"retry-after",
+	"www-authenticate",
+	"content-type",
+	"x-request-id",
+	"cf-ray",
+	"x-ratelimit-remaining",
+	"x-ratelimit-reset",
+	"server"
+];
+const RESPONSE_HEADER_VALUE_MAX = 128;
+/**
+* The allow-listed headers of one answer, masked and bounded. `read` is
+* `Headers.get` or a lookup into a decoded record. Empty when none is present.
+*/
+function boundedResponseHeaders(read) {
+	const headers = {};
+	for (const name of RESPONSE_HEADER_ALLOWLIST) {
+		const value = read(name);
+		if (typeof value === "string" && value.length > 0) headers[name] = boundedEvidence(value, RESPONSE_HEADER_VALUE_MAX);
+	}
+	return headers;
+}
 const PROVIDER_MESSAGE_MAX = 300;
 const METHOD_MAX = 64;
 const REVERT_NAME_MAX = 64;
@@ -66,19 +132,9 @@ const REVERT_ARG_KEY_MAX = 32;
 const REVERT_ARG_VALUE_MAX = 128;
 const REVERT_ARGS_MAX = 8;
 const SELECTOR_RE = /^0x(?:[0-9a-fA-F]{8})?$/u;
-const MASKS = [
-	[/\bBearer\s+[^\s,;]+/giu, "Bearer [REDACTED]"],
-	[/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[REDACTED]"],
-	[/\b0x[a-fA-F0-9]{40,}\b/gu, "[REDACTED]"],
-	[/(^|[^a-fA-F0-9])[a-fA-F0-9]{64}(?=$|[^a-fA-F0-9])/gu, "$1[REDACTED]"],
-	[/(?:(?:sk|pk|rk)_(?:live|test)|(?:phc|phx|ghp|gho|ghu|ghs|ghr|whsec)_|github_pat_|xox[baprs]-|AKIA[0-9A-Z]{16}|AIza)[A-Za-z0-9_-]*/giu, "[REDACTED]"],
-	[/(https?:\/\/[^\s"']+?\/v[0-9]\/)[A-Za-z0-9_-]{16,}/giu, "$1[REDACTED]"],
-	[/\b(api[ _-]?key|access[ _-]?token|token|secret|password|passphrase|private[ _-]?key|authorization|cookie|signature|credential|otp)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;&]+)/giu, "$1=[REDACTED]"]
-];
 /** Mask credential-shaped content, then cap the length. Total on any string. */
 function boundedEvidence(value, max) {
-	let text = value;
-	for (const [pattern, replacement] of MASKS) text = text.replace(pattern, replacement);
+	const text = redactSecrets(value);
 	return text.length <= max ? text : text.slice(0, max);
 }
 function isRecord(value) {
@@ -120,8 +176,36 @@ function decodeChainCause(value) {
 	const revert = decodeRevert(value.revert);
 	if (revert !== null) cause.revert = revert;
 	if (typeof value.providerMessage === "string") cause.providerMessage = boundedEvidence(value.providerMessage, PROVIDER_MESSAGE_MAX);
+	const attempts = decodeAttempts(value.attempts);
+	if (attempts !== null) cause.attempts = attempts;
+	if (isRecord(value.responseHeaders)) {
+		const raw = value.responseHeaders;
+		const headers = boundedResponseHeaders((name) => {
+			const header = raw[name];
+			return typeof header === "string" ? header : null;
+		});
+		if (Object.keys(headers).length > 0) cause.responseHeaders = headers;
+	}
 	return cause;
 }
+/** The attempt sequence, bounded. A malformed entry drops the sequence, never the cause. */
+function decodeAttempts(value) {
+	if (!Array.isArray(value)) return null;
+	const attempts = [];
+	for (const entry of value.slice(0, 5)) {
+		if (!isRecord(entry) || !isChainUpstream(entry.upstream) || !isFailureMode(entry.mode)) return null;
+		const duration = entry.durationMs;
+		if (typeof duration !== "number" || !Number.isFinite(duration) || duration < 0) return null;
+		attempts.push({
+			upstream: entry.upstream,
+			mode: entry.mode,
+			...typeof entry.httpStatus === "number" && Number.isInteger(entry.httpStatus) ? { httpStatus: entry.httpStatus } : {},
+			...typeof entry.rpcCode === "number" && Number.isInteger(entry.rpcCode) ? { rpcCode: entry.rpcCode } : {},
+			durationMs: Math.round(duration)
+		});
+	}
+	return attempts.length === 0 ? null : attempts;
+}
 /**
 * The cause as flat PostHog properties. Same keys from every producer, so one
 * filter (`failure_mode = 'rate-limited'`) finds the gateway's, the backend's,
@@ -140,7 +224,15 @@ function chainCauseProperties(chain) {
 			chain_revert_selector: chain.revert.selector,
 			chain_revert_args: chain.revert.args
 		},
-		...chain.providerMessage === void 0 ? {} : { chain_provider_message: chain.providerMessage }
+		...chain.providerMessage === void 0 ? {} : { chain_provider_message: chain.providerMessage },
+		...chain.attempts === void 0 ? {} : { chain_attempts: chain.attempts.map((attempt) => ({
+			upstream: attempt.upstream,
+			failure_mode: attempt.mode,
+			...attempt.httpStatus === void 0 ? {} : { http_status: attempt.httpStatus },
+			...attempt.rpcCode === void 0 ? {} : { rpc_code: attempt.rpcCode },
+			duration_ms: attempt.durationMs
+		})) },
+		...chain.responseHeaders === void 0 ? {} : { chain_response_headers: chain.responseHeaders }
 	};
 }
 //#endregion
@@ -3779,7 +3871,7 @@ function invalidValueReason(prefix, raw) {
 }
 //#endregion
 //#region ../../packages/sdk/package.json
-var version$3 = "3.0.0";
+var version$3 = "3.1.0";
 //#endregion
 //#region ../../packages/observability/src/engineering.ts
 const ENGINEERING_CAPXUL_ENVS = [
@@ -3929,33 +4021,6 @@ function resolveAuthClientUrl(authBaseUrl, path) {
 	return `${base}${path}`;
 }
 //#endregion
-//#region ../../packages/wire/src/secret-material.ts
-const SENSITIVE_MATERIAL_PATTERNS = [
-	/0x[a-fA-F0-9]{40,}/u,
-	/(?:^|[^a-fA-F0-9])[a-fA-F0-9]{64}(?:$|[^a-fA-F0-9])/u,
-	/eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/u,
-	/(?:(?:sk|pk|rk)_(?:live|test)|(?:phc|phx|ghp|gho|ghu|ghs|ghr|whsec)_|github_pat_|xox[baprs]-|AKIA[0-9A-Z]{16}|AIza)[A-Za-z0-9_-]*/iu
-];
-const RAW_PRIVATE_KEY_MASK = /(^|[^a-fA-F0-9])[a-fA-F0-9]{64}(?=$|[^a-fA-F0-9])/gu;
-const KNOWN_CREDENTIAL_MASK = /(?:(?:sk|pk|rk)_(?:live|test)|(?:phc|phx|ghp|gho|ghu|ghs|ghr|whsec)_|github_pat_|xox[baprs]-|AKIA[0-9A-Z]{16}|AIza)[A-Za-z0-9_-]*/giu;
-const LABELLED_SECRET_MASK = /\b(api[ _-]?key|access[ _-]?token|token|secret|password|passphrase|private[ _-]?key|authorization|cookie|signature|request[ _-]?body|credential|otp|one[ _-]?time[ _-]?(?:password|code)|verification[ _-]?code)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;]+)/giu;
-/**
-* Reject: does the value carry any known secret material? Best effort — callers
-* drop the whole value on a match; a false negative is a leak, a false positive
-* merely omits an observation field.
-*/
-function containsSensitiveMaterial(value) {
-	return SENSITIVE_MATERIAL_PATTERNS.some((pattern) => pattern.test(value));
-}
-/**
-* Mask: return the value with every known secret rewritten to `[REDACTED]`,
-* preserving surrounding text. Used where a value must still be shown (log
-* lines, issue bodies) but must not carry live credentials.
-*/
-function redactSecrets(value) {
-	return value.replace(/\bBearer\s+[^\s,;]+/giu, "Bearer [REDACTED]").replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[REDACTED]").replace(/\b0x[a-fA-F0-9]{40,}\b/gu, "[REDACTED]").replace(RAW_PRIVATE_KEY_MASK, "$1[REDACTED]").replace(KNOWN_CREDENTIAL_MASK, "[REDACTED]").replace(LABELLED_SECRET_MASK, (_match, label) => `${label}=[REDACTED]`);
-}
-//#endregion
 //#region ../../packages/wire/src/observation-context.ts
 /** Single bounded HTTP carrier used before a Convex action envelope exists. */
 const OBSERVATION_CONTEXT_HEADER = "x-capxul-observation-context";
@@ -10530,6 +10595,29 @@ const TelemetryEnvelopeProps = {
 */
 const FailureModeSchema = Schema.Literals(FAILURE_MODES$1);
 const ChainUpstreamSchema = Schema.Literals(CHAIN_UPSTREAMS);
+/**
+* The refusing upstream's response headers (#1818): exactly the names in
+* `RESPONSE_HEADER_ALLOWLIST`, each optional, so the catalog itself refuses a
+* `set-cookie` or `authorization` that a producer let through.
+*/
+const ResponseHeadersSchema = Schema.Struct({
+	"retry-after": OptionalString,
+	"www-authenticate": OptionalString,
+	"content-type": OptionalString,
+	"x-request-id": OptionalString,
+	"cf-ray": OptionalString,
+	"x-ratelimit-remaining": OptionalString,
+	"x-ratelimit-reset": OptionalString,
+	server: OptionalString
+});
+/** One upstream tried, flat (#1818): the `chain_attempts` entry on every producer's row. */
+const ChainAttemptSchema = Schema.Struct({
+	upstream: ChainUpstreamSchema,
+	failure_mode: FailureModeSchema,
+	http_status: Schema.optional(Schema.Number),
+	rpc_code: Schema.optional(Schema.Number),
+	duration_ms: Schema.Number
+});
 const ChainCauseTelemetryProps = {
 	failure_mode: Schema.optional(FailureModeSchema),
 	chain_upstream: Schema.optional(ChainUpstreamSchema),
@@ -10540,7 +10628,9 @@ const ChainCauseTelemetryProps = {
 	chain_revert_name: OptionalString,
 	chain_revert_selector: OptionalString,
 	chain_revert_args: Schema.optional(Schema.Record(Schema.String, Schema.String)),
-	chain_provider_message: OptionalString
+	chain_provider_message: OptionalString,
+	chain_attempts: Schema.optional(Schema.Array(ChainAttemptSchema)),
+	chain_response_headers: Schema.optional(ResponseHeadersSchema)
 };
 const AuthOtpRequestedProps = Schema.Struct({
 	...TelemetryEnvelopeProps,
@@ -10643,7 +10733,8 @@ const ChainUpstreamFallbackProps = Schema.Struct({
 	failure_mode: FailureModeSchema,
 	exhausted: Schema.Boolean,
 	http_status: Schema.optional(Schema.Number),
-	rpc_code: Schema.optional(Schema.Number)
+	rpc_code: Schema.optional(Schema.Number),
+	response_headers: Schema.optional(ResponseHeadersSchema)
 });
 const BundlerErrorProps = Schema.Struct({
 	...TelemetryEnvelopeProps,
@@ -38268,7 +38359,10 @@ const DEFINITIVE_PROVIDER_MODES = /* @__PURE__ */ new Set([
 	"insufficient-balance",
 	"insufficient-allowance",
 	"rejected",
-	"unauthorized"
+	"unauthorized",
+	"forbidden",
+	"bad-request",
+	"method-unsupported"
 ]);
 const isRetryable = (failure) => {
 	if (failure.code === "CANCELLED" || failure.code === "SIGNER_REJECTED") return true;
@@ -41006,13 +41100,13 @@ function observationError(cause) {
 function sanitizeChainDetail(source, detail) {
 	for (const key of [
 		"provider",
-		"provider_operation",
 		"failure_mode",
 		"reason"
 	]) {
 		const value = source[key];
 		if (typeof value === "string" && ENUMERATED_DETAIL_RE.test(value)) detail[key] = value;
 	}
+	sanitizeProviderOperation(source, detail);
 	sanitizeProviderErrorDetail(source, detail);
 	const status = source.http_status;
 	if (typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599) detail.http_status = status;
@@ -41041,6 +41135,43 @@ function sanitizeChainDetail(source, detail) {
 	}
 	const providerMessage = evidenceText(source.chain_provider_message);
 	if (providerMessage !== void 0) detail.chain_provider_message = providerMessage;
+	sanitizeChainAttempts(source, detail);
+}
+/** One flat attempt entry, or undefined when a field is not what the vocabulary allows. */
+function sanitizeChainAttempt(entry) {
+	if (!isPlainObject(entry)) return void 0;
+	const duration = entry.duration_ms;
+	if (!isChainUpstream(entry.upstream) || !isFailureMode(entry.failure_mode) || typeof duration !== "number" || !Number.isFinite(duration) || duration < 0) return;
+	return {
+		upstream: entry.upstream,
+		failure_mode: entry.failure_mode,
+		...typeof entry.http_status === "number" && Number.isInteger(entry.http_status) ? { http_status: entry.http_status } : {},
+		...typeof entry.rpc_code === "number" && Number.isInteger(entry.rpc_code) ? { rpc_code: entry.rpc_code } : {},
+		duration_ms: Math.round(duration)
+	};
+}
+/**
+* The attempt sequence and the refusing upstream's headers (#1818), same
+* bounds as the backend; a malformed entry is dropped, never invented.
+*/
+function sanitizeChainAttempts(source, detail) {
+	if (Array.isArray(source.chain_attempts)) {
+		const attempts = source.chain_attempts.slice(0, 5).map(sanitizeChainAttempt);
+		if (attempts.length > 0 && attempts.every((attempt) => attempt !== void 0)) detail.chain_attempts = attempts;
+	}
+	if (isPlainObject(source.chain_response_headers)) {
+		const raw = source.chain_response_headers;
+		const headers = boundedResponseHeaders((name) => {
+			const value = raw[name];
+			return typeof value === "string" ? value : null;
+		});
+		if (Object.keys(headers).length > 0) detail.chain_response_headers = headers;
+	}
+}
+/** Its own check because a provider operation carries that provider's separators. */
+function sanitizeProviderOperation(source, detail) {
+	const value = source.provider_operation;
+	if (typeof value === "string" && PROVIDER_OPERATION_RE.test(value)) detail.provider_operation = value;
 }
 function sanitizeProviderErrorDetail(source, detail) {
 	if (source.provider_error_source !== "openfort") return;
@@ -41086,11 +41217,22 @@ function sanitizeFailureDetail(input) {
 }
 /** Enumerated codes only (`convex`, `no-secure-context`, `bootstrap-encode`); free text fails. */
 const ENUMERATED_DETAIL_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/u;
+/**
+* A provider operation NAMES A FUNCTION on the provider, so it carries that
+* provider's separators. Convex writes its own as `dir/file:function`
+* (`media:setProfileImage`), and the enumerated shape above rejects both `:`
+* and `/` — so the operation was dropped and the PostHog issue lost the name of
+* what actually failed (staging, 2026-09-03). This widens the separators, not
+* the class: no spaces, same bound, and it matches the backend's own
+* `normalizeOperation`, which has always accepted them.
+*/
+const PROVIDER_OPERATION_RE = /^[A-Za-z][A-Za-z0-9_.:/-]{0,63}$/u;
 const TARGET_HOST_RE = /^[A-Za-z0-9.[\]:-]{1,253}$/u;
 /** A four-byte revert selector, or the bare `0x` of an empty revert. */
 const REVERT_SELECTOR_RE = /^0x(?:[0-9a-fA-F]{8})?$/u;
+/** Same shape as the backend's `normalizeOperation`: a Convex path (`dir/file:fn`) survives. */
 function normalizeOperation(value) {
-	return typeof value === "string" && /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,255}$/u.test(value) ? value : "unknown";
+	return typeof value === "string" && /^[A-Za-z0-9_][A-Za-z0-9_.:/-]{0,255}$/u.test(value) ? value : "unknown";
 }
 function normalizeErrorKind(value) {
 	return typeof value === "string" && /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/u.test(value) ? value : "Error";
@@ -43176,10 +43318,18 @@ async function recordSetupFailure(setup, orgId, error, retryable, observationSou
 	if (!scopedRecorded.ok) return scopedRecorded;
 	return scopedRecorded;
 }
+/**
+* ADR-0023 R7: the layer that saw the chain failure says whether the same
+* request can succeed later; its word wins over the mode table. The table is
+* the one `identity/model.ts` uses, so the two gates read one list
+* (`org.account.get` retried a `transient: false` 403 in 1.5 s, 2026-09-03).
+*/
 function isRetryableProviderFailure(error) {
-	const mode = error.details?.failure_mode;
-	return mode !== "auth-origin-mismatch" && mode !== "app-env-allowlist" && mode !== "no-secure-context";
+	if (error.chain !== void 0) return error.chain.retryable;
+	const mode = error.mode ?? error.details?.failure_mode;
+	return !DEFINITIVE_PROVIDER_MODES.has(isFailureMode(mode) ? mode : void 0);
 }
+/** @internal Exported for the retry-gate test; the surface calls it from the setup loop. */
 function isRetryableOrganizationSetupFailure(error) {
 	if (error.code === "CANCELLED" || error.code === "SIGNER_REJECTED") return true;
 	if (error.code === "PROVIDER_ERROR") return isRetryableProviderFailure(error);
@@ -44938,7 +45088,7 @@ function stdioIdentity(env = process.env, options = {}) {
 }
 //#endregion
 //#region package.json
-var version = "3.0.0";
+var version = "3.1.0";
 //#endregion
 //#region src/deps.ts
 const NO_IDENTITY = async () => void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/mcp",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "private": false,
   "description": "Capxul MCP server for auth, Account readiness, identity, Organizations, relationships, requests, destinations, and testnet funding over Streamable HTTP.",
   "keywords": [
@@ -48,8 +48,8 @@
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
     "vite-plus": "0.3.0",
-    "@capxul/config": "0.2.1",
-    "@capxul/sdk": "3.0.0",
+    "@capxul/config": "0.2.3",
+    "@capxul/sdk": "3.1.0",
     "@capxul/typescript-config": "0.0.0"
   },
   "scripts": {