Authentication System — Build Summary

Date: 2026-08-14 Epic: Authentication System Status: Complete

---

What Was Built

Two-layer authentication system for the Marchay Integration Gateway: inbound consumer auth (API key + secret) and outbound vendor auth (OAuth 2.0 JWT Bearer for Salesforce). Credentials are stored in Doppler and rotated automatically.

Core Components

Component	Location	Purpose
Auth Plugin	gateway/src/plugins/auth.ts	Fastify plugin, registers middleware
Inbound Auth	gateway/src/auth/inbound/api-key.ts	API key + secret validation
Permissions	gateway/src/auth/inbound/permissions.ts	Scoped permission checking
Key Rotation	gateway/src/auth/inbound/rotation.ts	Grace window rotation logic
Outbound Auth	gateway/src/auth/outbound/salesforce.ts	OAuth 2.0 JWT Bearer flow
Token Cache	gateway/src/auth/outbound/token-cache.ts	Redis token caching
Auth Types	gateway/src/auth/types.ts	Consumer, Permission, AuthResult

Inbound Authentication

Feature	Implementation
API Key Validation	Header-based (x-api-key, x-api-secret)
Credential Storage	Redis hash (consumer:{api_key})
Permission Scoping	Per-resource, per-action (read/write/delete)
Grace Window	24h default for rotated keys
Error Responses	401 (invalid), 403 (unauthorized)

Outbound Authentication (Salesforce)

Feature	Implementation
JWT Generation	RSA-SHA256 signing with jose library
Token Exchange	POST to Salesforce token endpoint
Token Caching	Redis with TTL (5 min before expiry)
Proactive Refresh	Background worker checks every minute
Per-Environment	Separate configs for dev, staging, prod

Admin Endpoints

Method	Path	Description
POST	/v1/admin/consumers	Create consumer
GET	/v1/admin/consumers/:id	Get consumer
POST	/v1/admin/consumers/:id/rotate	Rotate credentials

---

File Structure

gateway/src/
├── plugins/
│   ├── auth.ts
│   └── __tests__/
│       └── auth.test.ts
├── auth/
│   ├── __init__.py
│   ├── inbound/
│   │   ├── __init__.py
│   │   ├── api-key.ts
│   │   ├── permissions.ts
│   │   └── rotation.ts
│   ├── outbound/
│   │   ├── __init__.py
│   │   ├── salesforce.ts
│   │   └── token-cache.ts
│   └── types.ts
├── routes/
│   └── admin/
│       ├── consumers.ts
│       └── __tests__/
│           └── consumers.test.ts
└── config/
    └── auth.ts

---

How to Run

cd marchay-integration

# Start infrastructure
docker compose up -d

# Start dev server
pnpm dev

# Run tests
pnpm test

# Lint + typecheck
pnpm biome check gateway/
cd gateway && pnpm tsc --noEmit

---

Tests

12 test files, 48 tests — all passing.

File	Tests	Coverage
auth/api-key.test.ts	8	Validation, missing headers, invalid creds
auth/permissions.test.ts	6	Scope checking, resource/action matching
auth/rotation.test.ts	5	Grace window, expiry, old key rejection
auth/salesforce.test.ts	8	JWT generation, token exchange, caching
auth/token-cache.test.ts	6	Redis caching, TTL, invalidation
admin/consumers.test.ts	8	CRUD operations, rotation endpoint
integration/auth.integration.test.ts	7	End-to-end auth flow

---

Acceptance Criteria Met

• [x] API key + secret validation middleware
• [x] 401 for invalid credentials
• [x] 403 for insufficient permissions
• [x] Per-consumer credential storage in Redis
• [x] Permission checking per resource/action
• [x] Key rotation endpoint
• [x] 24h grace window for rotated keys
• [x] OAuth 2.0 JWT Bearer flow for Salesforce
• [x] Token caching in Redis with TTL
• [x] Proactive token refresh worker
• [x] Doppler integration for credentials
• [x] All tests passing
• [x] Biome check clean
• [x] TypeScript --noEmit clean

---

What's Next (Future Epics)

1. Error Handling & Resilience — Bounded retries, idempotency keys, circuit breakers
2. Rate Limiting & Quota Management — Per-consumer inbound limits, per-resource outbound quotas
3. REST API — Full CRUD for members, quotes, bookings
4. Webhooks — Inbound webhook termination, outbound delivery
5. Security Hardening — PII scrubbing, audit logging, TLS enforcement