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

# PRD — Hudu Integration

- Slug: `hudu-integration`
- Date: `2026-06-08`
- Status: Draft
- Edition: Enterprise (EE) only
- Phase: 1 (pull-only, Hudu → AlgaPSA)

## Summary

Add a Hudu integration to AlgaPSA that lets an MSP connect a Hudu instance (Hudu Cloud or self-hosted) and surface that Hudu data — companies, assets, knowledge-base articles, and asset passwords — read-only inside AlgaPSA, scoped to the AlgaPSA client it belongs to.

Hudu is the MSP's IT-documentation system of record. AlgaPSA is the PSA (system of record for clients/tickets/billing). This integration does **not** copy Hudu's documentation into AlgaPSA; it persists only the **client ↔ Hudu-company mapping**, fetches a mapped company's lists **on demand** (cached, with manual refresh), and **deep-links** to Hudu for the actual content. This matches how the wider Hudu ecosystem integrates (scheduled/low-frequency reads + deep-links; never duplicating Hudu's docs, especially secrets).

Phase 1 is **pull-only** and **EE-only**, gated behind a `hudu-integration` feature flag. The data model is kept direction-agnostic so a future push (AlgaPSA → Hudu) phase is additive.

## Problem

MSP technicians using AlgaPSA constantly need a client's documentation — devices, network notes, runbooks, and especially credentials — which lives in Hudu. Today they context-switch to Hudu, find the right company, and dig for the record.

There is no link between an AlgaPSA client and its Hudu company, and no way to see Hudu content in context while working a ticket. Hudu's `asset_passwords` are **company-scoped** — they are not attached to a specific device — so credentials cannot be mapped to an individual AlgaPSA asset; they belong at the client level. (AlgaPSA does ship an asset "Documents & Passwords" tab whose Passwords half is an unimplemented stub, but that is a different, asset-scoped concern and is left for the separate future native-password effort — see Non-goals.)

## Goals

- Let an EE tenant connect a Hudu instance with an API key + base URL, and validate the connection.
- Map AlgaPSA clients to Hudu companies (auto-suggested, admin-confirmed).
- Surface a mapped client's Hudu data read-only, all on the **Client** detail page:
  - a **"Hudu" tab** for **assets** and **articles**, and
  - a separate **"Passwords" tab** for the company's Hudu **asset passwords** (visible only when the Hudu integration is enabled and the client is mapped). Credentials live here, not on the asset, because Hudu passwords are company-scoped.
- Deep-link every surfaced record back to Hudu as the system of record.
- Keep the integration safe: never persist a Hudu password value anywhere in AlgaPSA (DB, Vault, or cache).

## Non-goals

- **Push / write-back to Hudu** (Alga → Hudu create/update). Deferred; model stays direction-agnostic.
- **Importing Hudu records as native AlgaPSA records** (no creating Alga `assets`/`documents` rows from Hudu).
- **Websites** entity (no clean AlgaPSA mapping target). Deferred.
- **Scheduled background sync engine / Temporal workflows.** Phase 1 fetches on demand + manual refresh. (A low-frequency scheduled refresh is a documented future enhancement.)
- **Contacts, Procedures, Magic Dash, Networks, Relations** and other Hudu resources beyond the four named entities.
- **CE availability.** EE only; CE routes return 501.
- **Persisting or caching Hudu passwords** anywhere in AlgaPSA (DB column, Vault, or cache). Phase 1 reveals on demand via live fetch only.
- **A native AlgaPSA password store** (first-class password management in Alga) and **importing Hudu passwords into it**. Deliberately deferred to a separate future effort/plan; added only if demanded.
- **Modifying the asset "Documents & Passwords" tab.** Left as-is (still a stub) in Phase 1 — Hudu passwords are company-scoped, so they surface on the client's Passwords tab, not the asset. The asset stub is the future native-password effort's concern.
- Monitoring/metrics/observability infrastructure beyond what the UI needs to show connection/fetch status.

## Users and Primary Flows

**Personas**
- **MSP Admin** — connects Hudu, manages client↔company mappings.
- **MSP Technician** — views a client's / asset's Hudu data in context while working.

