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

# Feature Specification: SaaS Product Integration & Inbound Request Trust

**Feature Branch**: `002-saas-integration`

**Created**: 2026-08-21

**Status**: Draft

**Input**: User description: "Phase 2 of docs/10-implementation-roadmap.md: SaaS integration —
Product/ProductIntegration models, credential validation, service-to-service auth (signed
tokens/OAuth2/mTLS), inbound request contract, rate limiting. Per docs/02-integration-and-security.md."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Every inbound request is authenticated and trusted before anything happens (Priority: P1)

A registered SaaS product's backend calls SupportHub on a customer's behalf (e.g., a customer
clicked "Help" inside the product). SupportHub validates the calling product's identity, the
credential presented, the product's current status, and the accompanying user/tenant context
against that product's registered integration and its allowed scope — before any downstream
processing occurs. A request from an unregistered product, an invalid/expired/revoked
credential, a suspended product, or context outside the credential's scope is rejected outright.

**Why this priority**: This is the trust boundary everything else in the system depends on.
Without it, SupportHub cannot safely accept "this is customer X of tenant Y using product Z" as
true, which every later phase (ticketing, AI, orchestration) relies on completely.

**Independent Test**: Send a request with a valid, correctly-scoped credential and confirm it is
accepted and its product/tenant/user context is trusted; send the same request with an invalid,
expired, or wrong-product credential and confirm it is rejected with no side effects.

**Acceptance Scenarios**:

1. **Given** a product has a registered, active integration with a valid credential, **When** it
   sends a request with that credential and in-scope context, **Then** the request is accepted
   and the product/tenant/user identity it carries is treated as trusted.
2. **Given** a request presents a credential that doesn't match any registered integration,
   **When** SupportHub validates it, **Then** the request is rejected and no ticket, session, or
   other record is created.
