Skip to main content
OpenCluster authenticates a Principal, resolves the User’s sole current Organization Membership, and checks the route’s Permission before tenant-owned logic runs. Report vulnerabilities through the process in SECURITY.md; do not open a public issue containing sensitive details.

​
Authentication and authorization

The one-time local bootstrap atomically creates the first Organization, its Admin User and Membership, the local password, and an opaque cookie session. Protect and retire the file-backed bootstrap token after that use. Normal product routes use the opaque __Host-oc_session cookie. General bearer API tokens are not shipped in OSS v0.1. Unsafe cookie requests require the configured same-origin Origin; cross-origin and Origin: null requests are rejected. Roles grant fixed Permissions inside an Organization. Missing authentication returns 401, insufficient Permission returns 403, and inaccessible Organizations and unknown tenant records are indistinguishable. A User has at most one current Organization Membership. Organization Admins can create local Users and manage that Membership, but cannot replace an existing User’s password. Change your own local password with PUT /api/v1/auth/local/password, supplying currentPassword and newPassword without an Organization selector. Success deletes all your sessions, including the current one, and requires sign-in again. Passwords accept 12–1024 bytes. OIDC Users manage their credentials through their identity provider. Deployment operators can recover an existing enabled local account using its User UUID:
Run this with the deployment’s existing configuration and database access. Supply the new password only through redirected or piped stdin; terminal input and password arguments are refused. One trailing line ending is accepted. Recovery changes the password, deletes all the User’s sessions and records the action atomically. Unknown and OIDC-only accounts are refused; recovery does not create Users or reactivate bootstrap. After initial setup, remove the bootstrap credential file and configuration before restart. An omitted bootstrap credential disables initialization without preventing normal startup. Initialization stays retired even if the initial User is later deleted. Retained installations acquire this protection through a forward migration. Sessions belong to the User and store no Organization or Role. Each request resolves the User’s one current Membership, so Role changes take effect immediately and Membership removal prevents authentication without deleting identity history. Logout clears the browser cookie and deletes the current session even without a membership. Expired sessions are cleaned up automatically; audit records follow the audit retention policy. An absent or expired cookie can be cleared again. Logout still requires the configured Origin; a storage failure returns an error because durable sign-out was not confirmed.

​
Trust boundaries

The browser and product ingress share one origin. PostgreSQL holds durable product truth. Customer Relays initiate outbound, pinned sessions; the control plane never receives cluster credentials. Integration and model providers remain external trust boundaries, and their returned content is always untrusted input. Changing an Organization identifier does not change the User’s identity: the server rejects a value that does not match the current Membership before a Tool is offered or a record is read. A Kubernetes read can cross the Relay boundary only when the registered capability and namespace allow-list both permit it. Read-only Tools reduce change risk but do not make source data harmless or complete.

​
Data handling

OpenCluster stores normalized Alert Events, Incidents, Messages, Investigation events, Tool Runs, cited Findings, audit records, and draft Postmortems in PostgreSQL. Tool results are bounded and summarized for review. Conversations retain continuity through Messages and prior cited Findings. OpenCluster does not persist or expose model chain-of-thought. An Investigation can perform live authorized reads, including bounded Kubernetes container logs through Relay and Slack channel or thread messages. A configured Slack App can also send originating-thread replies. These reads and replies remain constrained by the Integration’s verified permissions and the current Organization. Retention and backup policy are deployment responsibilities in OSS. Protect backups as production data and verify retention changes against legal and operational requirements.

​
Secrets and Relay

Secrets accept a direct environment value or an optional _FILE path, never both. Startup errors omit secret values and paths. Restart after changing configuration or secret files. Inbound webhook credentials are stored as digests. Presentable Integration credentials are sealed and never returned after creation; one-time values must be stored immediately. Audit details remove credential-shaped keys. The Relay initiates its connection from the customer boundary, validates configured SPKI pins, and executes only closed protocol capabilities. Kubernetes credentials remain with the Relay and never enter the control plane. Read-only capabilities still require least-privilege Kubernetes RBAC, network controls, credential rotation, and encryption-key custody. Losing the encryption key leaves product records readable but makes sealed Integration credentials unrecoverable. Back it up separately from PostgreSQL.

​
Model-provider boundary

For an Investigation, OpenCluster may send the subject, question, bounded time window, connected Tool catalog, normalized alert context, bounded prior cited Findings, and summarized Tool results to the configured model provider. It does not send Tool credentials or publish model chain-of-thought. The provider returns Tool requests or a structured conclusion. OpenCluster validates budgets, citations, enums, and result bounds before persistence. Deployment owners must review provider retention, training, regional processing, contractual terms, and the source content allowed to cross this boundary. Deployment owners remain responsible for HTTPS, identity-provider policy, provider terms, retention, backups, and secret custody. Use Configuration to apply the shipped controls.