support_backend/specs/002-saas-integration/research.md

Phase 0 Research: SaaS Product Integration & Inbound Request Trust

Decision: Signed short-lived token format

• Decision: HMAC-SHA256-signed token, structured as a compact JWT (header.payload.signature), signed with the ProductIntegration's own per-product secret (never a shared/global secret). Payload carries productId (SupportHub's internal id, not the raw external one), tenantId, userId, iat, exp (short — target 60s, generous enough for clock skew tolerance below), and a jti (nonce) for replay detection.
• Rationale: User picked "signed short-lived tokens" over OAuth2/mTLS for this plan (lowest operational overhead, no token-issuance service to build, straightforward per-product secret rotation). JWT is chosen over a bespoke signed-string format purely because Node's ecosystem already has well-reviewed JWT libraries and it's a format integrating teams will recognize — but the validation logic is fully custom (see below), it doesn't defer trust decisions to a JWT library's defaults.
• Alternatives considered: OAuth2 client-credentials (rejected per user decision — adds a token-issuance/introspection surface this plan doesn't need); mTLS (rejected — heavier operationally, reserved as a future per-integration option since ProductIntegration .authMechanism is already a free-text field in docs/06, not an enum, so nothing here blocks adding mTLS support to a specific high-trust integration later without a schema change).

Decision: Replay resistance

• Decision: Reject a token whose jti has been seen before within its own validity window. Track seen jtis in Redis (already an infrastructure dependency — infrastructure/cache) with a TTL matching the token's exp, so the tracking set never grows unbounded.
• Rationale: A 60-second token expiry alone bounds the replay window but doesn't close it — a captured token is still valid for up to 60s. jti-tracking closes it to "exactly once."
• Alternatives considered: Expiry-only (no jti tracking) — rejected, doesn't satisfy spec.md's Edge Cases requirement that a replayed token "MUST be rejected," only that it eventually stops being accepted.

Decision: Clock skew tolerance

• Decision: Accept a token up to 5 seconds past its exp and up to 5 seconds before its iat (both configurable, not hardcoded — Constitution Principle II).
• Rationale: Small enough that it doesn't meaningfully widen the replay window beyond what jti tracking already closes, generous enough to absorb realistic NTP drift between two independently-operated systems.
• Alternatives considered: Zero tolerance — rejected as operationally fragile; large tolerance (e.g. 60s) — rejected as unnecessarily widening the token's effective lifetime.

Decision: Credential rotation mechanism

• Decision: ProductIntegration gains a nullable previousCredentialRef and previousCredentialExpiresAt alongside the existing credentialRef. On rotation: the current credentialRef moves to previousCredentialRef with previousCredentialExpiresAt set to "now + transition window," and a new credentialRef is issued. Token validation tries the current secret first, then the previous one (if previousCredentialExpiresAt hasn't passed).
• Rationale: This is what makes rotation zero-downtime (SC-003) without a distributed "atomic cutover" — both secrets are simultaneously valid for a bounded window, which directly satisfies Constitution Principle VII's concurrency requirement without inventing new coordination infrastructure.
• Alternatives considered: Versioned credential list (unbounded history) — rejected as more than the spec requires (only one prior credential needs to remain valid, per spec.md User Story 2's "old and new credential both valid during a transition window").

Decision: Credential storage (no secret manager exists yet in this repo)

• Decision: docs/06-database-schema.md describes credentialRef as "a pointer into secret manager, never the raw secret" — but no secret-manager integration exists anywhere in this codebase or docs/07-backend-architecture.md's stack today, and HMAC signature verification needs the actual secret value at verify time, not just a hash of it (unlike a password, which only ever needs comparison). Pragmatic resolution for this feature: credentialRef / previousCredentialRef store the secret encrypted at rest with AES-256-GCM, using a new required env var INTEGRATION_CREDENTIAL_ENCRYPTION_KEY (32-byte key, added to src/config/env.ts's Zod schema). The plaintext secret is generated once at registration/ rotation time, returned to the admin caller exactly once (never retrievable again — matches spec.md's credential lifecycle), and only its ciphertext is persisted. Decryption happens in-process, only inside the token-verification path.
• Rationale: This satisfies the spirit of "never the raw secret in the database" (plaintext is never at rest) without inventing a dependency on an external secret-manager service this repo doesn't have. It's flagged here explicitly as a placeholder: if/when a real secret manager (Vault, AWS Secrets Manager, etc.) is adopted, credentialRef becomes a genuine external reference and this encryption layer is removed — that migration is out of scope for this feature and should be called out as a follow-up, not silently implied as "done."
• Alternatives considered: Storing the secret in plaintext — rejected outright, directly contradicts docs/06 and the constitution's secrets-handling governance. Requiring an actual secret-manager integration before this feature can ship — rejected as disproportionate scope for what Phase 2 needs; no other part of the roadmap currently requires one either.

Decision: Rate limiting design (per-integration and per-user)

• Decision: Apply @fastify/rate-limit at the route level (not the single global registration currently in rate-limit.plugin.ts) for the inbound SaaS-facing route, with a custom keyGenerator returning `integration:${productIntegrationId}` for the integration-level limit and a second, stricter per-route rate-limit instance keyed by `integration:${productIntegrationId}:user:${externalUserId}` for the per-user limit. Both read their max/window from ProductIntegration-linked configuration (new fields, see data-model.md), not a hardcoded value.
• Rationale: The existing global rate-limit.plugin.ts registration (max: 1000, timeWindow: '1 minute', ungated) stays as a blanket floor for the whole API; it doesn't get removed, just supplemented — this feature's per-integration/per-user limits are strictly tighter and specific to the inbound SaaS route. keyGenerator needs the validated productIntegrationId/ externalUserId, so the rate-limit check runs in the route's handler chain after the product-integration-auth plugin's preHandler populates request.reqContext.
• Alternatives considered: A single global per-IP limit — rejected, doesn't satisfy FR-009's "per integration and independently per end user" requirement; a product's shared outbound IP would incorrectly throttle every user behind it together.

Decision: Unknown-field rejection (FR-008)

• Decision: The inbound Zod schema uses .strict() (rejects any key not explicitly defined), not the Zod default of silently stripping unknown keys.
• Rationale: FR-008 requires the entire request rejected on an unknown field, not a best-effort parse — .strict() is exactly this behavior in Zod; the default .parse() behavior (strip unknown keys silently) would violate FR-008.
• Alternatives considered: None — this is a direct, unambiguous mapping from requirement to Zod API.

Decision: Error response shape without leaking registration status (FR-010)

• Decision: "Unregistered product" and "invalid credential for a registered product" return the same generic 401 INVALID_INTEGRATION_CREDENTIAL response body and status code. "Product suspended" returns a distinguishable 403 PRODUCT_INTEGRATION_SUSPENDED (this one is safe to distinguish — a suspended product's own registered caller already knows it's registered). "Out-of-scope request" (valid credential, but tenant/user outside allowedScope) returns 403 REQUEST_OUT_OF_SCOPE.
• Rationale: This satisfies both FR-010 requirements at once: distinguishable where doing so is safe (suspended vs. scope), identical where distinguishing would leak whether an arbitrary product ID is registered at all (invalid credential vs. unregistered product).
• Alternatives considered: Fully distinguishing all four cases — rejected, directly contradicts FR-010's "without leaking whether an unregistered product ID exists."

Decision: Reconciling the placeholder Prisma schema

• Decision: The current Product model in prisma/schema.prisma (code, name, description, status: ProductStatus enum) is starter-template scaffolding, not the real domain model — it doesn't match docs/06-database-schema.md's Product shape at all (externalProductId, supportEnabled, status: String). This feature replaces it with the doc 06 shape. New models (ProductIntegration, CustomerReference) use cuid() ids matching doc 06 exactly. The existing Category, User, and AuditLog placeholder models are left alone (out of scope for this feature — Category's real shape belongs to whichever future feature builds the catalog domain properly; User/AuditLog aren't touched by this feature's requirements beyond reusing AuditLog for FR-007).
• Rationale: Phase 2 is explicitly where docs/10-implementation-roadmap.md places "Product/ProductIntegration models" — this is the correct feature to fix Product, not a scope-creep addition. Leaving Category/User alone keeps the change bounded to what this feature actually needs.
• Alternatives considered: Adding ProductIntegration pointing at the old placeholder Product shape and deferring the Product fix — rejected, would mean building ProductIntegration.product against a model with no externalProductId to validate inbound requests against, defeating the feature's own purpose.

Decision: Aligning AuditLog to doc 06's shape (discovered during implementation)

• Decision: The placeholder AuditLog model (userId, action, resource, payload) is replaced with docs/06-database-schema.md's real shape (actor, actorType, action, entityType, entityId, oldValue, newValue, reason, metadata, createdAt) — dropping its foreign key to User. actor becomes a plain string identifier (a ProductIntegration.id, an agent id, "system", etc.), not a relation.
• Rationale: Originally planned to leave AuditLog untouched and just "reuse" it (see the "Where ProductIntegration lifecycle endpoints live" decision below and plan.md's Constitution Check), but the placeholder shape has no entityType/entityId/reason fields at all — FR-007 ("record which integration/credential was involved," "reason: invalid_credential | suspended | ...") literally cannot be satisfied by the old shape. This isn't scope creep into unrelated future work — it's a direct, minimal prerequisite for this feature's own FR-007, discovered while wiring up data-model.md's AuditLog field mapping against the real schema. The dropped User relation also better matches Constitution Principle I: an audit actor shouldn't require a local User row to exist, since most actors (product integrations, external users via externalUserId, "ai") never have one.
• Alternatives considered: Keep the placeholder shape and encode entityType/entityId/ reason inside the existing free-text resource field and payload JSON — rejected as exactly the kind of unstructured workaround Constitution Principle VI's audit requirement exists to prevent; it would make audit rows unqueryable by entity without parsing payload first.

Decision: Where ProductIntegration lifecycle endpoints live

• Decision: Extend the existing src/modules/catalog/products/ module (already scaffolded with controller/service/repository/routes/schema/mapper/types) with integration lifecycle operations, rather than creating a new top-level module.
• Rationale: docs/07-backend-architecture.md's module list has no separate "product-integrations" module; docs/06-database-schema.md groups ProductIntegration under the same "Domain: Integration / Catalog" heading as Product, and it's a 1:1 relation.
• Alternatives considered: A new src/modules/platform/integrations/ addition — rejected; that module already exists for outbound webhook delivery (docs/11 gap A2, a different, future concern), and conflating inbound-trust management with outbound-webhook delivery in one module would blur a module boundary the constitution requires to stay clear (Principle III).