@frihet/mcp-server 1.16.6 → 1.17.0

package/dist/openai-review-oauth.d.ts

@@ -3,6 +3,16 @@
  * freeze gate. Values in this module are public protocol metadata, not secrets.
  */
 export declare const OPENAI_REVIEW_ORIGIN = "https://openai-mcp.frihet.io";
+export declare const FULL_MCP_ORIGIN = "https://mcp.frihet.io";
+export declare const FRIHET_CONNECTOR_SCOPE = "frihet:workspace.manage";
+/** RFC 7636 S256 challenges are the 32-byte SHA-256 digest encoded as
+ * unpadded base64url, which is always exactly 43 characters. */
+export declare function isValidS256CodeChallenge(value: string): boolean;
+/** RFC 7636 code_verifier ABNF: 43–128 unreserved URI characters. */
+export declare function isValidPKCECodeVerifier(value: string): boolean;
+export type FrihetAccessProfile = "openai" | "full";
+/** Fail closed if a Worker deploy omits or mistypes its profile binding. */
+export declare function resolveFrihetAccessProfile(value: string | undefined): FrihetAccessProfile;
 /**
  * Byte-compatible extraction of the options previously inlined in the Worker.
  * index.ts spreads this object into the real OAuthProvider constructor.
@@ -16,7 +26,42 @@ export declare const OAUTH_PROVIDER_REVIEW_OPTIONS: {
     accessTokenTTL: number;
     refreshTokenTTL: number;
     allowPlainPKCE: false;
+    resourceMetadata: {
+        resource: string;
+        authorization_servers: string[];
+        scopes_supported: string[];
+        bearer_methods_supported: string[];
+        resource_name: string;
+    };
+};
+export type OAuthBoundaryError = "invalid_target" | "invalid_scope";
+export type OAuthBoundaryResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: OAuthBoundaryError;
+    description: string;
 };
+interface OAuthBoundaryParameters {
+    resource?: string | string[];
+    scope?: string | string[];
+    /** The authorization request creates the grant and must carry the canonical
+     * resource. Later token/refresh requests may omit it because the provider
+     * inherits the already-validated value stored on that grant. */
+    requireResource: boolean;
+    /** Authorization requests must include the advertised scope. Token refresh
+     * requests may omit it because the provider reuses the validated grant. */
+    requireScope: boolean;
+}
+/**
+ * Validate the two OAuth values that form the reviewed-host authorization
+ * boundary. RFC 8707 resource comparison is exact by design: accepting an
+ * arbitrary absolute URI would let a token minted by one Frihet Worker target
+ * the other Worker. Unknown or empty scopes are rejected instead of silently
+ * downscoping to an empty token.
+ */
+export declare function validateOAuthBoundary(parameters: OAuthBoundaryParameters, expectedResource: string): OAuthBoundaryResult;
+export declare function buildOpenAIUnauthorizedChallenge(origin?: string): string;
 /**
  * Materialize the public metadata generated by workers-oauth-provider 0.3.0
  * from the same options used by the Worker. The dependency version is pinned
@@ -42,10 +87,12 @@ export declare function buildOpenAIReviewOAuthContract(origin?: string): {
         authorization_servers: string[];
         scopes_supported: string[];
         bearer_methods_supported: string[];
+        resource_name: string;
     };
     wwwAuthenticate: {
         resourceMetadataUrl: string;
         missingTokenHeader: string;
     };
 };
+export {};
 //# sourceMappingURL=openai-review-oauth.d.ts.map

package/dist/openai-review-oauth.js

@@ -3,6 +3,25 @@
  * freeze gate. Values in this module are public protocol metadata, not secrets.
  */
 export const OPENAI_REVIEW_ORIGIN = "https://openai-mcp.frihet.io";
