fix(entitlements): gate paid AI document OCR server-side (free-tier leak) (#852)

* fix(entitlements): gate paid AI document OCR server-side (free-tier leak)

Free/manual-tier companies could trigger paid Bedrock OCR (extractInvoiceFields)
with no `ai` capability check, on every transport:
- invoice-inbox HTTP paths — /upload + email /inbound (shared uploadAndExtract),
  /items/:id/attach-document, /items/:id/retry-extraction (4 call sites, zero
  capability refs);
- the gnubok_upload_document MCP tool — absent from MCP_TOOL_CAPABILITY_MAP, so a
  free-tier API key (incl. the claude.ai connector's minted gnubok_sk_ key) got
  unlimited AI extraction. This disproved the keys.ts "no MCP tool invokes AI"
  comment.

Fix (money-blocker for the free/paid tier cutover):
- Gate the 3 inbox call sites on hasCapability(CAPABILITY.ai). Upload + attach
  degrade gracefully (document still stored; extraction skipped with reason
  `no_ai_entitlement`, highest priority in the existing skipReason chain). Retry
  is an explicit "run AI now" action, so it hard-blocks with 403
  capabilityBlockedResponse.
- Register gnubok_upload_document -> CAPABILITY.ai in MCP_TOOL_CAPABILITY_MAP; the
  dispatcher already enforces the map. Correct the stale keys.ts comment and the
  misleading "deterministic field extraction" tool description + manifest copy
  (the extension migrated regex -> AI OCR).

Tests: no-AI upload/attach skip + retry 403 (sandbox-skip-extraction), retry 403
(retry-extraction), and the MCP map contract + refined dispatch<->commit parity
(capability-maps: upload_document is dispatch-only, no commit counterpart).

Self-hosted stays all-on (hasCapability short-circuits). No migration.
Follow-up (not in scope): capability-blind DashboardNav (free/paid rails identical)
and /chat gated on isVerified not `ai` — see dev_docs/nav_ia_redesign.md Part 4.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(mcp): assert gnubok_upload_document is ai-gated at dispatch

The gnubok_upload_document handler runs extractInvoiceFields (Bedrock OCR)
inline rather than through the entitlement-gated uploadAndExtract, so the
central MCP_TOOL_CAPABILITY_MAP dispatch check is the only paywall on that
transport. Lock it with a test (flagged by PR review as an untested money
path) so a free-tier connector key can never reach paid OCR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lib/entitlements/__tests__/capability-maps.test.ts

@@ -12,12 +12,22 @@ import {
  * external-service tool silently bypassing the paywall — mirrors the
  * TOOL_SCOPE_MAP assertions in the mcp-server tests.
  */
+/**
+ * MCP tools that invoke a paid capability directly (no stage→commit round-trip),
+ * so they are gated at DISPATCH only and have no commit-time (operation-map)
+ * counterpart. gnubok_upload_document runs Bedrock OCR inline via
+ * extractInvoiceFields — it never stages a pending_operation.
+ */
+const DISPATCH_ONLY_MCP_TOOLS = new Set<string>(['gnubok_upload_document'])
+
 describe('MCP_TOOL_CAPABILITY_MAP', () => {
-  it('gates exactly the three paid external-service MCP tools', () => {
+  it('gates exactly the paid MCP tools (3 external-service staging tools + the AI OCR tool)', () => {
     expect(MCP_TOOL_CAPABILITY_MAP).toEqual({
       gnubok_send_invoice: CAPABILITY.email_send,
       gnubok_vat_declaration_submit: CAPABILITY.skatteverket,
       gnubok_agi_submit: CAPABILITY.skatteverket,
+      // Dispatch-only AI tool — inline Bedrock OCR, no staged operation.
+      gnubok_upload_document: CAPABILITY.ai,
     })
   })
 
@@ -43,9 +53,15 @@ describe('PAID_OPERATION_CAPABILITY_MAP', () => {
     }
   })
 
-  it('covers the same set of capabilities as the MCP tool map (dispatch ↔ commit parity)', () => {
-    expect(new Set(Object.values(PAID_OPERATION_CAPABILITY_MAP))).toEqual(
-      new Set(Object.values(MCP_TOOL_CAPABILITY_MAP)),
+  it('covers the same capabilities as the STAGING MCP tools (dispatch ↔ commit parity)', () => {
+    // Parity applies to staging tools only: an op that can be staged via MCP OR
+    // approved in the UI must be gated on both transports. Dispatch-only tools
+    // (inline AI OCR) have no commit counterpart and are excluded.
+    const stagingMcpCaps = new Set(
+      Object.entries(MCP_TOOL_CAPABILITY_MAP)
+        .filter(([tool]) => !DISPATCH_ONLY_MCP_TOOLS.has(tool))
+        .map(([, cap]) => cap),
     )
+    expect(new Set(Object.values(PAID_OPERATION_CAPABILITY_MAP))).toEqual(stagingMcpCaps)
   })
 })

lib/entitlements/keys.ts

@@ -57,18 +57,23 @@ export const PAID_CAPABILITIES: readonly CapabilityKey[] = [
 /**
  * Paid MCP tools → required capability. The MCP/agent path is a paid chokepoint
  * just like the HTTP routes, so the dispatcher gates these the same way it gates
- * API-key scope (see mcp-server `tools/call`). Only external-service WRITE tools
+ * API-key scope (see mcp-server `tools/call`). External-service WRITE tools
  * appear here: send_invoice (email) and the two Skatteverket submissions. The
  * read/local SKV tools (generate_agi, vat_declaration_validate/status, agi_status)
  * stay free — the §4 carve-out forbids blocking a statutory filing obligation.
  *
- * No MCP tool invokes AI or triggers bank sync, so those PAID capabilities have
- * no entry here — they are reachable only via already-gated HTTP routes/handlers.
+ * gnubok_upload_document invokes AI (Bedrock document OCR via
+ * extractInvoiceFields), so it is gated on CAPABILITY.ai — the same paywall the
+ * HTTP inbox upload/attach/retry paths enforce. Without this entry a free-tier
+ * API key (incl. the claude.ai connector's minted gnubok_sk_ key) could trigger
+ * paid AI extraction. bank_sync has no MCP tool (bank sync is cron/HTTP only).
  */
 export const MCP_TOOL_CAPABILITY_MAP: Readonly<Partial<Record<string, CapabilityKey>>> = {
   gnubok_send_invoice: CAPABILITY.email_send,
   gnubok_vat_declaration_submit: CAPABILITY.skatteverket,
   gnubok_agi_submit: CAPABILITY.skatteverket,
+  // AI document OCR (Bedrock) — the inbox's paid extraction, reachable via MCP.
+  gnubok_upload_document: CAPABILITY.ai,
 } as const
 
 /**

lib/extensions/_generated/sector-definitions.ts

@@ -98,7 +98,7 @@ export const EXTENSION_DEFINITIONS: Record<string, ExtensionDefinition[]> = {
           "icon": "Inbox",
           "dataPattern": "both",
           "description": "Vidarebefordra leverantörsfakturor till en unik adress – dokumenten landar här med extraherade fält",
-          "longDescription": "Varje bolag får en unik fakturainkorg-adress. Fakturor som skickas dit fångas automatiskt och fält som org.nr, OCR, bankgiro, belopp och förfallodatum extraheras deterministiskt från PDF-texten. Inga AI-anrop, inga molntjänster utöver Resend för e-postmottagning.",
+          "longDescription": "Varje bolag får en unik fakturainkorg-adress. Fakturor som skickas dit fångas automatiskt och fält som org.nr, OCR, bankgiro, belopp och förfallodatum läses av med AI (kräver AI-funktionen). Utan AI lagras dokumentet ändå och fälten fylls i manuellt.",
           "readsCoreTables": [
                 "document_attachments",
                 "suppliers"