feat(rest): consulta CPE OAuth + padrón RUC local

[Railly]

Summary

Adds two new SUNAT capabilities, both orthogonal to the SOAP CPE emission flow shipped in #1 and #2:

• sunat cpe consulta — validate any CPE (yours or vendor's) against SUNAT records via the official REST OAuth 2.0 API
• sunat padron — local mirror of the SUNAT Padrón Reducido del RUC (~370MB ZIP, 6.1M entries), no auth, instant lookups

Both verified end-to-end against real SUNAT infrastructure 2026-04-29.

What's in this PR

REST OAuth 2.0 client_credentials wrapper (src/sunat-rest/oauth.ts)

• Token fetch + in-process cache (refreshes 60s before SUNAT-reported expiry)
• Single callRestApi<T>() helper — auto-retries once on 401 with fresh token
• Two SUNAT host families: api-seguridad.sunat.gob.pe (token), api.sunat.gob.pe (ops)
• Reusable for upcoming GRE / SIRE PRs (same OAuth shape)

Consulta Integrada CPE (sunat cpe consulta)

export SUNAT_API_CLIENT_ID=...   # from SOL → Mi RUC → Credenciales API
export SUNAT_API_CLIENT_SECRET=...

sunat cpe consulta \
  --ruc-emisor 20131312955 --tipo 01 --serie F001 --numero 1234 \
  --fecha 2026-04-29 --monto 118

• POSTs to /v1/contribuyente/contribuyentes/{rucConsultante}/validarcomprobante
• Auto-converts ISO date → DD/MM/YYYY (SUNAT format)
• Maps cryptic codes to human descriptions: estadoCp (Aceptado/Anulado), estadoRuc (Activo/Baja), condDomiRuc (Habido/No Habido)
• Both raw codes and friendly descriptions in JSON output (agent-friendly)

Padrón Reducido del RUC local (sunat padron *)

sunat padron status                 # cache status + freshness
sunat padron sync [--force]         # 12s download, ~370MB ZIP → 1GB TXT
sunat padron ruc 20131312955        # ~1s streaming lookup
sunat padron batch --file rucs.csv  # one scan for N RUCs
echo "20131312955" | sunat padron batch

• 6.1M entries indexed by 11-char RUC prefix
• Streams raw bytes to disk (no encoding conversion in hot path) — was 12+ minutes when we tried UTF-8 conversion in flight, now 12s
• Pipe-separated TXT, ISO-8859-1 encoded, decoded only at lookup time
• 24h freshness check, --force to re-sync earlier
• No auth, no captcha, no third-party API, no dependency

Tests

209 pass / 2 skip / 0 fail in 2.6s (was 182)

New unit tests (27):
- oauth.test.ts (13) — token cache, 401 retry, query params, custom scope, error paths
- consulta-cpe.test.ts (6) — ISO→DD/MM/YYYY, body shape, code mappings, monto formatting
- padron-local.test.ts (8) — line parser, isStale (24h boundary), edge cases

Smoke tests

bun smoke:sunat   # Factura individual (PR #1)
bun smoke:boleta  # Boleta >= S/700 (PR #2)
bun smoke:padron  # NEW — downloads padrón + looks up SUNAT's own RUC

All three verified passing 2026-04-29.

Verified end-to-end

$ time bun run bin/sunat.ts -o json padron sync
{ synced: true, durationMs: 12306, zipSize: 385365406, entries: 6179818 }

$ time bun run bin/sunat.ts -o json padron ruc 20131312955
{
  "ruc": "20131312955",
  "found": true,
  "razonSocial": "SUPERINTENDENCIA NACIONAL DE ADUANAS Y DE ADMINISTRACION TRIBUTARIA - SUNAT",
  "estado": "ACTIVO",
  "condicion": "HABIDO",
  ...
}
real  0m1.155s

Out of scope (deliberately deferred)

Capability	Why	Path forward
Tipo de cambio	SUNAT + SBS portal endpoints both blocked by WAF (verified — both return "Request Rejected")	Future PR with --driver agent-browser (same pattern as RHE/F616)
Padrón RUC puntual via portal	Now requires numRnd token + reCAPTCHA on e-consultaruc.sunat.gob.pe	Local padrón is a strictly better answer for batch/scriptable use
GRE (Guía de Remisión REST)	Same OAuth shape — oauth.ts is reusable	Separate PR; minimal new code (UBL builder + 1 endpoint)
SIRE (RVIE/RCE)	Distinct host api-sire.sunat.gob.pe, mandatory monthly filing	High-value next PR — automates dolor mensual de contadores
sqlite index for padrón	Streaming lookup is 1s — good enough for now	Future PR if batch >1000 RUCs becomes common

Test plan

• bun test green (209/2 skip/0 fail)
• bun smoke:padron green (downloads + lookup verified)
• sunat cpe consulta --help parses correctly
• sunat padron status reports cache state
• sunat padron ruc 20131312955 returns SUNAT row in <2s
• CI green on push (will verify after PR opens)
• Reviewer to verify their SUNAT_API_CLIENT_ID/SECRET works for cpe consulta