@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/public-capability-contract.js

@@ -0,0 +1,186 @@
+/**
+ * Generated public-surface contract captured through the real MCP SDK.
+ *
+ * This is the mechanical source for catalogue, alias, discovery, resource, and
+ * prompt truth across the npm/full, remote/grouped, and OpenAI/full profiles.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CAPABILITY_META_KEY, } from "./capability-truth.js";
+import { FISCAL_MODELO_ALIASES } from "./fiscal-aliases.js";
+import { MCP_PROMPT_COUNT } from "./prompts/register-all.js";
+import { localMcpSurfaceComposition, registerMcpSurface, remoteMcpSurfaceComposition, } from "./server-composition.js";
+import { GROUPED_META_TOOL_COUNT } from "./tool-exposure.js";
+export const PUBLIC_CAPABILITY_CONTRACT_VERSION = 2;
+function makeRegistrationClient() {
+    return new Proxy({}, {
+        get: () => async () => ({ data: [], total: 0, limit: 0, offset: 0 }),
+    });
+}
+function isMethodNotFound(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === -32601);
+}
+async function listPromptsOrEmpty(client) {
+    try {
+        const result = await client.listPrompts();
+        return result.prompts.map((prompt) => prompt.name).sort();
+    }
+    catch (error) {
+        if (isMethodNotFound(error))
+            return [];
+        throw error;
+    }
+}
+async function listResourcesOrEmpty(client) {
+    try {
+        const result = await client.listResources();
+        return result.resources.map((resource) => resource.uri).sort();
+    }
+    catch (error) {
+        if (isMethodNotFound(error))
+            return [];
+        throw error;
+    }
+}
+function compactDiscoveryTool(value) {
+    if (typeof value !== "object" || value === null) {
+        throw new Error("Grouped discovery returned a non-object tool result");
+    }
+    const record = value;
+    if (typeof record.name !== "string") {
+        throw new Error("Grouped discovery result omitted the tool name");
+    }
+    return {
+        name: record.name,
+        ...(record.annotations && typeof record.annotations === "object"
+            ? { annotations: record.annotations }
+            : {}),
+        ...(record.capability && typeof record.capability === "object"
+            ? { capability: record.capability }
+            : {}),
+    };
+}
+async function captureDiscoveryTruth(client) {
+    const searched = await client.callTool({
+        name: "search_tools",
+        arguments: { query: "send_invoice", limit: 1 },
+    });
+    const searchTools = searched.structuredContent?.tools;
+    if (!Array.isArray(searchTools) || searchTools.length !== 1) {
+        throw new Error("search_tools did not return the pinned send_invoice result");
+    }
+    const described = await client.callTool({
+        name: "describe_tool",
+        arguments: { name: "send_invoice" },
+    });
+    return {
+        searchTools: compactDiscoveryTool(searchTools[0]),
+        describeTool: compactDiscoveryTool(described.structuredContent),
+    };
+}
+async function captureSurface(configure, captureDiscovery = false) {
+    const server = new McpServer({ name: "public-capability-capture", version: "1.0.0" });
+    configure(server, makeRegistrationClient());
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "public-capability-capture-client", version: "1.0.0" }, { capabilities: {} });
+    try {
+        await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+        const listed = await client.listTools();
+        const tools = listed.tools
+            .map((tool) => {
+            const meta = tool._meta;
+            const capability = meta?.[CAPABILITY_META_KEY];
+            return {
+                name: tool.name,
+                ...(tool.annotations
+                    ? { annotations: tool.annotations }
+                    : {}),
+                ...(capability ? { capability } : {}),
+            };
+        })
+            .sort((left, right) => left.name.localeCompare(right.name));
+        const [resources, prompts] = await Promise.all([
+            listResourcesOrEmpty(client),
+            listPromptsOrEmpty(client),
+        ]);
+        const discovery = captureDiscovery
+            ? await captureDiscoveryTruth(client)
+            : undefined;
+        return { tools, resources, prompts, ...(discovery ? { discovery } : {}) };
+    }
+    finally {
+        await Promise.allSettled([client.close(), server.close()]);
+    }
+}
+export async function capturePublicCapabilityContract() {
+    const localFull = await captureSurface((server, client) => {
+        registerMcpSurface(server, client, localMcpSurfaceComposition(false, false));
+    });
+    const remoteGrouped = await captureSurface((server, client) => {
+        registerMcpSurface(server, client, remoteMcpSurfaceComposition(false, true));
+    }, true);
+    const openaiFull = await captureSurface((server, client) => {
+        registerMcpSurface(server, client, remoteMcpSurfaceComposition(true, false));
+    });
+    const aliases = new Set(Object.keys(FISCAL_MODELO_ALIASES));
+    const discovery = new Set(["list_tool_groups", "search_tools", "describe_tool"]);
+    const canonicalOperations = remoteGrouped.tools.filter((tool) => !aliases.has(tool.name) && !discovery.has(tool.name)).length;
+    if (localFull.prompts.length !== MCP_PROMPT_COUNT ||
+        remoteGrouped.prompts.length !== MCP_PROMPT_COUNT) {
+        throw new Error(`Prompt count drift: registered ${localFull.prompts.length}/${remoteGrouped.prompts.length}, expected ${MCP_PROMPT_COUNT}`);
+    }
+    return {
+        contractVersion: PUBLIC_CAPABILITY_CONTRACT_VERSION,
+        catalogue: {
+            canonicalOperations,
+            aliasNames: aliases.size,
+            discoveryNames: GROUPED_META_TOOL_COUNT,
+        },
+        surfaces: { localFull, remoteGrouped, openaiFull },
+    };
+}
+function canonicalize(contract) {
+    const clone = structuredClone(contract);
+    for (const surface of Object.values(clone.surfaces)) {
+        surface.tools.sort((left, right) => left.name.localeCompare(right.name));
+        surface.resources.sort();
+        surface.prompts.sort();
+    }
+    return clone;
+}
+export function serializePublicCapabilityContract(contract) {
+    return `${JSON.stringify(canonicalize(contract), null, 2)}\n`;
+}
+export function assertPublicCapabilityContract(actual, expected) {
+    if (actual.contractVersion !== PUBLIC_CAPABILITY_CONTRACT_VERSION) {
+        throw new Error(`Unsupported public capability contract ${actual.contractVersion}`);
+    }
+    const fullSurfaces = [actual.surfaces.localFull, actual.surfaces.remoteGrouped];
+    for (const surface of fullSurfaces) {
+        for (const tool of surface.tools) {
+            assertFullToolTruth(tool);
+        }
+    }
+    const serializedActual = serializePublicCapabilityContract(actual);
+    const serializedExpected = serializePublicCapabilityContract(expected);
+    if (serializedActual !== serializedExpected) {
+        throw new Error("Public capability contract drift; regenerate and review the runtime capture");
+    }
+}
+function assertFullToolTruth(tool) {
+    if (!tool.capability) {
+        throw new Error(`Full-surface tool ${tool.name} lacks ${CAPABILITY_META_KEY}`);
+    }
+    if (tool.capability.callability === "available") {
+        throw new Error(`Tool ${tool.name} conflates registration with availability`);
+    }
+    if (tool.capability.externalInteraction &&
+        tool.annotations?.openWorldHint !== true) {
+        throw new Error(`External tool ${tool.name} must set openWorldHint=true`);
+    }
+}
+//# sourceMappingURL=public-capability-contract.js.map

package/dist/redaction.d.ts

@@ -17,6 +17,21 @@
  */
 /** Sentinel left in place of a redacted value in cloned (tracing) payloads. */
 export declare const REDACTED = "[redacted]";
