fintecia 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# fintecia
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/Fintecia/fintecia-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Fintecia/fintecia-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-green.svg)](https://nodejs.org)
+
+Servidor MCP **local** de [Fintecia](https://fintecia.com.mx/?utm_source=mcp&utm_medium=referral&utm_campaign=fintecia_mcp&utm_content=readme) para agentes de IA
+(Claude, Cursor, ChatGPT, OpenCode y cualquier cliente MCP). Le da a tu agente acceso a
+tus facturas (CFDI), conciliación bancaria, riesgo fiscal (69-B / art. 69) y
+deducibilidad — descargando tus facturas directamente del SAT con tu **e-firma local**,
+que **nunca sale de tu máquina**.
+
+## Qué puede hacer tu agente
+
+- **Descargar CFDIs del SAT** (emitidos / recibidos) por periodo, con tu e-firma local.
+- **Consultar tus finanzas** ya calculadas por Fintecia (balances, impuestos, conciliación).
+- **Verificar el riesgo fiscal** de cualquier RFC (listas 69-B y art. 69) y el estatus de una factura.
+- **Evaluar la deducibilidad** de tus gastos, con la evidencia de cada veredicto.
+
+## Estado del proyecto
+
+Esta es una **primera versión (0.1.0)**. Lo disponible hoy:
+
+- ✅ Descarga de CFDI del SAT con e-firma local + materialización en Fintecia.
+- ✅ Consultas materializadas: `fintecia_financials` (estados NIF B-3/B-6),
+  `fintecia_tax_summary`, `fintecia_risk_report`/`_check`, `fintecia_deductibility`.
+- ✅ `fintecia_reconciliation` (estado de conciliación banco↔CFDI, **solo lectura**).
+
+**Pendiente (próximas versiones):**
+
+- ⏳ **Carga del PDF de estado de cuenta bancario** para conciliar contra CFDI
+  (la reconciliación hoy solo reporta datos ya importados; no acepta el PDF todavía).
+
+## Requisitos
+
+- **Node.js 20 o superior.**
+- **Cuenta de Fintecia** para las herramientas `fintecia_*` (login con Google).
+- **e-firma** (`.cer` + `.key` + contraseña) solo si querés descargar CFDIs del SAT.
+  Sin e-firma, las consultas públicas y las de tu cuenta siguen funcionando.
+
+## Instalación
+
+### 1. Instalar el servidor
+
+```bash
+npm install -g fintecia
+```
+
+Esto deja el binario **`fintecia-mcp`** en tu `PATH` (apuntando a `dist/index.js`,
+definido en `package.json` `bin`). No hace falta clonar el repo ni compilar.
+
+### 2. Registrar el servidor en tu cliente MCP
+
+Agregá una entrada `fintecia` apuntando al binario `fintecia-mcp`. En **Claude
+Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "fintecia": {
+      "command": "fintecia-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+**Cursor** usa el mismo formato en `.cursor/mcp.json`; otros clientes (OpenCode,
+Windsurf, etc.) aceptan una estructura equivalente. Consultá la documentación de tu
+cliente para la sintaxis exacta.
+
+### 3. Primer uso: login + e-firma
+
+1. Pedile a tu agente que ejecute la herramienta **`fintecia_login`**.
+2. Abrí en tu navegador la URL local que devuelve.
+3. Iniciá sesión con Google y cargá tu e-firma (`.cer` + `.key` + contraseña).
+4. Listo: tu agente queda autenticado y vinculado a tu RFC.
+
+## Herramientas
+
+### Públicas del SAT (sin cuenta, sin e-firma)
+
+| Herramienta | Qué hace |
+|---|---|
+| `sat_efos_check` | ¿Un RFC está en la lista 69-B (EFOS, operaciones presuntamente inexistentes)? |
+| `sat_debts_check` | ¿Un RFC tiene créditos fiscales firmes (art. 69)? |
+| `cfdi_verify` | Estatus de una factura (vigente / cancelado) + Validación EFOS. |
+
+### Descarga del SAT (e-firma local)
+
+| Herramienta | Qué hace |
+|---|---|
+| `fintecia_efirmas` | Lista las e-firmas registradas en esta máquina. |
+| `cfdi_download` | Descarga CFDIs del SAT por periodo (async → devuelve un `jobId`). |
+| `cfdi_download_status` | Consulta el estado de una descarga en curso. |
+| `cfdi_sync_status` | Qué tan al día está tu información local. |
+
+### Fintecia (requiere login)
+
+| Herramienta | Qué hace |
+|---|---|
+| `fintecia_profile` | Tu usuario y los contribuyentes a los que estás vinculado. |
+| `fintecia_financials` | Balances y razones materializados — usá esto para responder "cuánto". |
+| `fintecia_tax_summary` | Resumen de ISR/IVA por periodo. |
+| `fintecia_reconciliation` | Estado de la conciliación banco ↔ CFDI. |
+| `fintecia_transactions` | Ingresos/gastos (dato crudo, solo para inspección). |
+| `fintecia_cfdi` | Buscar / ver facturas (dato crudo, solo para inspección). |
+| `fintecia_risk_report` | Cruce de tus contrapartes contra las listas 69-B / 69. |
+| `fintecia_risk_check` | Ficha de riesgo de un proveedor (RFC puntual). |
+| `fintecia_deductibility` | Veredicto de deducibilidad por gasto, con evidencia. |
+
+> **El agente razona, Fintecia calcula.** Para responder "cuánto" usá siempre las
+> herramientas materializadas (`fintecia_financials`, `fintecia_tax_summary`); las
+> herramientas `_transactions` / `_cfdi` son solo para inspeccionar qué hay detrás de
+> un número, nunca para re-sumarlo.
+
+### Glosario de campos (estática, sin login)
+
+| Herramienta | Qué hace |
+|---|---|
+| `fintecia_glosario` | Diccionario de campos de las tools `fintecia_*` (money objects, NIF B-3/B-6, impuestos vs ISR prepagado, IVA en el balance). Estática y sin auth — devuelve el glosario para interpretar `fintecia_financials`. |
+
+## Seguridad y privacidad
+
+- Tu **e-firma nunca sale de tu máquina**: se guarda en el keychain del sistema
+  (macOS Keychain / Windows Credential Manager / Linux libsecret). Fintecia solo
+  recibe los CFDI.
+- El servidor es **local** (corre por stdio, en tu máquina) y **sin secretos**:
+  la autenticación es OAuth de *loopback* — tu navegador hace el login y el token
+  queda en memoria, no en disco.
+- Todo acceso a tus datos pasa por tu sesión autenticada.
+
+## Licencia
+
+MIT

package/dist/auth/firebaseConfig.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Firebase Web config (public). The MCP is a public client: these values are
+ * meant to be embedded (the Web API key is not a secret). Overridable via env
+ * for staging/local emulator.
+ *
+ * `FINTECIA_ENV` selects the backend environment. Unlike the Flutter app's
+ * `Env` (which defaults to "local" for dev), the MCP is distributed to end
+ * users, so it defaults to "production": when local, the onboarding page
+ * connects the Auth SDK to the Auth emulator at 127.0.0.1:9099 (same as
+ * `lib/main.dart` `useAuthEmulator`).
+ */
+export declare const FIREBASE_ENV: string;
+export declare const isLocal: boolean;
+export declare const AUTH_EMULATOR_URL: string;
+/**
+ * Fintecia backend base URL (no trailing slash), env-aware.
+ *
+ * The MCP talks to the backend over plain `fetch` (NOT the Firebase Functions
+ * SDK), so it must know the full base URL. `FINTECIA_API_URL` wins when set;
+ * otherwise the URL is derived from `FINTECIA_ENV`:
+ *   - local      → Hosting emulator (http://127.0.0.1:5000). The client calls
+ *                  `/api/v1/*` paths, which are Hosting rewrites (firebase.json);
+ *                  the Functions emulator (5001) serves functions BY NAME, so it
+ *                  does NOT serve the `/api/v1/*` rewrite paths.
+ *   - staging    → fintecia-staging.web.app
+ *   - production → app.fintecia.com.mx
+ *
+ * L22 bug: previously `FINTECIA_API_URL` was read raw with NO default, so a
+ * prod run failed with "uploadBaseUrl no configurado (definí FINTECIA_API_URL)".
+ */
+export declare function resolveApiBaseUrl(env: string, explicit?: string, localOverride?: string): string;
+export declare const API_BASE_URL: string;
+export declare const FIREBASE_WEB_CONFIG: {
+    apiKey: string;
+    authDomain: string;
+    projectId: string;
+    appId: string;
+    storageBucket: string;
+    messagingSenderId: string;
+};

package/dist/auth/firebaseConfig.js

@@ -0,0 +1,54 @@
+/**
+ * Firebase Web config (public). The MCP is a public client: these values are
+ * meant to be embedded (the Web API key is not a secret). Overridable via env
+ * for staging/local emulator.
+ *
+ * `FINTECIA_ENV` selects the backend environment. Unlike the Flutter app's
+ * `Env` (which defaults to "local" for dev), the MCP is distributed to end
+ * users, so it defaults to "production": when local, the onboarding page
+ * connects the Auth SDK to the Auth emulator at 127.0.0.1:9099 (same as
+ * `lib/main.dart` `useAuthEmulator`).
+ */
+export const FIREBASE_ENV = process.env.FINTECIA_ENV ?? 'production';
+export const isLocal = FIREBASE_ENV === 'local';
+export const AUTH_EMULATOR_URL = process.env.FIREBASE_AUTH_EMULATOR ?? 'http://127.0.0.1:9099';
+/**
+ * Fintecia backend base URL (no trailing slash), env-aware.
+ *
+ * The MCP talks to the backend over plain `fetch` (NOT the Firebase Functions
+ * SDK), so it must know the full base URL. `FINTECIA_API_URL` wins when set;
+ * otherwise the URL is derived from `FINTECIA_ENV`:
+ *   - local      → Hosting emulator (http://127.0.0.1:5000). The client calls
+ *                  `/api/v1/*` paths, which are Hosting rewrites (firebase.json);
+ *                  the Functions emulator (5001) serves functions BY NAME, so it
+ *                  does NOT serve the `/api/v1/*` rewrite paths.
+ *   - staging    → fintecia-staging.web.app
+ *   - production → app.fintecia.com.mx
+ *
+ * L22 bug: previously `FINTECIA_API_URL` was read raw with NO default, so a
+ * prod run failed with "uploadBaseUrl no configurado (definí FINTECIA_API_URL)".
+ */
+export function resolveApiBaseUrl(env, explicit, localOverride) {
+    const trimmed = explicit?.trim();
+    if (trimmed)
+        return trimmed.replace(/\/+$/, '');
+    switch (env) {
+        case 'local':
+            return (localOverride?.trim() ||
+                'http://127.0.0.1:5000');
+        case 'staging':
+            return 'https://fintecia-staging.web.app';
+        default: // production and any unknown value → prod (fail safe to the real API)
+            return 'https://app.fintecia.com.mx';
+    }
+}
+export const API_BASE_URL = resolveApiBaseUrl(FIREBASE_ENV, process.env.FINTECIA_API_URL, process.env.FINTECIA_LOCAL_API_URL);
+export const FIREBASE_WEB_CONFIG = {
+    apiKey: process.env.FIREBASE_API_KEY ?? 'AIzaSyAt1DR0jI8h9GqaPo8kaSwVNL_4Hb3IhL8',
+    authDomain: process.env.FIREBASE_AUTH_DOMAIN ?? 'app.fintecia.com.mx',
+    projectId: process.env.FIREBASE_PROJECT_ID ?? 'fintecia',
+    appId: process.env.FIREBASE_APP_ID ?? '1:608545925207:web:68758d816a6085dce39b12',
+    storageBucket: process.env.FIREBASE_STORAGE_BUCKET ?? 'fintecia.firebasestorage.app',
+    messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID ?? '608545925207',
+};
+//# sourceMappingURL=firebaseConfig.js.map

package/dist/auth/firebaseConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firebaseConfig.js","sourceRoot":"","sources":["../../src/auth/firebaseConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,YAAY,CAAC;AACrE,MAAM,CAAC,MAAM,OAAO,GAAG,YAAY,KAAK,OAAO,CAAC;AAChD,MAAM,CAAC,MAAM,iBAAiB,GAC5B,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,uBAAuB,CAAC;AAEhE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAW,EACX,QAAiB,EACjB,aAAsB;IAEtB,MAAM,OAAO,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC;IACjC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAChD,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,OAAO;YACV,OAAO,CACL,aAAa,EAAE,IAAI,EAAE;gBACrB,uBAAuB,CACxB,CAAC;QACJ,KAAK,SAAS;YACZ,OAAO,kCAAkC,CAAC;QAC5C,SAAS,sEAAsE;YAC7E,OAAO,6BAA6B,CAAC;IACzC,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,iBAAiB,CAC3C,YAAY,EACZ,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAC5B,OAAO,CAAC,GAAG,CAAC,sBAAsB,CACnC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,yCAAyC;IACjF,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,qBAAqB;IACrE,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,UAAU;IACxD,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,2CAA2C;IACjF,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,8BAA8B;IACpF,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,cAAc;CAC9E,CAAC"}

package/dist/auth/session.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Auth session (loopback OAuth result). The local web page performs the
+ * Firebase sign-in (Google + MFA) and POSTs the tokens to the local server,
+ * which stores them here for the process lifetime.
+ *
+ * In-memory only for now: the MCP is a stdio process that lives while the
+ * agent talks to it; the ID token is refreshed via the refresh token. Disk
+ * persistence of the refresh token (surviving MCP restarts) is a follow-up.
+ */
+export interface AuthSession {
+    idToken: string;
+    refreshToken: string;
+}
+export declare class SessionStore {
+    private session;
+    set(session: AuthSession): void;
+    get(): AuthSession | null;
+    clear(): void;
+    get idToken(): string | null;
+}

package/dist/auth/session.js

@@ -0,0 +1,25 @@
+/**
+ * Auth session (loopback OAuth result). The local web page performs the
+ * Firebase sign-in (Google + MFA) and POSTs the tokens to the local server,
+ * which stores them here for the process lifetime.
+ *
+ * In-memory only for now: the MCP is a stdio process that lives while the
+ * agent talks to it; the ID token is refreshed via the refresh token. Disk
+ * persistence of the refresh token (surviving MCP restarts) is a follow-up.
+ */
+export class SessionStore {
+    session = null;
+    set(session) {
+        this.session = session;
+    }
+    get() {
+        return this.session;
+    }
+    clear() {
+        this.session = null;
+    }
+    get idToken() {
+        return this.session?.idToken ?? null;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/auth/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/auth/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,OAAO,YAAY;IACf,OAAO,GAAuB,IAAI,CAAC;IAE3C,GAAG,CAAC,OAAoB;QACtB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC;IACvC,CAAC;CACF"}

package/dist/fiel/decode.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Decode a base64 file (sent by the browser) into the string format nodecfdi's
+ * `Fiel.create` expects. The browser reads the .cer/.key as base64 (binary-safe
+ * — `readAsDataURL`), unlike `readAsText` which corrupts DER binaries.
+ *
+ *   - PEM → the UTF-8 text as-is.
+ *   - DER cert → base64 (matches Fintecia's `cerContents` in ws-auth.ts).
+ *   - DER key  → latin1/binary string (matches `keyBinary` in ws-auth.ts).
+ */
+export declare function decodeFileForFiel(b64: string, kind: 'cert' | 'key'): string;

package/dist/fiel/decode.js

@@ -0,0 +1,17 @@
+/**
+ * Decode a base64 file (sent by the browser) into the string format nodecfdi's
+ * `Fiel.create` expects. The browser reads the .cer/.key as base64 (binary-safe
+ * — `readAsDataURL`), unlike `readAsText` which corrupts DER binaries.
+ *
+ *   - PEM → the UTF-8 text as-is.
+ *   - DER cert → base64 (matches Fintecia's `cerContents` in ws-auth.ts).
+ *   - DER key  → latin1/binary string (matches `keyBinary` in ws-auth.ts).
+ */
+export function decodeFileForFiel(b64, kind) {
+    const buf = Buffer.from(b64, 'base64');
+    const text = buf.toString('utf8');
+    if (text.includes('-----BEGIN'))
+        return text;
+    return kind === 'cert' ? buf.toString('base64') : buf.toString('latin1');
+}
+//# sourceMappingURL=decode.js.map

package/dist/fiel/decode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.js","sourceRoot":"","sources":["../../src/fiel/decode.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,IAAoB;IACjE,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC3E,CAAC"}

package/dist/fiel/fiel.d.ts

@@ -0,0 +1,35 @@
+import { Fiel } from "@nodecfdi/sat-ws-descarga-masiva";
+/**
+ * FIEL inspection — thin wrapper over nodecfdi's `Fiel` (the same library the
+ * Fintecia backend uses in `functions/src/sat/ws-auth.ts`).
+ *
+ * The RFC lives in the X.509 `x500UniqueIdentifier` (OID 2.5.4.45), NOT the CN.
+ * nodecfdi's `Fiel.create(...).getRfc()` extracts it consistently with Fintecia,
+ * so we do NOT re-implement certificate parsing here.
+ *
+ * The private key (`keyPem`) and password are never logged, never persisted
+ * (the password is re-entered per signing session), and never leave the machine.
+ */
+export interface FielInfo {
+    rfc: string;
+    serial: string;
+    pem: string;
+    /** Legal name (razón social / nombre) from the certificate's CN, if present. */
+    razonSocial: string | null;
+    isValid: boolean;
+}
+export interface InspectedFiel {
+    fiel: Fiel;
+    info: FielInfo;
+}
+/**
+ * Build a nodecfdi Fiel from cert + key + passPhrase and extract its public
+ * identity (RFC, serial). Throws when the FIEL is invalid or expired.
+ */
+/**
+ * Extract the holder's legal name (razón social / nombre) from the subject's
+ * CN. The RFC lives in `x500UniqueIdentifier` (OID 2.5.4.45), NOT the CN —
+ * the CN carries the name. Returns null when the CN is absent.
+ */
+export declare function extractRazonSocial(certPem: string): string | null;
+export declare function inspectFiel(certPem: string, keyPem: string, passPhrase: string): InspectedFiel;

package/dist/fiel/fiel.js

@@ -0,0 +1,39 @@
+import { X509Certificate } from "node:crypto";
+import { Fiel } from "@nodecfdi/sat-ws-descarga-masiva";
+/**
+ * Build a nodecfdi Fiel from cert + key + passPhrase and extract its public
+ * identity (RFC, serial). Throws when the FIEL is invalid or expired.
+ */
+/**
+ * Extract the holder's legal name (razón social / nombre) from the subject's
+ * CN. The RFC lives in `x500UniqueIdentifier` (OID 2.5.4.45), NOT the CN —
+ * the CN carries the name. Returns null when the CN is absent.
+ */
+export function extractRazonSocial(certPem) {
+    try {
+        const subject = new X509Certificate(certPem).subject;
+        const m = subject.match(/^CN=([^\n]+)/m);
+        return m ? m[1].trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function inspectFiel(certPem, keyPem, passPhrase) {
+    const fiel = Fiel.create(certPem, keyPem, passPhrase);
+    if (!fiel.isValid()) {
+        throw new Error("FIEL inválida o vencida");
+    }
+    const pem = fiel.getCertificatePemContents();
+    return {
+        fiel,
+        info: {
+            rfc: fiel.getRfc(),
+            serial: fiel.getCertificateSerial(),
+            pem,
+            razonSocial: extractRazonSocial(pem),
+            isValid: true,
+        },
+    };
+}
+//# sourceMappingURL=fiel.js.map

package/dist/fiel/fiel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fiel.js","sourceRoot":"","sources":["../../src/fiel/fiel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,kCAAkC,CAAC;AA4BxD;;;GAGG;AACH;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC;QACrD,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QACzC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,MAAc,EACd,UAAkB;IAElB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAEtD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,yBAAyB,EAAE,CAAC;IAE7C,OAAO;QACL,IAAI;QACJ,IAAI,EAAE;YACJ,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE;YAClB,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE;YACnC,GAAG;YACH,WAAW,EAAE,kBAAkB,CAAC,GAAG,CAAC;YACpC,OAAO,EAAE,IAAI;SACd;KACF,CAAC;AACJ,CAAC"}

package/dist/fiel/store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * FIEL storage — multi-taxpayer, keyed by RFC.
+ *
+ * Security model (S2): the .key is the private material and NEVER leaves the
+ * machine nor is logged. The stored `.key` PEM is already password-encrypted
+ * with the user's FIEL password; the password itself is held ONLY in the OS
+ * keychain (never in the file store, never logged, never uploaded). The .cer
+ * is public.
+ *
+ * FileFielStore is the cross-platform base and the Linux fallback. The OS
+ * keychain (macOS Keychain / Windows DPAPI / Linux libsecret) is a follow-up
+ * refinement behind the same FielStore port (T1b).
+ */
+export interface FielCredentials {
+    rfc: string;
+    certPem: string;
+    keyPem: string;
+}
+export interface FielStore {
+    store(fiel: FielCredentials): Promise<void>;
+    load(rfc: string): Promise<FielCredentials | null>;
+    list(): Promise<string[]>;
+    remove(rfc: string): Promise<void>;
+}
+export declare class FileFielStore implements FielStore {
+    private readonly baseDir;
+    constructor(baseDir?: string);
+    private dirFor;
+    store(fiel: FielCredentials): Promise<void>;
+    load(rfc: string): Promise<FielCredentials | null>;
+    list(): Promise<string[]>;
+    remove(rfc: string): Promise<void>;
+}

package/dist/fiel/store.js

@@ -0,0 +1,61 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const CERT_FILE = "certificate.cer";
+const KEY_FILE = "private.key";
+function sanitizeRfc(rfc) {
+    // RFC is alphanumeric; defensive guard against path traversal.
+    if (!/^[A-ZÑ&0-9]{12,13}$/.test(rfc)) {
+        throw new Error(`invalid RFC for storage: ${rfc}`);
+    }
+    return rfc;
+}
+export class FileFielStore {
+    baseDir;
+    constructor(baseDir = defaultBaseDir()) {
+        this.baseDir = baseDir;
+    }
+    dirFor(rfc) {
+        return path.join(this.baseDir, sanitizeRfc(rfc));
+    }
+    async store(fiel) {
+        const dir = this.dirFor(fiel.rfc);
+        await fs.mkdir(dir, { recursive: true });
+        // 0600: owner-only — the .key must not be world-readable.
+        await fs.writeFile(path.join(dir, CERT_FILE), fiel.certPem, { mode: 0o600 });
+        await fs.writeFile(path.join(dir, KEY_FILE), fiel.keyPem, { mode: 0o600 });
+    }
+    async load(rfc) {
+        const dir = this.dirFor(rfc);
+        try {
+            const [certPem, keyPem] = await Promise.all([
+                fs.readFile(path.join(dir, CERT_FILE), "utf8"),
+                fs.readFile(path.join(dir, KEY_FILE), "utf8"),
+            ]);
+            return { rfc, certPem, keyPem };
+        }
+        catch {
+            return null;
+        }
+    }
+    async list() {
+        try {
+            const entries = await fs.readdir(this.baseDir, { withFileTypes: true });
+            return entries
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name)
+                .filter((name) => /^[A-ZÑ&0-9]{12,13}$/.test(name))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    async remove(rfc) {
+        await fs.rm(this.dirFor(rfc), { recursive: true, force: true });
+    }
+}
+function defaultBaseDir() {
+    return path.join(os.homedir(), ".fintecia", "fiel");
+}
+//# sourceMappingURL=store.js.map

package/dist/fiel/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/fiel/store.ts"],"names":[],"mappings":"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"}

package/dist/fin/read.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Read client for the Fintecia MCP read endpoints. The MCP queries the
+ * backend for MATERIALIZED data (the backend computes; the client reads).
+ * Each call is `POST /api/v1/mcp/<resource>` with `{ taxpayerRfc, ... }` and
+ * a Bearer ID token from the loopback session.
+ */
+export interface ReadClientConfig {
+    baseUrl: string;
+    getAuthToken: () => Promise<string | null>;
+    fetchFn?: typeof fetch;
+}
+export declare class ReadClient {
+    private readonly config;
+    constructor(config: ReadClientConfig);
+    private fetch;
+    read(path: string, taxpayerRfc: string, extra?: Record<string, unknown>): Promise<unknown>;
+    /** Read an endpoint that needs NO taxpayerRfc (e.g. profile, by uid). */
+    readRaw(path: string): Promise<unknown>;
+}

package/dist/fin/read.js

@@ -0,0 +1,54 @@
+/**
+ * Read client for the Fintecia MCP read endpoints. The MCP queries the
+ * backend for MATERIALIZED data (the backend computes; the client reads).
+ * Each call is `POST /api/v1/mcp/<resource>` with `{ taxpayerRfc, ... }` and
+ * a Bearer ID token from the loopback session.
+ */
+export class ReadClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    fetch(input, init) {
+        const fn = this.config.fetchFn ?? fetch;
+        return fn(input, init);
+    }
+    async read(path, taxpayerRfc, extra = {}) {
+        const idToken = await this.config.getAuthToken();
+        if (!idToken) {
+            throw new Error("no autenticado (fintecia_login)");
+        }
+        const res = await this.fetch(`${this.config.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${idToken}`,
+            },
+            body: JSON.stringify({ taxpayerRfc, ...extra }),
+        });
+        if (!res.ok) {
+            throw new Error(`read ${path} failed: ${res.status}`);
+        }
+        return res.json();
+    }
+    /** Read an endpoint that needs NO taxpayerRfc (e.g. profile, by uid). */
+    async readRaw(path) {
+        const idToken = await this.config.getAuthToken();
+        if (!idToken) {
+            throw new Error("no autenticado (fintecia_login)");
+        }
+        const res = await this.fetch(`${this.config.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${idToken}`,
+            },
+            body: JSON.stringify({}),
+        });
+        if (!res.ok) {
+            throw new Error(`read ${path} failed: ${res.status}`);
+        }
+        return res.json();
+    }
+}
+//# sourceMappingURL=read.js.map

package/dist/fin/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../src/fin/read.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,OAAO,UAAU;IACQ;IAA7B,YAA6B,MAAwB;QAAxB,WAAM,GAAN,MAAM,CAAkB;IAAG,CAAC;IAEjD,KAAK,CAAC,KAAa,EAAE,IAAkB;QAC7C,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,KAAK,CAAC;QACxC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,IAAI,CACR,IAAY,EACZ,WAAmB,EACnB,QAAiC,EAAE;QAEnC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QACjD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YAC5D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,OAAO,EAAE;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,GAAG,KAAK,EAAE,CAAC;SAChD,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,YAAY,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QACjD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YAC5D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,OAAO,EAAE;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;SACzB,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,YAAY,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/glossary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Field glossary for the Fintecia MCP tools.
+ *
+ * The agent cannot reliably deduce accounting-semantics fields (taxes vs
+ * prepaid ISR, IVA acreditable vs trasladado, preTaxIncome vs netIncome),
+ * so this dictionary documents them. It is served by the static
+ * `fintecia_glosario` tool — no auth, no backend round-trip — so the agent
+ * can load it during onboarding, in parallel with login + e-firma.
+ */
+export interface GlossaryEntry {
+    /** "summary" | "incomeStatement" | "balanceSheet" | "principio" */
+    section: string;
+    key: string;
+    /** Short meaning in the domain language (neutral Spanish). */
+    meaning: string;
+}
+export declare const FINANCIALS_GLOSSARY: GlossaryEntry[];