+export const FULL_MCP_ORIGIN = "https://mcp.frihet.io";
+export const FRIHET_CONNECTOR_SCOPE = "frihet:workspace.manage";
+/** RFC 7636 S256 challenges are the 32-byte SHA-256 digest encoded as
+ * unpadded base64url, which is always exactly 43 characters. */
+export function isValidS256CodeChallenge(value) {
+    return /^[A-Za-z0-9_-]{43}$/u.test(value);
+}
+/** RFC 7636 code_verifier ABNF: 43–128 unreserved URI characters. */
+export function isValidPKCECodeVerifier(value) {
+    return /^[A-Za-z0-9._~-]{43,128}$/u.test(value);
+}
+/** Fail closed if a Worker deploy omits or mistypes its profile binding. */
+export function resolveFrihetAccessProfile(value) {
+    if (value === "true")
+        return "openai";
+    if (value === "false")
+        return "full";
+    throw new Error("FRIHET_OPENAI_MODE must be explicitly set to true or false");
+}
 /**
  * Byte-compatible extraction of the options previously inlined in the Worker.
  * index.ts spreads this object into the real OAuthProvider constructor.
@@ -12,14 +31,65 @@ export const OAUTH_PROVIDER_REVIEW_OPTIONS = {
     authorizeEndpoint: "/authorize",
     tokenEndpoint: "/token",
     clientRegistrationEndpoint: "/register",
-    scopesSupported: ["read", "write"],
+    // This provider does not implement per-tool OAuth authorization. Advertise
+    // one honest connector-wide scope instead of implying that `read` prevents
+    // writes. Every mutating reviewed tool still requires confirm=true.
+    scopesSupported: [FRIHET_CONNECTOR_SCOPE],
     accessTokenTTL: 3600,
     refreshTokenTTL: 2592000,
     allowPlainPKCE: false,
+    resourceMetadata: {
+        resource: OPENAI_REVIEW_ORIGIN,
+        authorization_servers: [OPENAI_REVIEW_ORIGIN],
+        scopes_supported: [FRIHET_CONNECTOR_SCOPE],
+        bearer_methods_supported: ["header"],
+        resource_name: "Frihet ChatGPT connector",
+    },
 };
+/**
+ * Validate the two OAuth values that form the reviewed-host authorization
+ * boundary. RFC 8707 resource comparison is exact by design: accepting an
+ * arbitrary absolute URI would let a token minted by one Frihet Worker target
+ * the other Worker. Unknown or empty scopes are rejected instead of silently
+ * downscoping to an empty token.
+ */
+export function validateOAuthBoundary(parameters, expectedResource) {
+    if (parameters.resource === undefined && !parameters.requireResource) {
+        // The provider will inherit the exact resource stored on the grant.
+    }
+    else if (typeof parameters.resource !== "string"
+        || parameters.resource !== expectedResource) {
+        return {
+            ok: false,
+            error: "invalid_target",
+            description: "The OAuth resource must exactly match this Frihet MCP server.",
+        };
+    }
+    if (parameters.scope === undefined && !parameters.requireScope)
+        return { ok: true };
+    const scopes = Array.isArray(parameters.scope)
+        ? parameters.scope
+        : typeof parameters.scope === "string"
+            ? parameters.scope.split(/\s+/u).filter(Boolean)
+            : [];
+    if (scopes.length !== 1 || scopes[0] !== FRIHET_CONNECTOR_SCOPE) {
+        return {
+            ok: false,
+            error: "invalid_scope",
+            description: `The only supported OAuth scope is ${FRIHET_CONNECTOR_SCOPE}.`,
+        };
+    }
+    return { ok: true };
+}
 function endpoint(origin, path) {
     return new URL(path, new URL(origin).origin).toString();
 }
+export function buildOpenAIUnauthorizedChallenge(origin = OPENAI_REVIEW_ORIGIN) {
+    const resourceMetadataUrl = endpoint(new URL(origin).origin, "/.well-known/oauth-protected-resource");
+    return `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}", ` +
+        `scope="${FRIHET_CONNECTOR_SCOPE}", error="invalid_token", ` +
+        'error_description="Missing or invalid access token"';
+}
 /**
  * Materialize the public metadata generated by workers-oauth-provider 0.3.0
  * from the same options used by the Worker. The dependency version is pinned
@@ -55,11 +125,11 @@ export function buildOpenAIReviewOAuthContract(origin = OPENAI_REVIEW_ORIGIN) {
             authorization_servers: [normalizedOrigin],
             scopes_supported: [...OAUTH_PROVIDER_REVIEW_OPTIONS.scopesSupported],
             bearer_methods_supported: ["header"],
+            resource_name: OAUTH_PROVIDER_REVIEW_OPTIONS.resourceMetadata.resource_name,
         },
         wwwAuthenticate: {
             resourceMetadataUrl,
-            missingTokenHeader: `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}", ` +
-                'error="invalid_token", error_description="Missing or invalid access token"',
+            missingTokenHeader: buildOpenAIUnauthorizedChallenge(normalizedOrigin),
         },
     };
 }

package/dist/prompts/register-all.d.ts

@@ -6,5 +6,7 @@
  * using the available Frihet tools to complete each action.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Exact prompt registrations below; runtime capture gates this value. */
