From 8a36422238de57018ab077095017d812b4b226f8 Mon Sep 17 00:00:00 2001 From: Brandon Corbett Date: Sun, 5 Jul 2026 20:04:15 -0400 Subject: [PATCH] docs: define trusted server adapter and add deployment topology Add a Deployment Topology section to the architecture guide with a Mermaid diagram (browser -> adapter -> API -> Postgres) and a concrete definition of the trusted server adapter: what it is, why it is trusted, and its responsibilities (cookie/Bearer bridging, service token, JWKS verification). The term was referenced throughout the docs but never defined. Cross-links ecosystem.md. --- docs/architecture.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index 6486f5a..bae4238 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -11,6 +11,46 @@ Seamless Auth API is an Express and TypeScript authentication service backed by - Models: Sequelize models for users, credentials, sessions, system config, auth events, organizations, TOTP credentials, and OAuth identities. - Postgres: source of truth for users, credentials, sessions, config, and audit records. +## Deployment Topology + +This API is one component in a small system. It speaks a single Bearer/JSON contract and never +sets or reads browser cookies. Browser apps do not call it directly in the recommended setup; +a trusted server adapter sits in between. + +```mermaid +flowchart LR + browser["Browser
(@seamless-auth/react)"] + adapter["Trusted server adapter
(@seamless-auth/express / core)"] + api["This API
(seamless-auth-api)"] + db[("Postgres")] + + browser -- "cookies
credentials: include" --> adapter + adapter -- "Bearer + service token
JSON, no cookies" --> api + adapter -- "JWKS verify
/.well-known/jwks.json" --> api + api --> db +``` + +**Trusted server adapter.** A server-side component (not the browser) that holds token custody +and bridges the two auth styles. In the SeamlessAuth ecosystem this is +`@seamless-auth/express` / `@seamless-auth/core`, but any backend you control can play the role. +It is "trusted" because it runs in your infrastructure, holds the session cookies +(`seamless-access`, `seamless-refresh`, `seamless-ephemeral`) on the browser side, and is the +only party that presents this API's service token. Its responsibilities: + +- Terminate the browser's cookie-based session and translate it into an `Authorization: Bearer` + header for this API. +- Attach the service token (`x-seamless-service-token`) and forwarded client IP + (`x-seamless-client-ip`) on calls that require them. +- Verify access-token signatures against this API's JWKS (`/.well-known/jwks.json`, RS256). + +Direct browser-to-API integration is possible (see the "Direct HTTP APIs (advanced)" path in the +README) but unsupported for cookie-based browser sessions, because this API issues tokens only in +JSON bodies and expects the caller to hold them securely. Keeping token custody in the adapter is +the recommended path. + +For the full dependency and contract-coupling map across sibling repositories, see +[ecosystem.md](./ecosystem.md). + ## Request Flow 1. Express receives a request and applies global middleware.