# 02 — Integration & Security

## 1. Product integration model

Every SaaS product that wants support must be **registered as an integration client** in SupportHub, with its own credential. Credentials are never shared globally across products.

```
Product:              DocuQube
Product ID:           PROD_DQ_001
Support Integration:  Enabled
Integration Credential: PRODUCT_DQ_CREDENTIAL
```

A second product gets an entirely separate `Product ID` and credential — never reuse one credential across products.

## 2. What SupportHub must validate on every inbound request

- The calling product's identity
- The integration credential presented
- Product status (active/suspended/deprecated)
- User/tenant context accompanying the request
- The allowed integration scope for that credential

**Never trust a raw `userId` or `productId` blindly** — every value must be validated against the registered integration and its scope before use.

## 3. Inbound request contract (conceptual)

```ts
interface ProductToSupportHubRequest {
  productId: string;
  tenantId: string;
  userId: string;
  source: string;          // e.g. "docuqube-web", "docuqube-mobile"
  problem: string;         // free-text customer description
  feature?: string;        // e.g. "pdf_to_html"
  referenceIds?: string[]; // e.g. documentId, jobId — product-specific evidence handles
  context?: Record<string, unknown>;
}
```

## 4. Service-to-service authentication

Use production-appropriate mechanisms, chosen per integration risk profile:

- **Signed service tokens** (short-lived, scoped to a product)
- **OAuth2 client credentials** grant where suitable
- **mTLS** for high-trust server-to-server channels
- **Credential rotation** — must be supported without downtime
- **Credential revocation** — immediate effect, audited
- **Audit logging** of every integration authentication event (success and failure)

## 5. RBAC boundary

SupportHub **integrates with** the SaaS's existing RBAC — it does not reimplement it.

- Support-domain authorization (who can see which ticket, which admin config, which agent queue) is SupportHub's own concern and lives entirely within SupportHub's data model (teams, agents, hierarchy scope).
- Customer-facing authorization (does this user have access to this product at all) is always deferred to the SaaS via the validated integration context — SupportHub does not maintain a parallel "does this user own this product" table.
- **A customer must never be able to access another customer's tickets.** Every ticket query must be scoped by the validated `externalTenantId`/`externalUserId` from the authenticated session, never by client-supplied values alone.

## 6. Security requirements checklist

- [ ] Secure product integration (per-product credentials, scoped)
- [ ] Authentication context validated on every request
- [ ] RBAC integration with SaaS (never duplicated)
- [ ] Support-domain authorization (teams/hierarchy/product scope)
- [ ] Customer isolation (tenant/user scoping on every query)
- [ ] Rate limiting per integration and per user
- [ ] Input validation (schema-first, reject unknown/extra fields)
- [ ] Secure file handling (validation, size limits, malware scanning — see [04](./04-ticketing-and-problem-management.md#attachments))
- [ ] Encrypted transport (TLS everywhere, mTLS where appropriate)
- [ ] Encrypted sensitive storage at rest
- [ ] Secret management (never in source, never in `NEXT_PUBLIC_*`)
- [ ] Audit logging for all security-relevant actions (append-only from the application's perspective)

## 7. Environment & secrets handling

```
.env.example
.env.development.example
.env.test.example
.env.production.example
```

- Real environment values are **never committed**.
- Production secrets are injected via CI/CD infrastructure (Jenkins credentials store), not checked into any env file.
- Use environment validation at boot (fail fast if a required var is missing/malformed).
- Only browser-safe variables use the `NEXT_PUBLIC_` prefix — secrets must never be exposed this way.

## 8. AI-specific safety boundary (summary — full detail in [03](./03-ai-support-architecture.md#ai-safety-and-control))

The AI must never: invent product behavior or configuration, invent troubleshooting steps, execute unauthorized actions, access arbitrary customer data, expose internal notes or private knowledge, or modify support configuration/SLA/hierarchy. Deterministic application policy is always the actual decision-maker for anything with real-world effect.