saqib mirandClaude Sonnet 5
f475a55a53
Full system blueprint (docs 01-10): product vision, integration & security, AI support architecture, ticketing & problem management, orchestration/SLA/escalation, database schema, backend/frontend architecture, testing/observability/CI-CD, and the implementation roadmap. This is the pre-implementation design reference the codebase is being built against. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
92 lines
4.4 KiB
Markdown
92 lines
4.4 KiB
Markdown
# 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.
|