PSA/ee/docs/plans/2026-06-08-hudu-integration/SCRATCHPAD.md

# SCRATCHPAD — Hudu Integration

Rolling working memory. Append freely.

## Context

- Branch: `integrations_hudu`. Greenfield — zero "hudu" references in repo at start.
- Goal: pull-only (Hudu → AlgaPSA) integration, EE-only, gated behind `hudu-integration` feature flag.
- Hudu = MSP IT-documentation platform. REST JSON API. Auth = `x-api-key` header + per-instance base URL (NOT OAuth).
- Local reference skills (not committed; `.claude/` is gitignored): `hudu-api-patterns`, `hudu-companies`, `hudu-assets`, `hudu-articles`, `hudu-passwords`, `hudu-websites`.

## Hudu API facts (from reference skills)

- Base URL: `https://<instance>/api/v1/<resource>`; Hudu Cloud or self-hosted.
- Pagination: `?page=N`, fixed 25 items/page; page < 25 results ⇒ last page.
- Rate limit: 300 req/min; 429 ⇒ backoff (`Retry-After` + jitter / exponential).
- UI→API naming traps: Passwords→`asset_passwords`, Processes→`procedures`.
- `id_in_integration` / `integration_slug` on companies = PSA cross-link hook.
- Asset passwords API returns **plaintext** password values. API-key password access is a per-key permission (403 if denied).

## AlgaPSA architecture findings (from repo exploration)