**Primary flows**
1. **Connect Hudu** (Admin): Settings → Integrations → IT Documentation → Hudu → enter base URL + API key → Test → Connected.
2. **Map companies** (Admin): Hudu settings → Company Mapping → review auto-suggested matches (by `id_in_integration`, then name) → confirm/override per row → Save. Refresh companies re-pulls the Hudu company list.
3. **View client documentation** (Technician): open a mapped Client → "Hudu" tab → see assets / articles lists with counts → click any item → opens in Hudu.
4. **View client credentials** (Technician): open a mapped Client → "Passwords" tab → list of the company's Hudu credentials (name, username, URL) → "Reveal" fetches the value live from Hudu (masked, reveal-on-click, audited, never stored); "Open in Hudu" links to the record.

## UX / UI Notes

- **Settings entry**: new category **"IT Documentation"** in `IntegrationsSettingsPage.tsx` (`categories` array), with a single `HuduIntegrationSettings` item (`isEE: true`). Hidden unless EE + `hudu-integration` flag enabled.
- **Connection panel** (`HuduIntegrationSettings.tsx`): base URL field, API key field (write-only/masked), Test Connection button (calls `GET /api/v1/companies?page=1`), status badge (Not connected / Connected / Error), Disconnect button. On connect success, show the resolved instance + password-permission status of the key (so the admin knows whether passwords will be visible).
- **Company mapping** (`HuduCompanyMappingManager.tsx`): modeled on NinjaOne `OrganizationMappingManager` — counters (mapped / unmapped), a table with columns **Hudu Company** (name + id) | **AlgaPSA Client** (`ClientPicker` dropdown, pre-filled with the suggested match) | **Status** (badge: Suggested / Mapped / Unmapped), and a **Refresh companies** button. Selecting a client persists immediately.
- **Client "Hudu" tab**: read-only sections for Assets and Articles; each row deep-links to Hudu; show counts; "Refresh" button; empty/disconnected/unmapped states. Visible only when EE + flag + Hudu connected + client mapped.
- **Client "Passwords" tab** (separate tab on the Client detail page, shown only when the Hudu integration is enabled, connected, and the client is mapped): read-only list of the mapped company's Hudu `asset_passwords` (name, username, URL) with an inline **Reveal** (live fetch, masked, reveal-on-click, audited, never stored) and an "Open in Hudu" link. Empty/error states for unmapped / disconnected / key-lacks-password-permission.
- All Hudu-derived UI must visibly attribute Hudu as the source and link out.

## Requirements

### Functional Requirements

**Connection**
- FR1. Store Hudu `base_url` and `api_key` per tenant via the secret provider; never expose the key back to the client.
- FR2. Validate a connection by calling Hudu and surfacing success/failure + the key's password-access capability.
- FR3. Persist connection state (active, connected_at, last fetch) in a `hudu_integrations` table.
- FR4. Disconnect clears the connection (deletes secrets, marks inactive) but retains mappings.

**Hudu API client**
- FR5. Axios client using `x-api-key` + base URL, resolving credentials tenant-secret → env fallback.
- FR6. Page-based pagination helper (25/page; stop when a page returns < 25).
- FR7. Rate-limit handling: on HTTP 429 back off using `Retry-After` (+ jitter) and retry; cap retries.
- FR8. Map Hudu errors to typed results: 401 (bad key), 403 (no password permission), 404 (bad base URL/id), 429 (rate limited), 5xx (retry).
- FR9. UI→API naming is handled internally (`asset_passwords`, `procedures`, etc.).

**Company mapping**
- FR10. Fetch the Hudu company list for the connected tenant.
- FR11. Auto-suggest each Hudu company → AlgaPSA client by `id_in_integration` (exact, when it equals an Alga client id), then exact name, then fuzzy name; expose a confidence/source.
- FR12. Persist mappings in `tenant_external_entity_mappings` (`integration_type='hudu'`, `alga_entity_type='client'`, `external_entity_id=<hudu_company_id>`, `metadata={hudu_company_name, id_in_integration, url}`). One Hudu company ↔ one client.
- FR13. Admin can confirm a suggestion, override the client, or clear a mapping.

