support_backend/docs/02-integration-and-security.md

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)

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)
• 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)

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.