### Integration framework
- EE integration libs: `ee/server/src/lib/integrations/<provider>/` (ninjaone, entra, tanium). Axios clients.
- Canonical client example: `ee/server/src/lib/integrations/ninjaone/ninjaOneClient.ts` (credential layering: tenant secret → app secret → env).
- Settings catalog (renders Settings→Integrations): `packages/integrations/src/components/settings/integrations/IntegrationsSettingsPage.tsx` — `categories` array of `IntegrationItem { id, name, description, component, isEE? }`. Add a new "IT Documentation" category (don't shoehorn into RMM — Hudu is docs, not RMM).
- RMM provider registry (pattern ref only): `packages/integrations/src/lib/rmm/providerRegistry.ts`.

### Feature flags
- Server: `featureFlags.isEnabled('hudu-integration', { userId, tenantId })`. Guard pattern: `ee/server/src/app/api/integrations/entra/_guards.ts` (`requireEntraUiFlagEnabled`).
- Client: `useFeatureFlag('hudu-integration', { defaultValue: false })`.

### CE/EE stub
- CE route lazy-imports EE via `@enterprise/...` alias, else returns `eeUnavailable()` 501.
- Example: `server/src/app/api/integrations/entra/route.ts` + `_ceStub.ts`. Simple re-export variant: `server/src/app/api/integrations/ninjaone/callback/route.ts`.
- tsconfig aliases (`tsconfig.base.json`): `@enterprise`→`packages/ee/src`, `@ee`→`packages/ee/src`. EDITION env: `isEnterpriseEdition = EDITION==='ee' || NEXT_PUBLIC_EDITION==='enterprise'`.

### Secrets
- `ISecretProvider`: `getAppSecret`, `getTenantSecret(tenantId,name)`, `setTenantSecret(tenantId,name,value|null)`, `deleteTenantSecret`.
- Get instance: `getSecretProviderInstance()`. Store Hudu creds as `hudu_api_key`, `hudu_base_url` (per tenant). NinjaOne stores JSON blob under one key — viable too.
- Metadata layer: `tenant_secrets` table + `createTenantSecretProvider(knex, tenantId)`. Perms: `secrets.view/manage/use`.

### Server actions & DB
- Server actions: `'use server'` + `withAuth(async (user, { tenant }, args) => ...)` + `createTenantKnex()`.
- Migrations: CE in `server/migrations/*.cjs`, EE in `ee/server/migrations/*.cjs` (Knex CJS). Tenant tables: PK `(tenant uuid, <id> uuid)`, FKs `(tenant, ref)`, `updated_at` trigger `on_update_timestamp()`, Citus-distributed by `tenant`. App-layer isolation (no RLS).
- Connection-state shape precedent: `server/migrations/20251124000001_create_rmm_integration_tables.cjs` → `rmm_integrations (tenant, integration_id, provider, instance_url, is_active, connected_at, last_sync_at, settings jsonb)`. **BUT location**: `rmm_integrations` is CE only because the RMM layer is partly CE; Hudu is wholly EE, so `hudu_integrations` goes in **`ee/server/migrations/`** (exists, 49 migrations, Citus-distributes EE-only tables). EE precedent to mirror: `ee/server/migrations/20260220143000_create_entra_phase1_schema.cjs` (Entra = EE-only, flag-gated, connection-state — the true peer). CE route 501s before any DB access, so CE never needs the table.
- Generic mapping table: `external_entity_mappings (tenant, ..., asset_id NOT NULL, import_source_id, external_id, external_hash, metadata)` — **asset-scoped only**, so NOT reusable for company↔client. Need dedicated Hudu mapping table(s).

### Entity mapping targets
| Hudu | Alga table | Interface |
|---|---|---|
| Company | `clients` | `IClient` (`client_id`, `client_name`, `properties` jsonb) |
| Contact | `contact_names` | `IContact` |
| Asset | `assets` (+ `asset_facts` for synced metadata) | `Asset`, `AssetFact` (`provider`, `integration_id`, `namespace`, `fact_key`) |
| Article | `documents` (polymorphic via `document_associations (tenant, document_id, entity_id, entity_type)`) | `IDocument` |
| Asset Password | **no native table** | — |
| Website | none (lives in `clients.properties`) | — DEFERRED |

### Asset Passwords placeholder (KEY)
- `packages/assets/src/components/tabs/DocumentsPasswordsTab.tsx`: passwords half is a STUB — card titled "Passwords & Secrets", text "Secure password management coming soon." No DB table, no persistence.
- Tab registered in `packages/assets/src/components/AssetDetailTabs.tsx` (id `documents-passwords`, icon Lock), rendered by `AssetDetailView.tsx`.
- Documents already attach to assets (real) via `document_associations` (entity_type='asset'); see `packages/assets/src/components/AssetDocuments.tsx`.
- NOTE scope mismatch: Hudu `asset_passwords` are **company-scoped**, but the placeholder tab is on the **asset**. Resolve where company-scoped Hudu creds surface.

## Hard constraints / decisions

- **SECURITY: never store Hudu password plaintext in an Alga DB column.** Live-fetch + mask + reveal-on-demand; if persistence ever needed, encrypt via `secretProvider` only. Respect API-key password permission (handle 403). Audit reveals.
- Data model kept **direction-agnostic** (external-id mapping tables) so push (Alga→Hudu) is additive later.
- Websites + push = out of scope for Phase 1.
- **EE/CE deletion boundary (NFR7)**: `hudu_integrations` is EE-only → all its DELETEs (disconnect + client/tenant cascade) live in EE code + EE migrations; CE must never name the table. Mapping cleanup is fine in CE (shared `tenant_external_entity_mappings`). User flagged: don't let a CE path try to delete from an EE-only table.
- Vault confirmed as tenant-secret backend: `packages/core/src/lib/secrets/VaultSecretProvider.ts` + `CompositeSecretProvider` (read-chain/write-target). So `setTenantSecret` can persist to Vault (encrypted store, NOT a DB column).

## Decisions (resolved 2026-06-08, evidence-based)

Research thread A (Hudu ecosystem) + thread B (repo mapping patterns) drove these:

1. **Sync model → persist mappings only; fetch a mapped company's lists on demand (cached + manual Refresh); deep-link for content.** No scheduled sync engine in Phase 1. Rationale: Hudu has NO consumer webhooks (only Slack/Teams alerts), 300 req/min, 25/page, no bulk endpoints; the whole ecosystem polls low-frequency (Hudu PSA syncs 3h, CIPP 24h) — per-mapped-company on-demand is within limits; bulk-on-every-view is not.
2. **Assets/Articles/Passwords → reference + deep-link, do NOT import as native Alga records.** Hudu is the system of record; PSAs deep-link back (ConnectWise "Quick Links"); pulling Hudu assets into a PSA is an unfilled HaloPSA request. Passwords especially: never duplicate secrets.
3. **Surface point → CLIENT page only** (revised 2026-06-09): Client "Hudu" tab (assets + articles) + a SEPARATE Client "Passwords" tab (Hudu asset_passwords), shown only when Hudu enabled/connected + client mapped. NOT on the asset tab — Hudu passwords are company-scoped, can't map to an asset; the asset "Documents & Passwords" stub is left untouched (future native-password effort).
4. **Company↔Client matching → reuse generic `tenant_external_entity_mappings`** (Xero/QBO modern shared table; `integration_type='hudu'`, `alga_entity_type='client'`) with **NinjaOne `OrganizationMappingManager` single-table UX**. Auto-suggest by `id_in_integration` (exact) → exact name → fuzzy name, admin confirms/overrides. NO new mapping migration.

### Key Hudu API facts confirmed by research
- PSA is source of truth for companies; Hudu imports them and stamps `id_in_integration` + `integration_slug`. Query filter `?id_in_integration=` + deep-link `/api/v1/companies/jump?integration_id=&integration_slug=&integration_type=company` exist (shipped v2.1.1+).
- No external webhooks/change-feed (only admin Slack/Teams alerts on create/update/delete). 300 req/min, 25/page, ~90 polling GET endpoints, no bulk read.
- Reveal passwords via deep-link to Hudu (Phase 1) → zero secret transit through Alga, satisfies no-plaintext constraint.
- Caveat: support.hudu.com returns 403 to fetchers; claims corroborated via hudu.com, Canny, community, and lwhitelock/HuduAPI.

### Repo mapping pattern confirmed
- Shared generic table: `server/migrations/20250502173321_create_tenant_external_entity_mappings.cjs` + CRUD `packages/integrations/src/actions/externalMappingActions.ts` (publishes EXTERNAL_MAPPING_CHANGED, 30s cache, 23505→"already exists"). REUSE — no new migration.
- NinjaOne org-mapping UI: `ee/server/src/components/settings/integrations/ninjaone/OrganizationMappingManager.tsx` (ClientPicker per row, status badges, Refresh) — copy this UX.
- Entra matchers (`ee/server/src/lib/integrations/entra/mapping/matchers/`) return 0–1 confidence — pattern for the auto-suggest.

### Password model — RESOLVED 2026-06-09
- **On-demand reveal, NO storage.** List shows metadata only; reveal = single live GET of one asset_password, value transits to the browser (masked, reveal-on-click), audited, never persisted to DB/Vault/cache or logged. Satisfies the no-plaintext constraint by construction.
- Vault IS the tenant-secret backend (`VaultSecretProvider`), so a Vault-cached reveal was technically allowed — rejected to avoid secret duplication/staleness/blast-radius and bypassing Hudu's own access revocation.
- **Native AlgaPSA password store + importing Hudu into it = OUT OF SCOPE** (separate future plan, "if demanded"). User confirmed 2026-06-09.
- Plan threads: F067 (reveal action), F068 (audit), F073/F082 (inline Reveal UI), T067–T069/T082/T110 (incl. "never to Vault"); NFR1 + Non-goals + OQ1 updated.

### OQ2/3/4 — RESOLVED 2026-06-09
- **OQ2**: passwords → dedicated Client "Passwords" tab (company-scoped); NOT asset tab; asset stub untouched. Plan group renamed `asset-passwords-tab` → `client-passwords-tab` (F080–F083, T080–T083); removed Hudu-tab passwords section (old F073/T072).
- **OQ3**: reuse existing **`system_settings`** resource (`read`=view, `update`=manage). Evidence: Entra/Teams/Tactical-RMM/SSO all use `system_settings`; only billing/accounting (Xero/QBO + `externalMappingActions`) use `billing_settings`. So Hudu mapping actions write `tenant_external_entity_mappings` directly gated on `system_settings` — do NOT call the `billing_settings`-gated `externalMappingActions` wrappers. Dropped the new-`hudu`-resource + seeding (old F091/T092 removed).
- **OQ4**: one instance per tenant (`unique(tenant)`). Multiple is rare (M&A/sandbox); deferred.

### Still-open (none — all OQs resolved)
- OQ2 asset↔password relation is best-effort/company-scoped (Hudu passwords aren't strongly asset-linked).
- OQ3 new `hudu` RBAC resource vs reuse (default: new `hudu` resource, seed rows).
- OQ4 one Hudu instance per tenant in Phase 1 (confirm).

## Reference plan (house style)

- `ee/docs/plans/2026-04-06-tanium-rmm-integration-plan/` — closest analog (EE, pull-oriented RMM). Note: its features.json predates commitGroup; THIS plan WILL include `commitGroup` per software-planner spec.

## Implementation log

### `scaffold` (F001–F005) — DONE + verified 2026-06-09 (uncommitted)
CE↔EE wiring pattern (reuse for ALL later route/lib groups):
- `@enterprise` alias is edition-swapped in `server/next.config.mjs:319-320`: EE → `ee/server/src`, CE → `packages/ee/src`. (`server/tsconfig.json` statically points `@enterprise` at `packages/ee/src` for typecheck.)
- So every EE route needs TWO files: the REAL impl at `ee/server/src/app/api/integrations/hudu/<route>` and a 501 stub copy at `packages/ee/src/app/api/integrations/hudu/<route>`. The CE entry at `server/src/app/api/integrations/hudu/<route>` lazy-imports `@enterprise/app/api/integrations/hudu/<route>` guarded by `isEnterpriseEdition` + `assertSessionProductAccess`, else `eeUnavailable()` 501.
- Files created: EE lib `ee/server/src/lib/integrations/hudu/{contracts.ts,index.ts}`; EE route `ee/server/src/app/api/integrations/hudu/{_guards.ts,_responses.ts,route.ts}`; EE stub `packages/ee/src/app/api/integrations/hudu/{_stub.ts,route.ts}`; CE entry `server/src/app/api/integrations/hudu/{_ceStub.ts,route.ts}`; client gate `packages/integrations/src/components/settings/integrations/useHuduIntegrationEnabled.ts`.
- Guard `requireHuduUiFlagEnabled('read'|'update')` mirrors Entra `requireEntraUiFlagEnabled`: flag `hudu-integration` via `featureFlags.isEnabled`, RBAC `system_settings`, EE tier+add-on, 404 when flag off. **Reuse this guard in every EE Hudu route/action.**
- `contracts.ts` exports `HUDU_INTEGRATION_TYPE` + value-stripped `HuduAssetPasswordSummary` (no `password` field) for list payloads.
- Verified: focused tsc on all 10 files = 0 errors; `tsc -p packages/integrations/tsconfig.json` clean for our files; remaining server/ee baseline errors are pre-existing and reference no hudu file.
- Tests T001–T004 written + green (13 cases). Group committed `eca8008` (also includes the plan folder).

### `hudu-client` (F010–F017, T010–T018) — DONE + verified 2026-06-09, committed
- `ee/server/src/lib/integrations/hudu/huduClient.ts` (axios, x-api-key, pagination stop-at-<25, 429 Retry-After+jitter backoff capped at 4 attempts, 5xx exp backoff, validateConnection w/ password-access probe) + `secrets.ts` (`HUDU_SECRET_KEYS` = `hudu_api_key`/`hudu_base_url`; resolve tenant secret → env via `getSecretProviderInstance()`/`getTenantSecret`). Barrel updated.
- Result shape: `HuduResult<T> = {ok:true,data} | {ok:false,error:HuduError}`; `HuduError.kind ∈ invalid_key|no_password_access|not_found|validation|rate_limited|server_error|network_error|unknown`. Read methods THROW `HuduRequestError` (carrying the typed HuduError); consuming actions (connection/reference-fetch groups) map throw→envelope. `validateConnection()` returns the struct directly.
- Backoff `sleep` is injectable so tests run fast (no real timers). Redaction: errors built from status only, never bodies/headers/key.
- 22 unit tests (axios `vi.mock`ed, no network). Reuse `createHuduClient()` in later groups; do NOT add OAuth (x-api-key only).

### `connection` (F020–F028, T020–T028) — DONE + verified 2026-06-09 (uncommitted)
- Migration `ee/server/migrations/20260609120000_create_hudu_integrations.cjs`: tenant uuid FIRST col, integration_id default gen_random_uuid(), PK (tenant,integration_id), unique(tenant) (one connection/tenant), FK tenants CASCADE, settings jsonb '{}', `update_hudu_integrations_updated_at` trigger (on_update_timestamp), Entra-style citus guard (pg_is_in_recovery + pg_extension + pg_dist_partition, `colocate_with => 'tenants'` — Entra ensureDistributedTable precedent; teams uses microsoft_profiles only because of its FK), console.warn+skip when citus absent, GRANT to DB_USER_SERVER, `transaction:false`. down() drops the table.
- Repository `ee/server/src/lib/integrations/hudu/huduIntegrationRepository.ts`: `getHuduIntegration/upsertHuduIntegration/setHuduIntegrationActive/touchHuduIntegrationLastSynced`, all `(knex, tenant, ...)` (contactLinkRepository style — callers/tests inject the handle). Upsert = insert onConflict(['tenant']).merge, partial-field merge keeps untouched cols. Exported from barrel.
- Actions `ee/server/src/lib/actions/integrations/huduActions.ts` ('use server'): `connectHudu/testHuduConnection/getHuduConnectionStatus/disconnectHudu`, each wrapped in `withHuduSettingsAccess(perm)` = withAuth + user_type!=='client' + `system_settings` RBAC + assertTierAccess(INTEGRATIONS) + assertAddOnAccess(ENTERPRISE) + `hudu-integration` flag (action-level mirror of requireHuduUiFlagEnabled). Capability stored in `settings.password_access`. getStatus/route NEVER read or return the key. disconnect deletes both tenant secrets + setActive(false); mappings untouched. createTenantKnex imported from 'server/src/lib/db' (NOT '@/lib/db' — vitest alias for that subpath doesn't exist in EE).
- EE route GET now returns real status via repository (status/baseUrl/connectedAt/lastSyncedAt/passwordAccess).
- `contracts.ts` adds `HUDU_MAPPING_TABLE = 'tenant_external_entity_mappings'` — mapping group MUST use it (NFR7 boundary anchor; boundary test asserts it).
- Tests (49 hudu tests green total): T020–T022 REAL DB (`src/__tests__/integration/hudu-integrations.migration.integration.test.ts` — direct knex to local `server` DB :5432, postgres + secrets/postgres_password, single-migration up()/down() re-apply pattern; tests self-contained because vitest shuffles); T023–T026 unit-mocked (`huduConnectionActions.test.ts` — mock '@alga-psa/auth' withAuth, repo + HuduClient via '@ee/...' specifiers which dedupe with relative imports); T027/T028 static fs sweep (`huduDeletionBoundary.test.ts`). T028 client-delete-removes-mapping-rows half deferred to the mapping group (noted in test).
- Gotchas: `array_agg(a.attname)` (name[]) comes back as unparsed `{tenant}` string — cast `::text`; ee tsconfig is non-strict so `if (!result.success)` does NOT narrow unions in tests — use toMatchObject.

### `settings-ui` (F030–F034, T030–T034) — DONE + verified 2026-06-09 (uncommitted)
- Bridging decision: NinjaOne/Tanium precedent (NOT the heavier Entra entry-swap). Real component `ee/server/src/components/settings/integrations/HuduIntegrationSettings.tsx` imports `huduActions` directly (relative path, like TaniumIntegrationSettings); CE placeholder stub at `packages/ee/src/components/settings/integrations/HuduIntegrationSettings.tsx`; the page loads it via `dynamic(() => import('@enterprise/components/settings/integrations/HuduIntegrationSettings'))` — `@enterprise` is already edition-swapped in next.config (ee/server/src vs packages/ee/src), so NO new aliases/routes needed. CE delegator route untouched (still 3/3).
- Page: `IntegrationsSettingsPage.tsx` gets an `it-documentation` category (icon BookOpen, single `hudu` item, isEE) spread-gated on `useHuduIntegrationEnabled().enabled`; `calendarAvailability.getVisibleIntegrationCategoryIds` EE branch now includes `IT_DOCUMENTATION_SETTINGS_CATEGORY = 'it-documentation'` (CE list unchanged → CE can never show it).
- F033 additive huduActions change: `connectHudu` takes `HuduConnectInput` (`apiKey?`) — blank key falls back to stored key via `resolveHuduCredentials`, error unchanged when neither exists; `testHuduConnection` merges partial candidates with stored creds; failure arm of `HuduActionResult` gains optional `errorKind` (set from validation error) so the UI maps 401→invalid-key / 404→bad-base-URL messages. UI only sends `apiKey` when non-empty.
- Component: status badge Not connected/Connected/Error (Badge secondary/success/error), detected instance + password-access indicator when connected, inline URL-format validation, `useToast` (destructive) on failures, key input `type=password` `autoComplete=new-password` never prefilled, cleared after connect.
- i18n: `integrations.categories.itDocumentation` + `integrations.items.hudu` in `server/public/locales/en/msp/settings.json`; `integrations.hudu.settings.*` in `en/msp/integrations.json`. Component uses NinjaOne-style `t(key, { defaultValue })`.
- Tests (ee/server vitest, jsdom + @testing-library, entra-test house style): `huduSettingsPageCategory.test.tsx` (T030, 3 cases — gate on/off/CE; mocks sibling components via `@alga-psa/integrations/...` specifiers that dedupe with relative imports) + `huduIntegrationSettings.component.test.tsx` (T031–T034, 15 cases). 3 keep-existing-key cases added to `huduConnectionActions.test.ts` (one strict-equality assertion extended for `errorKind`). All 67 hudu tests green.
- Harness gotchas (REUSE): mock `@alga-psa/ui/lib/i18n/client` with a STABLE `t` identity (new-per-render t retriggers useCallback'd loaders → infinite loading flicker); added vitest alias `@product/billing/entry` → `packages/product-billing/oss/entry.tsx` in ee/server/vitest.config.ts (page's Stripe dynamic import broke Vite transform); jest-dom matcher TYPES don't resolve in ee/server (nested vitest 4.1.5 vs root 4.0.18 — pre-existing, entra tests have same errors) → use plain assertions (`toBeTruthy`/`.disabled`/`textContent`); `entraIntegrationSettings.initialSyncCta.test.tsx` & co fail PRE-EXISTING on this branch (i18n strings unresolved) — verified identical 22-file/50-test failure set with changes stashed.

### `company-mapping-data` (F040–F046, T040–T048) — DONE + verified 2026-06-09 (uncommitted)
- `ee/server/src/lib/integrations/hudu/companyMapping.ts`: matcher + cache shaping (pure) AND knex-level persistence/resolvers (all `(knex, tenant, ...)`, table via `HUDU_MAPPING_TABLE`); `ee/server/src/lib/actions/integrations/huduMappingActions.ts` ('use server', own copy of `withHuduSettingsAccess` — can't export a sync wrapper from a 'use server' file): `syncHuduCompanies` (update), `getHuduCompanyMappings` (read), `setHuduCompanyMapping`/`clearHuduCompanyMapping` (update), `resolveHuduCompanyIdForClient`/`resolveClientIdForHuduCompany` (read). Barrel updated.
- Matcher: per-company priority id_in_integration string-equals client_id (1.0) → exact case-insensitive name (0.9) → fuzzy normalized-Levenshtein ≥ 0.8 (score); already-mapped companies/clients excluded; greedy one-to-one claiming (best pass/score wins a client). Cache shape: `settings.companies_cache = { companies: [{id,name,id_in_integration:string|null,url}], fetched_at: ISO }` — read-modify-write merge preserves `password_access`.
- SCHEMA FACTS (verified live): shared table column is `tenant` (NOT `tenant_id` — renamed by 20250512094730_standardize_tenant_columns), PK `(id, tenant)`; BOTH one-to-one directions already DB-enforced (`idx_unique_alga_mapping` + `idx_unique_external_mapping` w/ COALESCE(realm,'')); `sync_status` is unconstrained varchar(20) → `'manual_link'` used. Pre-checks give friendly typed errors (`client_already_mapped`/`company_already_mapped`); racing 23505 → `mapping_conflict`. Replace = explicit clear+set only.
- Tests (97 hudu tests green across 10 files): `unit/huduCompanyMatcher.test.ts` (T041–T043, pure), `unit/huduMappingActions.test.ts` (T040/T046 — partial vi.mock of companyMapping via importOriginal keeps matcher real, fakes row fns), `integration/hudu-company-mappings.integration.test.ts` (T044/T045/T047/T048 — real DB :5432, random-uuid tenant + 2 clients fixtures, full cleanup, beforeEach wipes tenant's mapping rows for shuffle-safety).
- Gotchas: non-strict ee tsconfig doesn't narrow `result.ok` unions in SOURCE either → `Extract<HuduMappingWriteResult, { ok: false }>` cast in the action; vitest 4 `importOriginal` is untyped → cast the awaited result, not a type argument. Levenshtein note: 'Acme Corp' vs 'Acme Corporation' is only ~0.56 — pick near-variants (≤20% edits) for fuzzy fixtures. Pre-existing (NOT this group): `huduSettingsPageCategory.test.tsx(28)` TS2347.

### `company-mapping-ui` (F050–F053, T050–T053) — DONE + verified 2026-06-09 (uncommitted)
- `ee/server/src/components/settings/integrations/hudu/HuduCompanyMappingManager.tsx` modeled on NinjaOne `OrganizationMappingManager` (Card + counters + table + per-row `ClientPicker` + Refresh via `useTransition`). NO CE stub: like `ninjaone/` (no `packages/ee/.../ninjaone` dir exists), the manager is only imported relatively by the EE-injected `HuduIntegrationSettings`, which now renders it in a `mt-6` sibling div below the connection card when `isConnected` (the action sets `connected = row.is_active`, so connected already implies active).
- Row state from `getHuduCompanyMappings` views: status = mapping→Mapped(success) / suggestion→Suggested(primary) / else Unmapped(warning); counters mapped/suggested/unmapped/total (`hudu-mapping-count-*`). Picker pre-fill `mapping?.client_id ?? suggestion?.client_id`; suggested rows get a source+confidence note (`hudu-mapping-suggestion-<id>`). Select → `setHuduCompanyMapping` (metadata from the row), clear → `clearHuduCompanyMapping({mappingId})`, change on a mapped row = explicit clear-then-set (server rejects overwrites); typed codes (`client_already_mapped` etc.) map to friendly messages + destructive toast. Refresh = `syncHuduCompanies` then `loadData()` (mappings untouched server-side). Clients via `getAllClients(false)` from `@alga-psa/clients/actions`.
- i18n: `integrations.hudu.mapping.*` added to `server/public/locales/en/msp/integrations.json`; component uses `t(key, { defaultValue })` throughout.
- Tests: `unit/huduCompanyMappingManager.component.test.tsx` (T050–T053, 9 cases — mapping actions + `@alga-psa/clients/actions` mocked, ClientPicker mocked as a plain `<select>` ('' = null), same Card/Badge/Button/Alert/toast/i18n mock idioms); settings test gains the manager stub mock + 2 embedding cases (renders when connected, absent otherwise). All 9 hudu unit files green (101 tests). Focused tsc: 0 errors in touched files (the only hudu hit is the PRE-EXISTING `huduSettingsPageCategory.test.tsx(28)` TS2347 — re-verified with changes stashed).
- Gotchas (REUSE): testing-library `getByText` matches DIRECT text nodes, but client names appear in every picker mock's `<option>`s too — assert row `textContent` instead; `fireEvent.change` to the already-selected value does NOT fire React onChange (value tracking), so "confirm the suggested client" can't be simulated by re-selecting it.

### `company-mapping-ui` (F050–F053, T050–T053) — DONE + verified 2026-06-09, committed
- `ee/server/src/components/settings/integrations/hudu/HuduCompanyMappingManager.tsx` — NinjaOne OrganizationMappingManager pattern: counters, per-row ClientPicker (pre-filled with mapping or suggestion), Mapped/Suggested/Unmapped badges, Refresh Companies. Rendered inside HuduIntegrationSettings when connected (sibling div, NinjaOne precedent — no CE stub needed: only imported relatively by the EE-injected parent).
- Mapped-row change = explicit clear-then-set (server rejects overwrites); typed conflict codes → friendly toast.
- **Gotcha fixed: cross-file Postgres deadlock (40P01)** — the migration test's `DROP TABLE hudu_integrations` (needs lock on `tenants` for the FK) vs the mapping test's `DELETE FROM tenants` (cascade needs lock on `hudu_integrations`) when vitest ran both files in parallel. Fix: both hudu integration test files take `pg_advisory_lock(hashtext('hudu-db-integration-tests'))` in beforeAll on a single-connection pool (`pool:{min:1,max:1}`), unlock_all+destroy in afterAll. Full suite 108/108 ×3.

### `reference-fetch` (F060–F068, T060–T069) — DONE + verified 2026-06-09 (uncommitted)
- `ee/server/src/lib/integrations/hudu/referenceData.ts`: capped-FIFO module Map cache keyed `${tenant}:${companyId}:${resource}` (TTL 60s, cap 200, lazy expiry; externalMappingActions pattern), allowlist `toHuduAssetPasswordSummary` (only id/company_id/name/username/url/password_folder_name/description/timestamps — `password`/`otp_secret`/unknown fields can never pass), deep-link builders `buildHuduRecordUrl` (record url absolute as-is / relative resolved via `huduInstanceBaseUrl`) + `buildHuduCompanyUrl` (company url → `/companies/jump` API URL only when id_in_integration+slug known → null). `contracts.ts` gains explicit `otp_secret` and Summary = `Omit<…,'password'|'otp_secret'>`.
- `ee/server/src/lib/actions/integrations/huduDataActions.ts` ('use server', own `withHuduSettingsAccess` copy): `getHuduCompanyAssets/Articles/Passwords(clientId, {refresh?})` + `revealHuduPassword(clientId, huduPasswordId)` — ALL read-gated (PRD flow 4 = technician view; reveal's compensating control is the mandatory audit, not a harder gate). Shared `fetchCompanyList`: row-level resolver (unmapped ⇒ `{state:'unmapped'}` before ANY Hudu call), cache-or-fetch, project BEFORE cache (passwords stripped pre-cache), per-record `hudu_url` = record url → company url (from companies_cache + base_url) → null. 403 ⇒ `{state:'no_password_access'}`; HuduRequestError ⇒ `{state:'error',errorKind}`.
- Reveal: single `getAssetPassword(id)` GET, company_id must equal the mapped company (else `not_found` — no cross-company leak), 404→not_found, 403→no_password_access; audit BEFORE value, **fail-closed** (audit throw ⇒ error state, no value); value never cached/persisted/logged (logger gets ids only). Read actions stay write-free (no `touch…LastSynced` on fetch — same as the mapping read path).
- **Audit sink** `ee/server/src/lib/integrations/hudu/revealAudit.ts`: shared `audit_logs` table via `auditLog` from `server/src/lib/logging/auditLog` (EE precedent: ninjaoneActions REMOTE_ACCESS audit) — BUT auditLog silently SKIPS when the `app.current_tenant` GUC is unset (new pool model never sets it), so wrap in `knex.transaction` + `set_config('app.current_tenant', tenant, true)` first (expiredCreditsHandler precedent; audit_logs trigger stamps tenant from the GUC). Row: operation `hudu_password_reveal`, table `clients`, record clientId, details `{integration,tenant,hudu_password_id,hudu_company_id,revealed_at}` — never the value.
- Tests (141 hudu tests green across 14 files, ×2 shuffled seeds): `unit/huduReferenceData.test.ts` (cache TTL/keying/eviction via fake timers, stripping, deep links), `unit/huduRevealAudit.test.ts` (GUC-before-auditLog ordering, payload key audit, fail-closed propagation), `unit/huduDataActions.test.ts` (T060–T063/T065–T069; partial importOriginal mocks keep HuduRequestError + parseCompaniesCache + the REAL referenceData cache; asserts client-never-called on unmapped, single-GET reveal with zero repo/Vault/knex/cache writes and value absent from every logger+console call).
- Gotcha (REUSE): static-importing a partially-mocked module (`vi.mock(..., importOriginal)`) from the test file TDZ-crashes on the factory's closure over mock consts — use top-level `await import(...)` after the const declarations instead.

### `client-hudu-tab` (F070–F072, F074, F075; T070/T071/T073/T074) — DONE + verified 2026-06-09 (uncommitted)
- Tab mechanism (no prior client-page extension point existed; combined the two precedents): real EE tab `ee/server/src/components/integrations/hudu/HuduClientTab.tsx` (imports huduDataActions relatively); CE null stub `packages/ee/src/components/integrations/hudu/HuduClientTab.tsx`; CE wrapper `packages/clients/src/components/clients/HuduClientTab.tsx` = `dynamic(() => import('@enterprise/components/...'), {ssr:false})` (AssetAlertsSection precedent, packages/assets); registered in `ClientDetails.tsx` `baseTabContent` (id `hudu`, spread-gated, `huduClientTab.visible` in the useMemo deps).
- Gate `packages/clients/src/components/clients/useHuduClientTab.ts`: `isEnterprise` (@alga-psa/core) + `useFeatureFlag('hudu-integration')` (useHuduIntegrationEnabled logic INLINED — packages/integrations has no exported barrel path for it and adding the package dep wasn't worth it), then dynamic `await import('@enterprise/lib/actions/integrations/huduDataActions')` → new `getHuduClientContext(clientId)` → `{connected, mapped}`; any throw ⇒ hidden. New CE action stub `packages/ee/src/lib/actions/integrations/huduDataActions.ts` returns `{connected:false,mapped:false}` (plain async fn, not 'use server').
- `getHuduClientContext` (additive in EE huduDataActions, read-gated): is_active row check → resolver; NO Hudu API call; internal failure resolves `{false,false}` instead of throwing (UI-gate semantics).
- Tab component: attribution always visible ("Source: Hudu" + Open-in-Hudu link from ok-result companyUrl, F075); Refresh re-runs context+both fetches with `{refresh:true}` (F074); guard states not-connected/unmapped (context OR fetch-level `state:'unmapped'`) + tab-level unreachable (context throw) + per-section unreachable alerts (`state:'error'|'no_password_access'`); rows = name link (target=_blank rel=noopener noreferrer, plain span when hudu_url null) + meta (asset_type · Serial; articles only have `folder_id` in the Hudu payload so meta shows "Folder #N" — no folder NAME exists in the API).
- i18n: `integrations.hudu.clientTab.*` in `en/msp/integrations.json` (component, ns 'msp/integrations'); tab LABEL is `clientDetails.huduTab` in `en/msp/clients.json` (ClientDetails uses ns 'msp/clients').
- Tests: `unit/huduClientTab.component.test.tsx` (T070 guard/T071/T073/T074 + refresh, 12 cases, mapping-manager idioms, actions mocked via `@ee/...`); `unit/huduClientTabGate.test.tsx` (T070 registration gate, 7 cases — mocks `@alga-psa/ui/hooks`, `@alga-psa/core` hoisted-getter isEnterprise, `@enterprise/lib/actions/...`; SUT imported via `@alga-psa/clients/components/...` alias); +5 getHuduClientContext cases in huduDataActions.test.ts. Full hudu suite 16 files / 165 tests green ×2 seeds.
- Verification: packages/clients `tsc --noEmit` 0 errors; ee/server tsc → only pre-existing 3 (huduSettingsPageCategory TS2347 + 2 msp-composition TS2307); packages/clients vitest: 2 pre-existing contacts failures (ContactDetails.inboundDestination.wiring, ContactPortalTab.visibilityGroups) — identical with changes stashed; tsup build keeps `@enterprise` specifiers in dist (entraClientSyncActions precedent — webpack swaps per edition).

### `client-passwords-tab` (F080–F083; T080–T083) — DONE + verified 2026-06-09 (uncommitted)
- Mirrors the client-hudu-tab trio exactly: real EE tab `ee/server/src/components/integrations/hudu/HuduClientPasswordsTab.tsx` (relative huduDataActions imports); CE null stub `packages/ee/src/components/integrations/hudu/HuduClientPasswordsTab.tsx`; CE wrapper `packages/clients/src/components/clients/HuduClientPasswordsTab.tsx` (`dynamic(@enterprise/..., {ssr:false})`). Registered in `ClientDetails.tsx` as a SECOND entry (`id: 'hudu-passwords'`) inside the SAME `huduClientTab.visible` spread, directly after `hudu` — no new gate hook, REUSES `useHuduClientTab`/`getHuduClientContext`.
- Reveal lifecycle (NFR1): values live ONLY in a `revealedValues: Record<id,string>` useState — set by `revealHuduPassword(clientId, id)` on `{state:'ok'}`, deleted on Hide, the whole map reset at the top of every `load()` (so Refresh clears it), gone on unmount; Copy = `navigator.clipboard.writeText` from that state; never logged. Per-row inline reveal errors keyed no_password_access/not_found/else→failed; per-row Open-in-Hudu uses the list's `hudu_url` (record url → company url fallback from the data layer).
- States: loading / tab-level unreachable (context throw) / not-connected / unmapped (context OR fetch-level) / `no_password_access` (DISTINCT key-lacks-password-access alert, id `hudu-passwords-tab-no-access`) / list `error` unreachable / ok-empty / ok-rows (name + username meta + count badge; metadata only).
- i18n: `integrations.hudu.passwordsTab.*` (source/openInHudu/refresh/loading/notConnected/unmapped/unreachable/noPasswordAccess/title/empty/reveal/hide/copy/revealNoAccess/revealNotFound/revealFailed) in `en/msp/integrations.json`; label `clientDetails.huduPasswordsTab` ("Passwords") in `en/msp/clients.json`.
- Tests: `unit/huduClientPasswordsTab.component.test.tsx` (T081–T083, 18 cases — value absent pre-reveal, reveal/Hide/Refresh clear the DOM, clipboard mock, afterEach console-spy asserts the secret never hits any console channel) + `unit/huduClientPasswordsTabGate.test.tsx` (T080, 7 cases — gate-mock TabsProbe mirrors the gated spread asserting BOTH tabs absent/present + ordering, plus a ClientDetails source-wiring case). Gotcha: under jsdom `new URL(..., import.meta.url)` is NOT file-scheme — import the source via Vite `'...ClientDetails.tsx?raw'` (alias regex passes the query through) instead of readFileSync. Full hudu suite 16 ee/server files / 183 tests ×2 shuffled seeds + useHuduIntegrationEnabled (4) + huduRouteDelegator (3) = 190 green.
- Verification: packages/clients `tsc --noEmit` 0 errors; ee/server tsc → only the same pre-existing 3; packages/clients tsup build OK, dist keeps the `@enterprise/components/.../HuduClientPasswordsTab` specifier; both packages/clients ClientDetails tests still green.

### `permissions` (F090/F092; T090/T091/T093) — DONE + verified 2026-06-09 (uncommitted)
- Mostly VERIFICATION: full audit of every Hudu server entry point found ZERO gaps — no source change needed. EE route GET `/api/integrations/hudu` → `requireHuduUiFlagEnabled('read')`; CE delegator → `assertSessionProductAccess` + `@enterprise` lazy import (501 stub otherwise); all 15 exported actions wrapped in `withHuduSettingsAccess` (the three per-file copies are byte-identical: client-user reject → `hasPermission(system_settings, level)` → `assertTierAccess(INTEGRATIONS)` → `assertAddOnAccess(ENTERPRISE)` → `hudu-integration` flag). Levels: update = connectHudu/testHuduConnection/disconnectHudu/syncHuduCompanies/setHuduCompanyMapping/clearHuduCompanyMapping; read = getHuduConnectionStatus/getHuduCompanyMappings/both resolvers/getHuduClientContext/getHuduCompanyAssets/Articles/Passwords/revealHuduPassword (reveal stays read per plan — compensating control is the fail-closed audit).
- New `unit/huduPermissions.test.ts` (46 cases): completeness case derives runtime function exports of all three action modules and asserts they EQUAL the manage∪view lists (adding an unlisted action later fails T093); T090 it.each over the 6 manage actions with read-granted/update-denied `hasPermission` (catches mis-gating at read); T091 it.each over the 9 view entries with update-granted/read-denied (catches over-gating at update); T093 it.each ×15 flag-off (perm granted) + it.each ×15 add-on-denied (asserts flag never consulted); every denial also asserts no `createTenantKnex`/secret-provider work happened. Route-guard path NOT duplicated — already huduFlagGuard.test.ts (T001) + huduRouteDelegator.test.ts.
- Gate-test trick (REUSE): `mockImplementation((_u,_r,perm) => perm !== 'update')` instead of blanket-false makes the permission-LEVEL assertions real — blanket-false would pass even if an action gated at the wrong level.
- Verified: full hudu ee/server suite 19 files / 236 tests green ×2 shuffled seeds (1111, 987654) incl. both real-DB integration files; + huduRouteDelegator (3) + useHuduIntegrationEnabled (4) green; ee/server tsc → only the same pre-existing 3 errors (huduSettingsPageCategory TS2347 + 2 msp-composition TS2307), zero touching huduPermissions.

### `i18n` (F100/T100) — DONE + verified 2026-06-09 (uncommitted)
- Pure VERIFICATION group: zero i18n gaps found — every key already resolves, no hardcoded strings. New static test `unit/huduI18n.test.ts` (12 cases), no source/locale changes.
- Key resolution: collects every `t('…')` literal via regex from the 4 Hudu components (Vite `?raw` imports — huduClientPasswordsTabGate precedent) + ClientDetails (the 2 `clientDetails.hudu*` labels) + IntegrationsSettingsPage (`integrations.categories.itDocumentation.*`/`integrations.items.hudu.*`), filtered to the Hudu key families, and asserts each resolves to a non-empty string in its namespace file (msp/integrations→integrations.json, msp/clients→clients.json, msp/settings→settings.json). Per-source minKeys lower bounds guard the extraction regex against rot; missing keys fail by name.
- Hardcoded-string heuristic (documented in-file): strip comments → candidate text nodes = `(?<!=)>([^<>{}]+)<(?=[A-Za-z/])` (brace-free runs between a tag-`>` and a tag-`<`; translated text always renders via `{t(…)}` so literal nodes are brace-free) → reject code-shaped candidates (`[;=()\`]` — generics/statements between `>`…`<` were the false-positive source) → flag >2 words (3+ runs of 2+ letters). Plus literal multi-word label/placeholder/title/alt/aria-label attributes. Self-test case pins the heuristic. Allowlist const provided (currently empty).

### `regression` (T110–T114) — DONE + verified 2026-06-09 (uncommitted)
- New `unit/huduRegression.test.ts` (21 cases) + `integration/hudu-regression.integration.test.ts` (T112 DB half, same advisory-lock + single-conn-pool harness/key as the other two DB files).
- **Real gap found + minimally fixed (T111): disconnect did NOT clear the reference cache** — reconnect with a new key within the 60s TTL could serve keyA-era lists. Fix: `clearHuduReferenceCacheForTenant(tenant)` added to referenceData.ts (tenant-prefix delete), called from `disconnectHudu` after setActive(false). Lifecycle test proves connect(keyA)→fetch(cached)→disconnect(secrets+cache gone)→connect(keyB)→fetch WITHOUT refresh is live keyB data, keyA strings absent.
- T110 static sweep (fs walk for /hudu/i-pathed non-test sources across ee/server/src + server/src + packages, ≥20 files, completeness-pinned): balanced-paren call-arg extraction asserts (a) knex insert/update/merge args have no password/otp token (allowlist: password_access, password_folder_name, hudu_password_id…), (b) setTenantSecret only ever called with HUDU_SECRET_KEYS.apiKey/baseUrl (exactly 1 call site each), (c) setCachedHuduList call sites never pass raw records, (d) logger/console args never reference record/.password/otp_secret/apiKey/value. Behavioral: poisoned record through REAL toHuduAssetPasswordSummary strips password/otp_secret/totp/unknown fields. Reveal-path behavioral guarantees referenced to T067/T068, not duplicated. NOTE: the CE delegator's `console.error('… Failed to load EE route')` is deliberate (entra precedent) — the console check inspects args, doesn't ban console.
- T112: DB — tenant A's mapping rows invisible to tenant B list+resolvers; same external company id maps independently per tenant (unique indexes are tenant-scoped) and resolves per tenant. Unit — cache keys tenant-prefixed (poison A ⇒ B miss; same companyId distinct per tenant).
- T113: it.each network_error over assets/articles/passwords ⇒ `{state:'error',errorKind:'network_error'}`; reveal same (no value, no audit); failing createHuduClient factory same; getHuduClientContext untouched by Hudu unreachability (no Hudu call).
- T114: actions re-resolve the mapping EVERY call (resolver consulted per call, no memoization) — clearing the mapping flips the next fetch to `unmapped` even with a warm cache; context flips mapped:false; reveal blocked (no GET, no audit).
- Harness gotcha (REUSE): `vi.clearAllMocks()` keeps `mockRejectedValue` overrides — restore shared mock default implementations in beforeEach (createHuduClientMock leak made T113 failures bleed into shuffled neighbors).
- Verified: full hudu ee/server suite 22 files / 271 tests green ×2 shuffled seeds (1111, 987654) incl. all three real-DB files; + huduRouteDelegator (3) + useHuduIntegrationEnabled (4); ee/server tsc → only the same pre-existing 3 errors.