**Surfacing (read-only)**
- FR14. For a mapped client, fetch its Hudu assets, articles, and asset passwords (company-scoped) on demand, with a short server-side cache and a manual Refresh.
- FR15. Client "Hudu" tab renders the assets and articles lists with counts and deep-links.
- FR16. Client "Passwords" tab (separate from the Hudu tab, shown only when Hudu is enabled/connected and the client is mapped) renders the mapped company's Hudu passwords list with inline Reveal (live fetch, audited, never stored) and Open-in-Hudu links.
- FR17. Every surfaced record links to its Hudu URL (per-record URL or `/companies/jump` deep-link).
- FR18. Clear empty/error states for: not connected, client unmapped, Hudu unreachable, key lacks password permission (403).
- FR19. Reveal a single credential on demand via a targeted live GET; return the value transiently to the browser (masked, reveal-on-click); never persist it (DB/Vault/cache) or log it.
- FR20. Audit every reveal (who, when, which password/company); the audit entry never contains the value.

### Non-functional Requirements

- NFR1. **Security**: no Hudu password value is ever persisted anywhere in AlgaPSA — not a DB column, not Vault, not a cache. Reveal is on demand: a targeted live GET returns the value transiently to the browser (masked, reveal-on-click); every reveal is audited; the value is never logged or written server-side. The connection's own `api_key` is stored only via the secret provider (Vault).
- NFR2. **EE gating**: all server entry points require EE + `hudu-integration` flag; CE routes return 501 via the `@enterprise` lazy-import stub.
- NFR3. **Tenant isolation**: all queries tenant-scoped via `createTenantKnex()`; tables are Citus-distributed by `tenant`.
- NFR4. **Rate-limit safety**: on-demand fetches are per-mapped-company and paginated; never bulk-fetch across all clients on a page view.
- NFR5. **i18n**: all user-facing strings use translation keys.
- NFR6. **Direction-agnostic data model**: mapping rows carry no pull-only assumptions, enabling a later push phase.
- NFR7. **EE/CE deletion boundary**: `hudu_integrations` is EE-only, so every read/write/**delete** against it — disconnect, and any client-/tenant-delete cascade that removes its rows — must live in EE-only code paths and EE migrations. No CE migration or CE runtime path may name `hudu_integrations` (it does not exist in CE). Mapping cleanup is exempt: those rows live in the shared CE table `tenant_external_entity_mappings` (filtered `integration_type='hudu'`) and are safe to delete from CE.

## Data / API / Integrations

**New table — `hudu_integrations`** (connection state), **EE migration in `ee/server/migrations/`** (Hudu is EE-only; CE never touches it — the CE route 501s before any DB access). Follow the Entra EE precedent `ee/server/migrations/20260220143000_create_entra_phase1_schema.cjs` for the Citus-distributed EE tenant-table pattern (`ee/server/migrations` runs `isCitusEnabled` logic). Columns:
- `tenant uuid`, `integration_id uuid` (PK `(tenant, integration_id)`), `base_url text`, `is_active boolean`, `connected_at timestamptz`, `last_synced_at timestamptz`, `settings jsonb` (e.g. cached capability flags), `created_at`, `updated_at` (+ `on_update_timestamp` trigger). Unique `(tenant)` (one Hudu connection per tenant in Phase 1). Citus-distributed by `tenant`.
- (`rmm_integrations` is CE only because the RMM layer is partly CE — not a precedent for a wholly-EE table.)

**Reused table — `tenant_external_entity_mappings`** for company↔client links (no new migration).

**Secrets**: `hudu_api_key`, `hudu_base_url` via `getSecretProviderInstance().setTenantSecret(tenant, …)`.

**Hudu API surfaces used** (all GET): `/api/v1/companies` (+ `?id_in_integration=`, `?page=`), `/api/v1/assets?company_id=`, `/api/v1/articles?company_id=`, `/api/v1/asset_passwords?company_id=`, per-record URLs, and `/api/v1/companies/jump?integration_id=&integration_slug=` for deep-linking. Auth `x-api-key`. Limits: 300 req/min, 25/page, no consumer webhooks.

**Code locations**
- Client lib: `ee/server/src/lib/integrations/hudu/` (`huduClient.ts`, `contracts.ts`, `secrets.ts`, mapping/suggest helpers).
- Server actions: `huduConnectionActions.ts`, `huduCompanyMappingActions.ts`, `huduDataActions.ts` (fetch lists).
- EE API routes: `ee/server/src/app/api/integrations/hudu/...`; CE stubs: `server/src/app/api/integrations/hudu/...` (501).
- Settings UI: `IntegrationsSettingsPage.tsx` (category), `HuduIntegrationSettings.tsx`, `HuduCompanyMappingManager.tsx`.
- Client tabs: client detail tab host — `HuduClientTab` (assets + articles) and `HuduClientPasswordsTab` (passwords). The asset `packages/assets/src/components/tabs/DocumentsPasswordsTab.tsx` is **not** modified in Phase 1.

## Security / Permissions

- EE + `hudu-integration` feature flag required on every server entry point (guard mirrors `requireEntraUiFlagEnabled`).
- **Reuse the existing `system_settings` RBAC resource** — `read` to view surfaced Hudu data, `update` to connect/disconnect and manage mappings. This matches Entra, Teams, Tactical RMM, and SSO (all `system_settings`); accounting/billing integrations use `billing_settings`, which is the wrong resource here. **No new RBAC resource and no permission seeding** are required (`system_settings` already exists). Note: reuse the `tenant_external_entity_mappings` table for mappings, but do **not** call the `billing_settings`-gated `externalMappingActions` wrappers — Hudu mapping actions enforce `system_settings`.
- API key stored only in the secret provider; masked in UI; excluded from logs and error payloads.
- Password values: handled per NFR1 — revealed on demand via a transient live GET, never persisted (DB/Vault/cache) or logged; every reveal is audited. Respect Hudu key password permission (403 → "password access not enabled for this key").

## Observability

- Minimal: surface connection status, last-fetch time, and fetch errors in the UI. No new metrics/telemetry infrastructure in Phase 1.

## Rollout / Migration

- One **EE migration** (`ee/server/migrations/`) creates `hudu_integrations` (greenfield tenant table: create `tenant uuid` first, distribute inline under the `isCitusEnabled` guard, `transaction:false`), per the Entra precedent.
- No RBAC seeding migration needed — reuse the existing `system_settings` resource.
- Ship dark behind `hudu-integration` (default off). Enable per-tenant for pilot MSPs.
- No data backfill (pull-only, on-demand).

## Open Questions

- OQ1. **RESOLVED** — Phase 1 reveals credentials inline via a targeted live GET (masked, reveal-on-click, audited, never persisted to DB/Vault/cache). A Vault-backed reveal cache and a native AlgaPSA password store (with optional Hudu import) are explicitly deferred to separate future efforts.
- OQ2. **RESOLVED** — Hudu `asset_passwords` are company-scoped and cannot be mapped to a specific asset, so they are **not** surfaced on the asset tab. They get a dedicated **"Passwords" tab on the Client page** (shown only when the Hudu integration is enabled and the client is mapped). The asset "Documents & Passwords" stub is untouched in Phase 1.
- OQ3. **RESOLVED** — Reuse the existing `system_settings` RBAC resource (`read`=view, `update`=manage), matching Entra/Teams/Tactical-RMM/SSO. No new resource, no seeding.
- OQ4. **RESOLVED** — One Hudu instance per tenant (enforced by `unique(tenant)`). Multiple instances are rare in practice (only unmerged M&A or sandbox/prod splits); multi-instance support is a possible future enhancement, not Phase 1.

## Acceptance Criteria (Definition of Done)

- An EE tenant with the flag on can connect a Hudu instance (base URL + key), see a Connected status, and Disconnect.
- A CE build returns 501 for all Hudu routes; the settings item is hidden in CE.
- Admin can see Hudu companies auto-matched to clients, override/confirm, and persist mappings in `tenant_external_entity_mappings`.
- On a mapped client's "Hudu" tab, assets / articles lists render with counts and working deep-links.
- On a mapped client's separate "Passwords" tab (shown only when Hudu is enabled/connected and the client is mapped), the company's Hudu passwords render with inline Reveal (live fetch, never stored) and Open-in-Hudu links. The asset "Documents & Passwords" stub is unchanged.
- No AlgaPSA store (DB column, Vault, or cache) ever contains a Hudu password value; every reveal is audited; the `api_key` is never returned to the client or logged.
- 401/403/404/429/unreachable all produce clear, non-crashing UI states.
- All strings are translated; all server entry points enforce EE + flag + `system_settings` (no new RBAC resource).