ms2k/remora
SHA256
Watch
0
Code Releases Activity

Harden WebBFF and deployment release behavior

Browse source 
Model fail-closed cross-replica session renewal and implement owner-fenced refresh, transient observer handling, logout fencing, and graceful shutdown. Remove chart-owned Ingress while retaining qualification-owned external routing.
This commit is contained in:
ms2k 2026-07-20 17:09:26 +09:00
commit 414b380516
1 changed files with 980 additions and 136 deletions
Download patch file Download diff file Expand all files Collapse all files

18
docs/spec/architecture.md
View file

@ -22,6 +22,7 @@ Terms in this glossary are stable identifiers for use across Remora documentatio
| `WebClient` | The browser-based user interface for submitting and managing jobs. |
| `WebBFF` | The same-origin confidential OAuth client and token-mediating backend for `WebClient`. |
| `WebSession` | Ephemeral server-side OAuth session state addressed by an opaque browser cookie. |
| `WebSessionProtocol` | The TLA+ specification defining distributed browser-session renewal semantics and their safety and liveness properties. |
| `API` | The authenticated service interface for job submission, status, cancellation, history, and deletion. |
| `Worker` | A stateless process that executes attempts and reports progress and outcomes. |
| `IdentityProvider` | The external authority for user identity, administrative roles, and storage authorization scopes. |
@ -35,9 +36,14 @@ Terms in this glossary are stable identifiers for use across Remora documentatio
## Scope
This document is authoritative for Remora's product requirements, system boundaries, major components, result representation and access contract, and allocation of responsibilities below the abstraction of `JobProtocol`. It intentionally does not define implementation-level technology choices.
This document is authoritative for Remora's product requirements, system boundaries, major components, result representation and access contract, and allocation of responsibilities below the protocol models' abstractions. It intentionally does not define implementation-level technology choices.
[`Remora.tla`](../protocol/Remora.tla) is the authoritative `JobProtocol`. This document references its symbols without restating their definitions or actions; where they overlap, the model controls. Concrete frameworks, libraries, wire formats, mutable API descriptions, and deployment choices are outside the scope of this specification.
[`Remora.tla`](../protocol/Remora.tla) is the authoritative `JobProtocol`, and
[`WebSessionRenewal.tla`](../protocol/WebSessionRenewal.tla) is the authoritative
`WebSessionProtocol`. This document references their symbols without restating
their definitions or actions; where they overlap, the models control. Concrete
frameworks, libraries, wire formats, mutable API descriptions, and deployment
choices are outside the scope of this specification.
## Problem Statement
@ -108,7 +114,7 @@ flowchart TD
- `WebBFF` uses the OAuth authorization-code flow as a confidential client with Proof Key for Code Exchange and nonce validation. OAuth and OpenID Connect remain the only user-authentication path.
- Access tokens, refresh tokens, and ID tokens remain inside `WebBFF` and its protected `WebSession` store. Browser JavaScript receives only an authorization snapshot and a CSRF value.
- The browser carries a random session identifier in a host-only `__Host-` cookie with `Secure`, `HttpOnly`, `SameSite=Strict`, and `Path=/`. Authentication creates both the session identifier and CSRF value. Token renewal rotates the identifier while retaining the CSRF value for in-flight same-session requests; an identity change invalidates the session.
- The browser carries a random session identifier in a host-only `__Host-` cookie with `Secure`, `HttpOnly`, `SameSite=Strict`, and `Path=/`. Authentication creates both the session identifier and CSRF value. The authorization callback rotates the identifier before establishing the authenticated session. Renewal and concurrent-observer behavior refine `WebSessionProtocol`. An identity change invalidates the session.
- `WebSession` state is stored under a deployment-specific, WebBFF-only namespace in `CoordinationStore`. Its lifetime is bounded by the provider session and token lifetimes. Loss, expiry, unreadable state, or failed renewal destroys the local session and requires authentication again.
- Unsafe same-origin requests require the current session CSRF value in a request header. `WebBFF` also rejects unsafe requests with an absent or foreign `Origin` or a cross-site Fetch Metadata classification. SameSite cookies are defense in depth rather than the sole CSRF control.
- Browser API requests use a same-origin BFF route. `WebBFF` removes browser credentials and forwarding headers, injects the current access token, preserves idempotency keys and response status, and never retries an unsafe application request.
@ -267,9 +273,9 @@ flowchart TD
## Responsibility Boundaries
- [`docs/protocol`](../protocol/) is authoritative for distributed state and coordination semantics, including safety and liveness invariants.
- This architecture specification is authoritative for components, trust boundaries, externally visible behavior, and responsibility allocation below the model's abstraction, and must conform to `JobProtocol` where they overlap.
- Implementations may optimize storage layout but must refine `JobProtocol` behavior and preserve its linearization points.
- Mutable implementation contracts and documentation select technologies, wire shapes, and mappings from architectural components. They are not normative over `JobProtocol` or this specification.
- This architecture specification is authoritative for components, trust boundaries, externally visible behavior, and responsibility allocation below the models' abstractions, and must conform to the applicable protocol where they overlap.
- Implementations may optimize storage layout but must refine the applicable protocol behavior and preserve its linearization points.
- Mutable implementation contracts and documentation select technologies, wire shapes, and mappings from architectural components. They are not normative over the protocol models or this specification.
- Deployment configuration supplies service credentials and endpoints, configures allowed source reachability, and provides infrastructure-level egress enforcement.
- Deployment configuration reserves and protects Remora's internal target namespace, excludes it from independent lifecycle deletion, and establishes either exclusive write ownership or immutable version addressing.
- Deployment configuration selects secret-store topology and policies while preserving the application-level grant-bound credential-resolution contract.