003 Universal Integration Cli Platform

# ADR-003: Universal Integration CLI Platform
 
**Status:** Proposed  
**Date:** 2026-02-06  
**Decision Makers:** RGL8R Engineering
 
---
 
## Context
 
RGL8R currently supports module uploads through API routes (`/api/upload`, `/api/ship/upload`, `/api/catalog/upload`, `/api/orders/upload`) with either Clerk JWTs or development fallback headers (`x-api-key` + `x-org-id`).
 
Customer onboarding needs are shifting toward:
 
- Automated file-based integrations from legacy systems
- Tenant-safe authentication without caller-provided `orgId`
- Reusable adapter/policy configuration across customers
- Audit-friendly evidence of sanitization decisions
 
KnifeCenter is the first target, but the platform must remain customer-agnostic.
 
---
 
## Decision
 
Adopt a universal integration platform with these design constraints:
 
1. Add a dedicated integration-key auth path (`POST /api/auth/token/integration`) that derives tenant from key binding.
2. Keep `POST /api/auth/token` as backward-compatible fallback for existing web/dev flows.
3. Use explicit per-route scope middleware (`requireScopes(...)`) instead of global route-key matching.
4. Externalize source handling into versioned adapters (mapping + required columns + allowlist + PII policy).
5. Record adapter and policy identifiers in manifests for reproducible audits.
 
### Contract Freeze Addendum (2026-02-06)
 
Implementation details are frozen in:
 
- `docs/integration-cli-v1-scope.md`
- `docs/error-contract.md`
- `docs/exit-codes.md`
- `docs/integration-keys.md`
- `docs/adapters.md`
- `docs/manifests.md`
 
This addendum resolves prior draft drift by standardizing:
 
1. Node integration CLI location: `packages/integration-cli` (without changing existing Python `packages/cli`).
2. Integration key naming: `keyPrefixHash` and `keyPrefixFingerprint` (no clear-text key prefix storage).
3. PII policy shape: `patterns`, `globalPatternIds`, `textOnlyPatternIds`.
4. Outcome taxonomy split: `preflight_failed` (header/schema) vs `sanitization_failed` (row/content).
5. Postman source path: `docs/postman/RGL8R-API.postman_collection.json`.
 
---
 
## Non-Goals
 
- No direct implementation of Tier 1 EDI connectors in this phase.
- No dependency on third-party billing API aggregators in this phase.
- No claim of guaranteed PII elimination; only fail-closed policy enforcement with documented limitations.
 
---
 
## Consequences
 
### Positive
 
- Universal onboarding path for CLI, MCP, and future SDK clients.
- Stronger tenant isolation by removing caller-controlled org binding from integration auth.
- Better auditability through adapter/policy version traceability.
- Lower long-term cost to add customers (new adapter config instead of new code path).
 
### Negative
 
- Additional backend surface area (key lifecycle, scope checks, event logging).
- Adapter governance is required to avoid policy drift.
- Migration/operational work needed before rollout (new tables, env vars, key tooling).
 
---
 
## Implementation Notes
 
- Integration keys should be stored as hash + metadata, never plaintext.
- Key prefixes should be neutral (no tenant names in key prefix).
- Scope denials should return structured machine-readable codes.
- Adapter changes that break behavior must bump adapter version.
 
---
 
## Rollout Plan
 
1. Foundation: schema + auth endpoint + scope middleware + env plumbing.
2. CLI core: profile config, token exchange, manifest generation, structured errors.
3. Adapter system: generic baseline adapter + tenant-specific adapters.
4. Pilot onboarding: KnifeCenter strict dry-run gate before production key issuance.
 
---
 
## Current State Clarification
 
This ADR describes target direction and does not imply all capabilities are already live in `apps/api`.