3. **Given** a product's integration status is "suspended," **When** a request arrives for that
   product, **Then** it is rejected with a reason distinguishable from "invalid credential" (so
   the calling product can tell the difference between "you're not registered" and "you're
   registered but temporarily disabled").
4. **Given** a request includes fields not defined in the inbound contract, **When** it is
   validated, **Then** the entire request is rejected rather than the unknown fields being
   silently ignored.
5. **Given** a request's tenant/user context doesn't fall within the presented credential's
   allowed scope, **When** it is validated, **Then** the request is rejected even though the
   credential itself is valid.

---

### User Story 2 - An admin can onboard, rotate, and revoke a product's integration credential (Priority: P2)

An operator/admin registers a new SaaS product as a SupportHub integration client, issuing it a
credential scoped to that product alone. Later, the admin can rotate that credential (issue a new
one while the old one keeps working for a defined transition window) or revoke it immediately
(e.g., on suspected compromise), without any SupportHub downtime or a deploy.

**Why this priority**: Without this, User Story 1 has nothing to validate against, and there's no
way to safely respond to a leaked credential — but it's second because a single seeded
integration is enough to prove Story 1 works end to end before onboarding/rotation tooling exists.

**Independent Test**: Register a new product integration and confirm a request using its
credential is accepted (Story 1); rotate the credential and confirm both old and new credentials
work during the transition, then only the new one after; revoke a credential and confirm the very
next request using it is rejected.

**Acceptance Scenarios**:

1. **Given** an admin registers a new product integration, **When** they issue its credential,
   **Then** that credential is scoped to that product alone — it is never valid for any other
   product's requests.
2. **Given** an active integration, **When** an admin rotates its credential, **Then** requests
   using either the old or new credential succeed until the transition window ends, after which
   only the new one works.
3. **Given** an active integration, **When** an admin revokes its credential, **Then** the next
   request using that credential is rejected, and the revocation is recorded in the audit trail.
4. **Given** any authentication attempt (success or failure) against any integration, **When** it
   occurs, **Then** it is recorded in an audit trail an admin can review — including which
   integration was involved and the outcome.

---

### User Story 3 - No single product integration or end user can overwhelm the system (Priority: P3)

Inbound requests are rate-limited both per product integration and per end user within that
integration, using limits an admin can change without a deploy. A product (or a single customer
within it) sending requests far beyond its configured limit is throttled; other integrations and
users are unaffected.

**Why this priority**: Important for production resilience and fairness across multiple
integrated products, but the system is meaningfully useful (and Stories 1-2 fully testable)
without it — this hardens an already-working trust boundary rather than enabling new behavior.

**Independent Test**: Send requests from one integration far beyond its configured rate limit and
confirm later requests in the burst are throttled while a concurrent, well-behaved second
integration's requests continue to succeed normally.

**Acceptance Scenarios**:

1. **Given** an integration has a configured rate limit, **When** it is exceeded within the
   configured window, **Then** further requests from that integration are throttled until the
   window resets.
2. **Given** two different end users under the same integration, **When** one exceeds their
   per-user limit, **Then** the other user's requests continue to succeed normally.
3. **Given** an admin changes a rate limit value, **When** the change is saved, **Then** it takes
   effect without requiring a deploy or restart.

---

### Edge Cases

- What happens when a credential is presented after its rotation transition window has fully
  elapsed? It MUST be treated identically to an already-revoked credential (rejected).
- What happens when the inbound request's signature/token appears valid but is a replay of a
  previously-used one (e.g., a captured and resent signed token)? It MUST be rejected — accepted
  service-to-service auth mechanisms must be replay-resistant (short-lived tokens with a
  nonce/timestamp check, or equivalent).
- What happens when a product has no integration configured at all (never registered)? Requests
  MUST be rejected the same way as an invalid credential, without leaking whether the product ID
  itself is known to SupportHub.
- What happens when clock skew between the calling product and SupportHub affects a
  time-bound signed token's validity window? A small, explicitly bounded tolerance is allowed;
  anything beyond it is rejected.
- What happens when an integration is rotated or revoked while a request is mid-flight? The
  in-flight request's outcome is decided by validation at the moment it's checked — no partial
  application, no race that lets a revoked credential's request complete after revocation is
  recorded.
- What happens when the same underlying customer problem is submitted twice in quick succession
  (e.g., the calling product's own client retried after a timeout)? Out of scope for this
  feature — de-duplicating retried problem reports into a single ticket depends on the `Ticket`
  entity, which doesn't exist until the ticketing feature. This feature's contract MUST still
  reserve a field for an idempotency key so that later feature can use it without a contract
  change (see Assumptions).

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: The system MUST require every SaaS product that wants support to be registered as
  a distinct integration, each with its own credential — never shared across products.
- **FR-002**: The system MUST validate, on every inbound request before any downstream
  processing: the calling product's identity, the presented credential, the product's current
  status (active/suspended/deprecated), the accompanying user/tenant context, and the
  credential's allowed scope.
- **FR-003**: The system MUST reject a request whose product, tenant, or user values are not
  corroborated by the validated integration and its scope — a caller-supplied ID is never trusted
  by itself.
- **FR-004**: The system MUST support at least one production-appropriate, replay-resistant
  service-to-service authentication mechanism (signed short-lived scoped tokens, OAuth2
  client-credentials, or mTLS), selectable per integration.
- **FR-005**: The system MUST support rotating an integration's credential with a defined
  transition window in which both the old and new credential are valid, with zero downtime.
- **FR-006**: The system MUST support revoking an integration's credential with immediate effect
  on the next request.
- **FR-007**: The system MUST audit every authentication attempt (success and failure), recording
  which integration/credential was involved, without ever recording the raw credential value
  itself.
- **FR-008**: The system MUST reject any inbound request containing fields outside the defined
  contract, rather than silently accepting or ignoring them.
- **FR-009**: The system MUST rate-limit inbound requests per integration and independently per
  end user within an integration, with limit values configurable without a deploy.
- **FR-010**: The system MUST distinguish, in its rejection response, between "unregistered/
  invalid credential," "suspended product," and "out-of-scope request" where doing so does not
  leak whether an unregistered product ID exists in the system.
- **FR-011**: The system MUST let an admin change an integration's status (active/suspended/
  deprecated) and have that change take effect on the very next request, without a deploy.
- **FR-012**: The inbound request contract MUST include an optional idempotency-key field,
  reserved for the ticketing feature's future use, even though this feature does not implement
  deduplication against it.

### Key Entities

- **Product Integration**: One SaaS product's registration with SupportHub — its identity,
  current status, credential reference, chosen authentication mechanism, allowed scope, and
  rotation/revocation timestamps. Exactly one per product; never shared.
- **Customer Reference**: The external user/tenant identifiers a validated request carries,
  scoped to the Product Integration that vouched for them — a reference into the SaaS's own
  identity system, never a second copy of it (per Constitution Principle I).
- **Authentication Audit Event**: A record of one authentication attempt (success or failure)
  against a Product Integration, including outcome and timestamp, but never the raw credential.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 100% of inbound requests presenting an invalid, unregistered, expired, or
  out-of-scope credential are rejected before any downstream record is created.
- **SC-002**: Revoking a credential stops it from being accepted on the very next request after
  revocation — no propagation delay beyond normal request processing.
- **SC-003**: Rotating a credential causes zero failed requests for a well-behaved caller using
  either the old or new credential during the transition window.
- **SC-004**: An admin can retrieve a complete authentication audit trail (success and failure)
  for any given integration on demand.
- **SC-005**: An integration or user sending requests at 10x its configured rate limit is
  measurably throttled while unrelated integrations/users see no change in their own success
  rate.
- **SC-006**: Onboarding a new SaaS product as an integration requires no code change or
  deploy — it is a configuration/data action only.

## Assumptions

- This feature covers the trust boundary and its own admin/audit surface only. It does not
  implement ticket creation, the AI agent, or any business logic beyond validating and scoping an
  inbound request — those are later features per the roadmap (Phases 3-5+).
- The idempotency key reserved in FR-012 is deliberately not enforced here (no `Ticket` entity
  exists yet to deduplicate against) — this is a forward-compatibility placeholder so the
  ticketing feature doesn't need a breaking contract change later, per the gap noted in
  `docs/11-architect-additions-gaps-and-recommendations.md` §A1.
- "Rate limiting... configurable without a deploy" follows Constitution Principle II
  (configuration over hardcoding) — exact default limit values are a
  `REQUIRES BUSINESS CONFIRMATION` item per `docs/10-implementation-roadmap.md`, not invented
  here.
- Choice of authentication mechanism (signed tokens vs. OAuth2 vs. mTLS) per integration, and the
  credential rotation transition-window length, are technical decisions deferred to
  `/speckit-plan` — this spec only requires that *a* production-appropriate, replay-resistant
  mechanism exists and that rotation/revocation behave as described.