+/**
+ * Return a backend request id only when it is a short opaque token that is
+ * safe to echo to an agent (no whitespace, no prose, no instructions).
+ */
+export declare function safeRequestId(value: unknown): string | undefined;
+/**
+ * Allowlist short, single-line human remediation prose for agent display.
+ *
+ * Server text is omitted unless it matches one of two explicit semantics: an
+ * API-key scope instruction matching the ERP contract, or a conservative
+ * workspace-owner access instruction. A small character alphabet and the
+ * structural checks below are defense in depth. Rejection is intentional: an
+ * omitted hint is safer than attempting to redact arbitrary backend prose.
+ */
+export declare function sanitizeServerRemediation(value: unknown, errorCode?: string): string | undefined;
 /**
  * Field names whose VALUES must never appear in logs, traces, or any surface
  * outside the process boundary. Includes snake_case + locale synonyms because

package/dist/redaction.js

@@ -17,6 +17,73 @@
  */
 /** Sentinel left in place of a redacted value in cloned (tracing) payloads. */
 export const REDACTED = "[redacted]";
+/** Opaque backend correlation id (publicApi `meta.requestId` / `X-Request-Id`). */
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+/**
+ * Return a backend request id only when it is a short opaque token that is
+ * safe to echo to an agent (no whitespace, no prose, no instructions).
+ */
+export function safeRequestId(value) {
+    return typeof value === "string" && REQUEST_ID_PATTERN.test(value) ? value : undefined;
+}
+const MAX_SERVER_REMEDIATION_CHARS = 500;
+const SERVER_REMEDIATION_PROSE_ALPHABET = /^[\p{L}\p{N} .,;:!?'"()_/*+\-]+$/u;
+const LIVE_EINVOICE_SCOPE_REMEDIATION = "This API key requires the einvoice:read or einvoice:write scope to access e-invoicing endpoints. Add the scope when creating or updating the key.";
+const OWNER_ACCESS_REMEDIATION = /^(?:Ask (?:a|the|your) workspace owner to (?:grant (?:you )?access to (?:this|the) (?:resource|feature|action)|grant (?:the )?required (?:scope|permission))|Contact (?:a|the|your) workspace owner to request access to (?:this|the) (?:resource|feature|action))\.$/iu;
+const GENERIC_REMEDIATION_MESSAGES = new Set([
+    "forbidden",
+    "access denied",
+    "access forbidden",
+    "authorization failed",
+    "not authorized",
+]);
+/**
+ * Allowlist short, single-line human remediation prose for agent display.
+ *
+ * Server text is omitted unless it matches one of two explicit semantics: an
+ * API-key scope instruction matching the ERP contract, or a conservative
+ * workspace-owner access instruction. A small character alphabet and the
+ * structural checks below are defense in depth. Rejection is intentional: an
+ * omitted hint is safer than attempting to redact arbitrary backend prose.
+ */
+export function sanitizeServerRemediation(value, errorCode = "") {
+    if (typeof value !== "string")
+        return undefined;
+    const remediation = value.trim();
+    if (!remediation || remediation.length > MAX_SERVER_REMEDIATION_CHARS)
+        return undefined;
+    if (!SERVER_REMEDIATION_PROSE_ALPHABET.test(remediation))
+        return undefined;
+    const normalized = remediation.toLowerCase();
+    if (normalized === errorCode.trim().toLowerCase()
+        || GENERIC_REMEDIATION_MESSAGES.has(normalized)) {
+        return undefined;
+    }
+    if (remediation !== LIVE_EINVOICE_SCOPE_REMEDIATION
+        && !OWNER_ACCESS_REMEDIATION.test(remediation)) {
+        return undefined;
+    }
+    const credentialOrInternalShape = [
+        // Frihet API keys are `fri_` plus 32 random bytes encoded base64url (43 chars).
+        /\bfri_[A-Za-z0-9_-]{32,128}(?=$|[^A-Za-z0-9_-])/u,
+        // Header name is not required for a leaked bearer/basic credential to be dangerous.
+        /\b(?:bearer|basic)\s+[A-Za-z0-9+/_-]{8,}={0,2}(?:\s|[.,;!?]|$)/iu,
+        /\b(?:api[_ -]?key|access[_ -]?token|refresh[_ -]?token|token|client[_ -]?secret|password)\s*(?::|=|\bis\b|\bwas\b)\s*["']?\S+/iu,
+        /\b(?:whsec_[A-Za-z0-9_-]+|ya29\.[A-Za-z0-9._-]+)\b/u,
+        /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/u,
+        /(?:^|\s)at\s+(?:async\s+)?[^\s]+\s*\([^)]*:\d+(?::\d+)?\)/u,
+        // Any whitespace-delimited absolute path is outside the remediation contract.
+        /(?:^|[\s("'])\/(?:[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)/u,
+        /(?:^|[\s("'])[A-Za-z]:\\/u,
+        // Relative application/source paths (for example `src/auth.ts`).
+        /(?:^|\s)(?:(?:\.\.?\/)?(?:src|lib|dist|build|node_modules|functions|workers)\/)[A-Za-z0-9_./-]+/iu,
+        /\b[A-Za-z0-9_./-]+\.(?:c|m)?(?:j|t)sx?(?::\d+(?::\d+)?)?\b/u,
+        /\b(?:node_modules|file:\/\/)/iu,
+    ];
+    if (credentialOrInternalShape.some((pattern) => pattern.test(remediation)))
+        return undefined;
+    return remediation;
+}
 /**
  * Field names whose VALUES must never appear in logs, traces, or any surface
  * outside the process boundary. Includes snake_case + locale synonyms because
@@ -24,6 +91,8 @@ export const REDACTED = "[redacted]";
  */
 export const SENSITIVE_FIELD_NAMES = [
     "taxId", "tax_id", // Primary field name + snake_case variant
+    "taxIdNormalized", "tax_id_normalized", // Search-normalized government tax ID
+    "clientTaxId", "client_tax_id", // Per-document client government tax ID
     "nif", "cif", "vatNumber", // Spanish/EU synonyms for government tax ID
     "vat_number", "vatId", "vat_id",
     "secret", // Webhook signing credential
@@ -39,6 +108,20 @@ export const SENSITIVE_FIELD_NAMES = [
     "requestId", "request_id", "traceId", "trace_id",
     "sessionId", "session_id", "userId", "user_id",
     "verifactuHash", "verifactu_hash",
+    // Raw Firestore records can contain nested fiscal-submission state and
+    // capability/payment identifiers that are not part of any public response
+    // contract. Redact the parent objects so future nested fields fail closed.
+    "verifactu", "verifactuAnulacion", "verifactu_anulacion",
+    "verifactuSubmission", "verifactu_submission",
+    "paymentDetails", "payment_details",
+    "paymentUrl", "payment_url", "paymentLink", "payment_link",
+    "paymentIntentId", "payment_intent_id", "stripePaymentIntentId",
+    "publicHash", "public_hash",
+    "bankTransactionId", "bank_transaction_id",
+    "bankIncomeAuthority", "bank_income_authority",
+    // Backend search indexes can embed normalized names, email addresses and
+    // government identifiers even when the canonical fields are removed.
+    "searchTokens", "search_tokens",
 ];
 /** Recursively removes named fields from an object/array tree, IN PLACE. */
 export function deepRedact(obj, fields = SENSITIVE_FIELD_NAMES) {