+export declare const MCP_PROMPT_COUNT = 10;
 export declare function registerAllPrompts(server: McpServer): void;
 //# sourceMappingURL=register-all.d.ts.map

package/dist/prompts/register-all.js

@@ -6,6 +6,8 @@
  * using the available Frihet tools to complete each action.
  */
 import { z } from "zod/v4";
+/** Exact prompt registrations below; runtime capture gates this value. */
+export const MCP_PROMPT_COUNT = 10;
 export function registerAllPrompts(server) {
     // -- monthly-close --
     server.registerPrompt("monthly-close", {

package/dist/public-capability-contract.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { type PublicCapabilityTruth } from "./capability-truth.js";
+export declare const PUBLIC_CAPABILITY_CONTRACT_VERSION = 2;
+export interface CompactPublicTool {
+    name: string;
+    annotations?: Record<string, boolean>;
+    capability?: PublicCapabilityTruth;
+}
+export interface CompactPublicSurface {
+    tools: CompactPublicTool[];
+    resources: string[];
+    prompts: string[];
+    discovery?: {
+        searchTools: CompactPublicTool;
+        describeTool: CompactPublicTool;
+    };
+}
+export interface PublicCapabilityContract {
+    contractVersion: number;
+    catalogue: {
+        canonicalOperations: number;
+        aliasNames: number;
+        discoveryNames: number;
+    };
+    surfaces: {
+        localFull: CompactPublicSurface;
+        remoteGrouped: CompactPublicSurface;
+        openaiFull: CompactPublicSurface;
+    };
+}
+export declare function capturePublicCapabilityContract(): Promise<PublicCapabilityContract>;
+export declare function serializePublicCapabilityContract(contract: PublicCapabilityContract): string;
+export declare function assertPublicCapabilityContract(actual: PublicCapabilityContract, expected: PublicCapabilityContract): void;
+//# sourceMappingURL=public-capability-contract.d.ts.map

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,16 @@
  */
 /** Sentinel left in place of a redacted value in cloned (tracing) payloads. */
 export declare const REDACTED = "[redacted]";
+/**
+ * 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,64 @@
  */
 /** Sentinel left in place of a redacted value in cloned (tracing) payloads. */
 export const REDACTED = "[redacted]";
+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 +82,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 +99,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) {

package/dist/resources/register-all.js

@@ -58,13 +58,13 @@ Endpoints:
   PATCH  /quotes/:id        — Update quote
   DELETE /quotes/:id        — Delete quote
 
-  GET    /webhooks          — List webhooks (paginated)
+  GET    /webhooks          — List webhooks (unpaginated)
   GET    /webhooks/:id      — Get webhook by ID
   POST   /webhooks          — Create webhook
   PATCH  /webhooks/:id      — Update webhook
   DELETE /webhooks/:id      — Delete webhook
 
-Pagination:
+Pagination (list families that expose limit/offset; webhooks are unpaginated):
   Query params: limit (1-100, default 50), offset (default 0)
   Response: { data: [...], total: number, limit: number, offset: number }
 
@@ -77,7 +77,7 @@ Error responses:
   500 — Internal server error
 
 Content-Type: application/json
-All monetary values in EUR (cents not used — decimal euros).
+Monetary values use the currency declared by each record; amounts are decimal major units.
 Dates in ISO 8601 format (YYYY-MM-DD or full datetime).`;
 const TAX_RATES = `Spanish Tax Rates by Fiscal Zone
 ================================
@@ -163,11 +163,6 @@ CANARY ISLANDS (IGIC instead of IVA)
   Modelo 425  — Annual IGIC summary (same deadline as Modelo 390)
   Filed with ATC (Administración Tributaria Canaria), NOT AEAT
 
-VERIFACTU (mandatory e-invoicing, phased rollout)
-  2026: Voluntary adoption
-  2027: Mandatory for large companies
-  2028: Mandatory for all businesses
-
 KEY DATES SUMMARY
   Apr 20 — Q1 filings
   Jul 20 — Q2 filings
@@ -382,8 +377,8 @@ const COUNTRIES = JSON.stringify([
 /* ------------------------------------------------------------------ */
 export function registerAllResources(server, client) {
     server.registerResource("api-schema", "frihet://api/schema", {
-        description: "OpenAPI schema summary: all endpoints, authentication method, rate limits, pagination, and error codes. " +
-            "/ Resumen del esquema OpenAPI: endpoints, autenticación, límites, paginación y errores.",
+        description: "Selected core REST endpoint summary with authentication, rate limits, pagination, and error codes. " +
+            "/ Resumen de endpoints REST principales, autenticación, límites, paginación y errores.",
         mimeType: "text/plain",
     }, async () => ({
         contents: [
@@ -410,8 +405,7 @@ export function registerAllResources(server, client) {
     }));
     server.registerResource("tax-calendar", "frihet://tax/calendar", {
         description: "Spanish quarterly tax calendar with filing deadlines for Modelo 303, 130, 390, 420 (IGIC), and annual returns. " +
-            "Includes VeriFactu e-invoicing timeline. " +
-            "/ Calendario fiscal trimestral español con plazos de presentación de modelos y VeriFactu.",
+            "/ Calendario fiscal trimestral español con plazos de presentación de modelos.",
         mimeType: "text/plain",
     }, async () => ({
         contents: [

package/dist/server-composition.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical registration path shared by the stdio server, remote Worker, and
+ * generated public-surface contract. Transport/auth setup stays with each host;
+ * the exposed MCP operations/resources/prompts are composed here exactly once.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IFrihetClient } from "./client-interface.js";
+export interface McpSurfaceComposition {
+    readonly openaiMode: boolean;
+    readonly groupedMode: boolean;
+    readonly includeDynamicResources: boolean;
+}
+export declare function localMcpSurfaceComposition(openaiMode: boolean, groupedMode: boolean): McpSurfaceComposition;
+export declare function remoteMcpSurfaceComposition(openaiMode: boolean, groupedMode: boolean): McpSurfaceComposition;
+export declare function registerMcpSurface(server: McpServer, client: IFrihetClient, options: McpSurfaceComposition): void;
+//# sourceMappingURL=server-composition.d.ts.map

package/dist/server-composition.js

@@ -0,0 +1,44 @@
+/**
+ * Canonical registration path shared by the stdio server, remote Worker, and
+ * generated public-surface contract. Transport/auth setup stays with each host;
+ * the exposed MCP operations/resources/prompts are composed here exactly once.
+ */
+import { applyPublicCapabilityTruth, buildLocalDiscoveryCapability, CAPABILITY_META_KEY, } from "./capability-truth.js";
+import { applyFiscalAliases } from "./fiscal-aliases.js";
+import { applyOpenAIProfile, applyOpenAIReviewProfiles, } from "./openai-profile.js";
+import { registerAllPrompts } from "./prompts/register-all.js";
+import { registerAllResources } from "./resources/register-all.js";
+import { applyToolExposureProfile } from "./tool-exposure.js";
+import { registerAllTools } from "./tools/register-all.js";
+export function localMcpSurfaceComposition(openaiMode, groupedMode) {
+    return { openaiMode, groupedMode, includeDynamicResources: true };
+}
+export function remoteMcpSurfaceComposition(openaiMode, groupedMode) {
+    return { openaiMode, groupedMode, includeDynamicResources: false };
+}
+export function registerMcpSurface(server, client, options) {
+    if (options.groupedMode) {
+        if (options.openaiMode) {
+            applyOpenAIReviewProfiles(server);
+        }
+        else {
+            applyToolExposureProfile(server, {
+                capabilityTruth: {
+                    metaKey: CAPABILITY_META_KEY,
+                    localDiscovery: buildLocalDiscoveryCapability,
+                },
+            });
+        }
+    }
+    else if (options.openaiMode) {
+        applyOpenAIProfile(server);
+    }
+    if (!options.openaiMode) {
+        applyPublicCapabilityTruth(server);
+    }
+    registerAllTools(server, client);
+    applyFiscalAliases(server);
+    registerAllResources(server, options.includeDynamicResources ? client : undefined);
+    registerAllPrompts(server);
+}
+//# sourceMappingURL=server-composition.js.map