Merge main into wait-cmd: combine the wait command with chat-persistence pairing

Brings main (chat-persistence: OpenCode pairing, protocol status, server
websocket/status changes) up to date on this branch so it can land without
conflict. Auto-merged with no conflicts; no comment or intent from either side
was dropped. Re-ran build, vet, gofmt and the full test suite after the merge -
all pass.
This commit is contained in:
2026-10-18 01:11:31 +01:00
10 changed files with 880 additions and 41 deletions
+60 -26
View File
@@ -15,6 +15,7 @@ import (
"git.a-wan.net/alan/pipelines/internal/opencode"
"git.a-wan.net/alan/pipelines/internal/paths"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/server"
"git.a-wan.net/alan/pipelines/internal/summarise"
)
@@ -47,17 +48,6 @@ func main() {
// harness; the summariser falls back to the prompt's first line, so title
// generation never blocks or fails run creation.
options := server.Options{ArtifactsRoot: artifactsRoot, RunTitles: summarise.GenerateTitle, StepVerdicts: summarise.GenerateVerdictReason}
// Chat brokers OpenCode over one endpoint. By default OpenChat detects the
// installed CLI and starts the single owned serve process for it: the native
// wire for v1, and the V2 API for the installed V2 CLI (which exposes the
// authenticated SSE firehose at /api/event). When the operator configured an
// endpoint (flag, environment or a previously recorded choice) chat is
// brokered from that endpoint instead: it is validated once, an unreachable or
// non-OpenCode endpoint is a clear refusal and never falls back to a spawned
// instance, and nothing is started locally. Only a URL-bearing, SSE-capable
// connection enables chat; otherwise chat stays disabled and every chat_*
// request is answered with a protocol error naming the missing configuration
// rather than hanging.
recorded := ""
if value, err := store.OpenCodeEndpoint(ctx); err != nil {
log.Printf("OpenCode endpoint setting unreadable: %v", err)
@@ -65,28 +55,72 @@ func main() {
recorded = value
}
reference := opencode.ResolveEndpointRef(*endpoint, os.Getenv(opencode.EndpointEnvKey), recorded)
// Chat brokers OpenCode over one endpoint. When the operator configured an
// endpoint (flag, environment or a previously recorded choice) the broker
// attaches to it: it uses the password-file credential if one was supplied,
// otherwise it pairs once with the operator's local OpenCode service
// credential, stores the paired token owner-only beside the pipeline
// database and reuses it across restarts. An endpoint that cannot be
// attached is a log line and a status note, and chat then falls back to the
// server's own OpenCode instance rather than staying refused. Only a
// URL-bearing, SSE-capable connection enables chat; otherwise chat stays
// disabled and every chat_* request is answered with a protocol error naming
// the missing configuration rather than hanging.
openCodeStatus := protocol.ServiceStatus{Health: "unavailable"}
if reference != "" {
password, err := opencode.ReadEndpointCredentialFile(os.Getenv(opencode.EndpointPasswordFileEnvKey))
if err != nil {
log.Printf("OpenCode chat unavailable: %v", err)
} else if conn, err := opencode.OpenEndpoint(ctx, reference, password); err != nil {
log.Printf("OpenCode chat unavailable: %v", err)
explicit, explicitErr := opencode.ReadEndpointCredentialFile(os.Getenv(opencode.EndpointPasswordFileEnvKey))
if explicitErr != nil {
log.Printf("OpenCode endpoint password file unreadable: %v", explicitErr)
}
// The pair bootstrap (the operator's local service credential) is only
// needed when no explicit password was supplied; a password-file setup
// therefore logs nothing here.
bootstrap := ""
if explicit == "" {
setting, _ := opencode.ServiceCredentialPath()
value, bootstrapErr := opencode.ReadServiceCredential(setting)
if bootstrapErr != nil {
log.Printf("OpenCode local service credential unreadable: %v", bootstrapErr)
}
bootstrap = value
}
credentialPath := filepath.Join(filepath.Dir(*db), "opencode-endpoint.json")
attach, attachErr := opencode.OpenEndpointAttached(ctx, reference, explicit, bootstrap, credentialPath)
if attachErr != nil {
log.Printf("OpenCode endpoint %s could not be attached (%v); falling back to the server's own OpenCode instance", reference, attachErr)
openCodeStatus = protocol.ServiceStatus{Health: "fallback", URL: reference}
} else {
options.Chat = opencode.NewChat(conn)
defer conn.Close()
options.Chat = opencode.NewChat(attach.Connection)
defer attach.Connection.Close()
openCodeStatus = protocol.ServiceStatus{Health: "endpoint", URL: reference}
if attach.Note != "" {
log.Printf("OpenCode endpoint %s: %s", reference, attach.Note)
}
if err := store.RecordOpenCodeEndpoint(ctx, reference); err != nil {
log.Printf("record OpenCode endpoint: %v", err)
}
}
} else if conn, err := opencode.OpenChat(ctx, opencode.Executable(), ""); err != nil {
log.Printf("OpenCode chat unavailable: %v", err)
} else if conn.URL == "" {
conn.Close()
log.Printf("OpenCode chat unavailable: the connection exposes no streamable event endpoint")
} else {
options.Chat = opencode.NewChat(conn)
defer conn.Close()
}
if options.Chat == nil {
if conn, err := opencode.OpenChat(ctx, opencode.Executable(), ""); err != nil {
log.Printf("OpenCode chat unavailable: %v", err)
} else if conn.URL == "" {
conn.Close()
log.Printf("OpenCode chat unavailable: the connection exposes no streamable event endpoint")
} else {
options.Chat = opencode.NewChat(conn)
defer conn.Close()
if openCodeStatus.Health == "unavailable" {
openCodeStatus = protocol.ServiceStatus{Health: "spawned", URL: conn.URL}
}
}
}
// If neither the endpoint nor the spawned instance enabled chat, report that
// honestly rather than claiming the fallback is serving chat.
if options.Chat == nil && openCodeStatus.Health != "endpoint" {
openCodeStatus.Health = "unavailable"
}
options.OpenCodeStatus = openCodeStatus
srv := &http.Server{Addr: *addr, Handler: server.HandlerWithOptions(ctx, options, store), ReadHeaderTimeout: 5 * time.Second}
defer server.WaitRuns(srv.Handler)
go func() {
+115
View File
@@ -0,0 +1,115 @@
# Chat persistence: attach to the operator's own OpenCode by pairing, and fall back honestly
## What this item changed
Brokered chat could already be pointed at an operator-supplied OpenCode endpoint
(`-opencode-endpoint` / `PIPELINES_OPENCODE_ENDPOINT`), but pointing it at the
operator's running V2 service failed closed: the V2 API authenticates every
request with HTTP Basic auth (fixed user `opencode` plus a password), the broker
had no credential, so the health probe answered 401, startup logged
`OpenCode chat unavailable: OpenCode endpoint … is unreachable or is not an
OpenCode service`, and chat was disabled entirely.
Established from the installed binary (`opencode v2.0.20`), not from docs:
- `opencode --help` lists `api`, `pair`, `serve`, `service`, `auth`; `pair` is
"Print one-time links to connect a browser or app".
- `GET /api/info` unauthenticated → `401`, `www-authenticate: Basic realm="Secure Area"`.
- Basic auth user `opencode` with the password from `~/.local/state/opencode/service.json`
(`opencode service start` writes it, mode 0600) → `200`.
- `POST /api/pair` (authenticated) → `{"code":"…","expires_in":300}`;
`GET /auth/connect/{code}` (unauthenticated, single use) → `{"token":"…"}`.
The returned token is then accepted as the Basic password with user
`opencode`; it is not a bearer token, a cookie or an api-key header.
Changes:
- `internal/opencode/pair.go` (new): `PairEndpoint` performs the pair exchange
(`POST /api/pair` then `GET /auth/connect/{code}`) over the shared
`nativeRequest` transport, so it keeps the same auth, bounds and JSON checks;
`ReadServiceCredential` reads the operator's local service password (private
file rule); `OpenEndpointAttached` resolves the credential in precedence order
— explicit password file, a paired token stored by an earlier run, then a
fresh pairing bootstrapped by the local service credential — stores the token
in an owner-only file and re-pairs once when a stored token is refused (401).
The paired token is written 0600 through a temp file and rename and is never
logged.
- `internal/opencode/endpoint.go`: `OpenEndpoint` now wraps `probeEndpoint`,
which returns the connection even on failure; `Connection.unauthorized`
(set by the request paths on HTTP 401, cleared per probe) lets the attach tell
an authentication refusal from any other refusal.
- `cmd/pipelines-server/main.go`: the endpoint attach uses
`OpenEndpointAttached` with the paired-credential file beside the pipeline
database (`<db dir>/opencode-endpoint.json`). An endpoint that cannot be
attached logs a line naming it and **falls back to the server's own OpenCode
instance** instead of leaving chat refused.
- `internal/protocol/status.go`, `internal/server/websocket.go`: `get_status`
gains an `opencode` object (`health` = `endpoint` | `fallback` | `spawned` |
`unavailable`, plus the endpoint `url`), the honest status evidence for the
fallback. `Options.OpenCodeStatus` carries it; no credential is ever placed
there.
- Tests: `internal/opencode/pair_test.go`, `internal/protocol/status_test.go`,
a `TestStatusReportsOpenCodeAttachment` case in `internal/server/status_test.go`.
## Verification (17 Oct 2026)
Scratch server only, deployed server untouched; `go build ./... && go vet ./...`
and `gofmt -l .` clean; `go test ./internal/... ./cmd/...` green. Live check with
`-addr 127.0.0.1:<free>` and `-db <scratch>/pipelines.db`,
`PIPELINES_OPENCODE_ENDPOINT=http://127.0.0.1:49374`:
- `get_status` → `{"opencode":{"health":"endpoint","url":"http://127.0.0.1:49374"}}`;
`<scratch>/opencode-endpoint.json` written mode `-rw-------`.
- `chat_sessions` (empty registry) → 0 sessions; `chat_adopt ses_eb3c685f0ffe…`
(an operator session) → recorded; `chat_create <scratch dir>` → a new operator
session; `chat_sessions` → both.
- `chat_prompt` on the created session → `turn completed: 4 frame(s), 1 text
frame(s)`; `chat_messages` → 2 turns.
- **Restart**: stopped the scratch server (SIGTERM), started it again on the
same database. `get_status` → `endpoint`; `chat_sessions` → the same 2
sessions; `chat_messages` → the same 2 turns; the paired-credential file's
mtime and size were unchanged, so the stored token was reused, not re-paired.
- Fallback: `PIPELINES_OPENCODE_ENDPOINT=http://127.0.0.1:1` → log
`OpenCode endpoint http://127.0.0.1:1 could not be attached (…); falling back
to the server's own OpenCode instance`, and `get_status` →
`{"opencode":{"health":"fallback","url":"http://127.0.0.1:1"}}` with chat
still served by the spawned instance.
Not verified: whether the V2 service rotates/invalidates paired tokens across a
restart of **the service itself** (the operator's service was never restarted);
whether a containerised/remote Pipelines server can reach the local
`service.json` bootstrap (it cannot, so it would need the password-file path).
## Shared documents this change makes stale
The note is written here rather than edited in place; the `docs-fold` writer
should update these when it next folds notes.
- `docs/cli.md:354` — the `### Choosing the endpoint` section says a failure
"disable[s] chat … never a silent fallback". It should now say: the broker
authenticates to a V2 endpoint by pairing (`POST /api/pair` then
`GET /auth/connect/{code}`) using the operator's local OpenCode service
credential as bootstrap, stores the paired token owner-only
(`opencode-endpoint.json` beside the database), reuses it across restarts and
re-pairs once when it is refused; an explicit
`PIPELINES_OPENCODE_ENDPOINT_PASSWORD_FILE` still wins; and an endpoint that
cannot be attached logs the reason and **falls back to the server's own
OpenCode instance** rather than disabling chat.
- `docs/cli.md` — the `get_status`/`status` description should document the new
`opencode` object (`health` = `endpoint`|`fallback`|`spawned`|`unavailable`,
`url`), which is where an unattachable endpoint is reported.
- `internal/author/skill/references/operations.md:289` — the endpoint paragraph
repeats the same "clear refusal and no fallback" wording and the
password-file/username-only credential story; update it for pairing, the
stored paired token and the honest fallback, and add the `opencode` status
field. Add a dated evidence bullet naming the new tests and the restart check.
## Not stale
- `internal/author/install.go`'s managed file inventory: no reference file is
added.
- `internal/installation/service.go`: no new environment variable, so the
autostart variable list and the credential-file handling are unchanged.
- `internal/server/AGENTS.md` already points at `cmd/pipelines-server/main.go`
for the endpoint choice and at `internal/server/chat_*.go`; no new area-map
entry is needed.
+11
View File
@@ -42,6 +42,11 @@ type Connection struct {
LastHTTPStatus int
LastHTTPOperation string
MessageReadbackDiagnostic string
// unauthorized records that at least one request through this connection was
// refused with HTTP 401, so an attach that probed both backend families can
// tell an authentication refusal (worth re-pairing) from any other refusal.
// It is set only by the request path and cleared by the attach probe.
unauthorized bool
}
// Reference records only our ephemeral loopback service credentials, never provider auth.
@@ -356,6 +361,9 @@ func (c *Connection) nativeRequest(ctx context.Context, method, path string, bod
}
defer response.Body.Close()
c.LastHTTPStatus = response.StatusCode
if response.StatusCode == http.StatusUnauthorized {
c.unauthorized = true
}
if response.StatusCode < 200 || response.StatusCode >= 300 {
// The stage adapter stores bounded, redacted failure evidence separately;
// the public error string remains free of provider bodies and credentials.
@@ -409,6 +417,9 @@ func (c *Connection) EventStream(ctx context.Context) (io.ReadCloser, error) {
return nil, fmt.Errorf("OpenCode event stream request failed")
}
if response.StatusCode < 200 || response.StatusCode >= 300 {
if response.StatusCode == http.StatusUnauthorized {
c.unauthorized = true
}
evidence, _ := io.ReadAll(io.LimitReader(response.Body, 16<<10))
response.Body.Close()
return nil, fmt.Errorf("OpenCode event stream failed (HTTP %d): %s", response.StatusCode, strings.TrimSpace(string(evidence)))
+29 -12
View File
@@ -7,7 +7,6 @@ import (
"net/url"
"os"
"strings"
"syscall"
"time"
)
@@ -64,15 +63,15 @@ func ReadEndpointCredentialFile(path string) (string, error) {
if strings.TrimSpace(path) == "" {
return "", nil
}
info, err := os.Lstat(path)
if err != nil {
return "", fmt.Errorf("cannot read the OpenCode endpoint password file")
}
if !info.Mode().IsRegular() || info.Mode().Perm() != 0600 || info.Size() > endpointPasswordFileLimit {
return "", fmt.Errorf("invalid OpenCode endpoint password file")
}
if stat, ok := info.Sys().(*syscall.Stat_t); !ok || stat.Uid != uint32(os.Getuid()) {
return "", fmt.Errorf("the OpenCode endpoint password file belongs to another user")
if err := checkPrivateFile(path, endpointPasswordFileLimit); err != nil {
switch {
case os.IsNotExist(err):
return "", fmt.Errorf("cannot read the OpenCode endpoint password file")
case strings.Contains(err.Error(), "another user"):
return "", fmt.Errorf("the OpenCode endpoint password file belongs to another user")
default:
return "", fmt.Errorf("invalid OpenCode endpoint password file")
}
}
data, err := os.ReadFile(path)
if err != nil {
@@ -88,6 +87,20 @@ func ReadEndpointCredentialFile(path string) (string, error) {
// backend-specific health contract, then a streamable event path) and every
// failure names the endpoint; there is no fallback and no retry loop.
func OpenEndpoint(ctx context.Context, rawURL, password string) (*Connection, error) {
conn, err := probeEndpoint(ctx, rawURL, password)
if err != nil {
return nil, err
}
return conn, nil
}
// probeEndpoint is the shared body of OpenEndpoint. Unlike OpenEndpoint it
// returns the connection even when the probe fails, so a caller that supplied a
// credential can tell an authentication refusal (Connection.unauthorized, set on
// HTTP 401) from any other refusal without a second probe or a second judgement
// of the endpoint contract. A caller that does not care discards the connection
// through OpenEndpoint.
func probeEndpoint(ctx context.Context, rawURL, password string) (*Connection, error) {
base, err := NormalizeEndpointURL(rawURL)
if err != nil {
return nil, err
@@ -99,6 +112,10 @@ func OpenEndpoint(ctx context.Context, rawURL, password string) (*Connection, er
models: map[string]map[string]string{},
responses: map[string][]byte{},
}
// A fresh probe judges this connection's credential only: any 401 recorded
// here belongs to the password supplied now, not to a connection reused
// across a re-pair.
conn.unauthorized = false
probeCtx, cancel := context.WithTimeout(ctx, endpointProbeTimeout)
defer cancel()
switch {
@@ -107,7 +124,7 @@ func OpenEndpoint(ctx context.Context, rawURL, password string) (*Connection, er
case conn.probeHealth(probeCtx, "v1") == nil:
conn.Backend = "v1"
default:
return nil, fmt.Errorf("OpenCode endpoint %s is unreachable or is not an OpenCode service", base)
return conn, fmt.Errorf("OpenCode endpoint %s is unreachable or is not an OpenCode service", base)
}
// Require a streamable event endpoint before the endpoint is accepted: a
// healthy service without SSE cannot broker chat, so it is a clear refusal,
@@ -116,7 +133,7 @@ func OpenEndpoint(ctx context.Context, rawURL, password string) (*Connection, er
defer cancelStream()
body, err := conn.EventStream(streamCtx)
if err != nil {
return nil, fmt.Errorf("OpenCode endpoint %s exposes no streamable event endpoint: %w", base, err)
return conn, fmt.Errorf("OpenCode endpoint %s exposes no streamable event endpoint: %w", base, err)
}
body.Close()
return conn, nil
+332
View File
@@ -0,0 +1,332 @@
package opencode
import (
"context"
"encoding/json"
"fmt"
"net/url"
"os"
"path/filepath"
"strings"
"syscall"
)
// The V2 OpenCode service authenticates every /api request with HTTP Basic
// auth: the fixed user "opencode" (unless PIPELINES_OPENCODE_ENDPOINT_USERNAME
// overrides it) and a password. A client that does not already hold the
// service password obtains its own by pairing: POST /api/pair returns a
// single-use code and GET /auth/connect/{code} returns the paired token, which
// is then sent as the Basic password exactly like the service password. There
// is no bearer or api-key header, verified against the installed 2.0.20 binary
// (`opencode api POST /api/pair`, then an unauthenticated `curl` of the
// `/auth/connect/{code}` link `opencode pair` prints).
//
// The broker pairs once, stores the token in an owner-only file beside the
// other Pipelines configuration, and reuses it. The bootstrap for the pair call
// is the operator's own local service credential (the file `opencode service
// start` writes); it is read, never stored and never logged.
// OpenCodeServiceStateEnvKey overrides the directory holding the OpenCode
// service state file. It is the XDG state location, so the usual override
// applies for tests and for a service that keeps its state elsewhere.
const OpenCodeServiceStateEnvKey = "XDG_STATE_HOME"
// serviceCredentialLimit bounds the service state file read.
const serviceCredentialLimit = 64 << 10
// EndpointAttach is the outcome of attaching the chat broker to the operator's
// OpenCode endpoint: the ready, non-owning connection plus exactly how the
// credential was obtained, so the caller can report the attach (and any
// non-fatal caveat) without ever touching the credential itself.
type EndpointAttach struct {
Connection *Connection
// Mode is "password-file" when the operator supplied the Basic password
// directly, "paired" when a token from this run's pairing was stored, and
// "paired-stored" when a token stored by an earlier run was reused.
Mode string
// Note carries a non-fatal caveat such as a paired credential that could not
// be persisted; empty when there is none. It never contains a credential.
Note string
}
// OpenCodeStateDirectory is the directory `opencode` keeps its service state
// (including service.json, the owner-only file `opencode service start`
// writes) in: $XDG_STATE_HOME/opencode or the XDG default
// ~/.local/state/opencode.
func OpenCodeStateDirectory() (string, error) {
if dir := strings.TrimSpace(os.Getenv(OpenCodeServiceStateEnvKey)); dir != "" {
return filepath.Join(dir, "opencode"), nil
}
home, err := os.UserHomeDir()
if err != nil {
return "", err
}
if home == "" {
return "", fmt.Errorf("operator home directory is empty")
}
return filepath.Join(home, ".local", "state", "opencode"), nil
}
// ServiceCredentialPath is the local OpenCode service state file the pair
// bootstrap reads. It is the operator's own machine configuration.
func ServiceCredentialPath() (string, error) {
dir, err := OpenCodeStateDirectory()
if err != nil {
return "", err
}
return filepath.Join(dir, "service.json"), nil
}
// ReadServiceCredential reads the service password from the operator's local
// OpenCode service state file. The file is held to the same private-file rule
// as the other credential files (a regular, single-owner, 0600 file with a
// bounded read), so a world-readable or foreign-owned file is refused rather
// than trusted. An empty path yields no credential.
func ReadServiceCredential(path string) (string, error) {
if strings.TrimSpace(path) == "" {
return "", nil
}
if err := checkPrivateFile(path, serviceCredentialLimit); err != nil {
return "", fmt.Errorf("cannot read the local OpenCode service credential")
}
data, err := os.ReadFile(path)
if err != nil {
return "", fmt.Errorf("cannot read the local OpenCode service credential")
}
var state struct {
URL string `json:"url"`
Password string `json:"password"`
}
if err := json.Unmarshal(data, &state); err != nil || strings.TrimSpace(state.Password) == "" {
return "", fmt.Errorf("the local OpenCode service credential is not usable")
}
return strings.TrimSpace(state.Password), nil
}
// PairEndpoint exchanges one fresh credential with the running service: it
// calls POST /api/pair on the already-authenticated connection and completes
// the returned single-use code at GET /auth/connect/{code}. It reuses
// nativeRequest, so the pair request carries the same Basic auth, bounds and
// JSON checks as every other call and no second HTTP client is introduced. A
// blank bootstrap is a clear refusal rather than a guessed credential.
func PairEndpoint(ctx context.Context, rawURL, bootstrapPassword string) (string, error) {
base, err := NormalizeEndpointURL(rawURL)
if err != nil {
return "", err
}
if strings.TrimSpace(bootstrapPassword) == "" {
return "", fmt.Errorf("OpenCode endpoint %s needs a password or a local OpenCode service credential to pair", base)
}
conn := &Connection{
Backend: "v2",
URL: base,
password: bootstrapPassword,
username: strings.TrimSpace(os.Getenv(EndpointUsernameEnvKey)),
models: map[string]map[string]string{},
responses: map[string][]byte{},
}
codeCtx, cancel := context.WithTimeout(ctx, endpointProbeTimeout)
defer cancel()
data, err := conn.nativeRequest(codeCtx, "post", "/api/pair", nil, "")
if err != nil {
return "", fmt.Errorf("OpenCode endpoint %s could not start a pairing: %w", base, err)
}
var issued struct {
Code string `json:"code"`
ExpiresIn int `json:"expires_in"`
}
if json.Unmarshal(data, &issued) != nil || strings.TrimSpace(issued.Code) == "" {
return "", fmt.Errorf("OpenCode endpoint %s returned no pairing code", base)
}
tokenCtx, cancelToken := context.WithTimeout(ctx, endpointProbeTimeout)
defer cancelToken()
tokenData, err := conn.nativeRequest(tokenCtx, "get", "/auth/connect/"+url.PathEscape(issued.Code), nil, "")
if err != nil {
return "", fmt.Errorf("OpenCode endpoint %s refused the pairing code: %w", base, err)
}
var paired struct {
Token string `json:"token"`
}
if json.Unmarshal(tokenData, &paired) != nil || strings.TrimSpace(paired.Token) == "" {
return "", fmt.Errorf("OpenCode endpoint %s returned no paired credential", base)
}
return strings.TrimSpace(paired.Token), nil
}
// OpenEndpointAttached attaches chat to the operator's endpoint with the first
// credential that works, in precedence order: an explicit password (the
// password-file reference), a paired token stored by an earlier run, and a
// freshly paired token. The returned connection never owns a process. When a
// stored token is refused with 401 it is cleared and the broker pairs once
// more, so a credential the service has rotated heals without operator action;
// any other refusal is returned as-is.
//
// credentialPath is where the paired token is kept (owner-only). No credential
// is ever written to the log or the returned error; only the endpoint and the
// mode are.
func OpenEndpointAttached(ctx context.Context, rawURL, explicitPassword, bootstrapPassword, credentialPath string) (EndpointAttach, error) {
base, err := NormalizeEndpointURL(rawURL)
if err != nil {
return EndpointAttach{}, err
}
// 1. An explicit password (the operator's password-file reference) is used
// as given: it needs no pairing and is never replaced.
if strings.TrimSpace(explicitPassword) != "" {
conn, err := probeEndpoint(ctx, base, explicitPassword)
if err != nil {
return EndpointAttach{}, err
}
return EndpointAttach{Connection: conn, Mode: "password-file"}, nil
}
// 2. A token a previous run paired and stored.
stored, found, err := ReadPairedCredential(credentialPath, base)
if err != nil {
return EndpointAttach{}, err
}
if found {
conn, err := probeEndpoint(ctx, base, stored)
if err == nil {
return EndpointAttach{Connection: conn, Mode: "paired-stored"}, nil
}
if conn == nil || !conn.unauthorized {
return EndpointAttach{}, err
}
// The stored token was refused: drop it and pair a fresh one below.
if clearErr := ClearPairedCredential(credentialPath); clearErr != nil {
return EndpointAttach{}, clearErr
}
}
// 3. Pair a fresh token with the local service credential as bootstrap.
token, err := PairEndpoint(ctx, base, bootstrapPassword)
if err != nil {
return EndpointAttach{}, err
}
conn, err := probeEndpoint(ctx, base, token)
if err != nil {
return EndpointAttach{}, err
}
attach := EndpointAttach{Connection: conn, Mode: "paired"}
if credentialPath != "" {
if writeErr := WritePairedCredential(credentialPath, base, token); writeErr != nil {
// The attached connection works for this run; only persistence
// failed, so the next start re-pairs instead of failing closed.
attach.Note = "the paired credential could not be stored; chat will re-pair on the next start"
}
}
return attach, nil
}
// pairedCredential is the owner-only record of a token a previous run paired
// with one endpoint. The endpoint is stored so a token paired for one service
// is never offered to another.
type pairedCredential struct {
Endpoint string `json:"endpoint"`
Token string `json:"token"`
}
// ReadPairedCredential returns the stored token for endpoint, found false when
// no credential file exists or it belongs to a different endpoint. A file that
// exists but is not a private, owner-held regular file is an error, never a
// silently ignored credential.
func ReadPairedCredential(path, endpoint string) (string, bool, error) {
if strings.TrimSpace(path) == "" {
return "", false, nil
}
info, err := os.Lstat(path)
if err != nil {
if os.IsNotExist(err) {
return "", false, nil
}
return "", false, fmt.Errorf("cannot read the stored OpenCode pairing")
}
if !info.Mode().IsRegular() || info.Mode().Perm() != 0600 {
return "", false, fmt.Errorf("the stored OpenCode pairing is not a private file")
}
if stat, ok := info.Sys().(*syscall.Stat_t); !ok || stat.Uid != uint32(os.Getuid()) {
return "", false, fmt.Errorf("the stored OpenCode pairing belongs to another user")
}
data, err := os.ReadFile(path)
if err != nil {
return "", false, fmt.Errorf("cannot read the stored OpenCode pairing")
}
var credential pairedCredential
if err := json.Unmarshal(data, &credential); err != nil {
return "", false, fmt.Errorf("the stored OpenCode pairing is not usable")
}
if credential.Endpoint != endpoint || strings.TrimSpace(credential.Token) == "" {
return "", false, nil
}
return credential.Token, true, nil
}
// WritePairedCredential stores the paired token in an owner-only file: the
// directory is created 0700 and the file is written 0600 through a temporary
// file in the same directory and renamed over the target, so a reader never
// sees a partial record.
func WritePairedCredential(path, endpoint, token string) error {
if strings.TrimSpace(path) == "" {
return fmt.Errorf("no location to store the OpenCode pairing")
}
if strings.TrimSpace(token) == "" {
return fmt.Errorf("no OpenCode pairing token to store")
}
dir := filepath.Dir(path)
if err := os.MkdirAll(dir, 0700); err != nil {
return fmt.Errorf("cannot create the OpenCode pairing directory")
}
data, err := json.Marshal(pairedCredential{Endpoint: endpoint, Token: token})
if err != nil {
return err
}
temp, err := os.CreateTemp(dir, "opencode-pairing-*.json")
if err != nil {
return fmt.Errorf("cannot create the OpenCode pairing file")
}
name := temp.Name()
if err := temp.Chmod(0600); err != nil {
temp.Close()
os.Remove(name)
return fmt.Errorf("cannot secure the OpenCode pairing file")
}
if _, err := temp.Write(data); err != nil {
temp.Close()
os.Remove(name)
return fmt.Errorf("cannot write the OpenCode pairing file")
}
if err := temp.Close(); err != nil {
os.Remove(name)
return fmt.Errorf("cannot write the OpenCode pairing file")
}
if err := os.Rename(name, path); err != nil {
os.Remove(name)
return fmt.Errorf("cannot store the OpenCode pairing file")
}
return nil
}
// ClearPairedCredential removes a stored pairing that the service refused.
func ClearPairedCredential(path string) error {
if strings.TrimSpace(path) == "" {
return nil
}
if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
return fmt.Errorf("cannot clear the refused OpenCode pairing")
}
return nil
}
// checkPrivateFile applies the shared private-file rule: a regular file with
// exact 0600 permissions, owned by the current user and no larger than limit.
func checkPrivateFile(path string, limit int64) error {
info, err := os.Lstat(path)
if err != nil {
return err
}
if !info.Mode().IsRegular() || info.Mode().Perm() != 0600 || info.Size() > limit {
return fmt.Errorf("not a private file")
}
if stat, ok := info.Sys().(*syscall.Stat_t); !ok || stat.Uid != uint32(os.Getuid()) {
return fmt.Errorf("belongs to another user")
}
return nil
}
+256
View File
@@ -0,0 +1,256 @@
package opencode
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"sync"
"testing"
"time"
)
// pairService is a minimal V2 OpenCode service: it accepts the fixed "opencode"
// basic-auth user with either the bootstrap service password or a token it has
// paired, issues single-use pair codes, exchanges them for tokens, and counts
// pair calls so a test can prove a stored token is reused rather than re-paired.
type pairService struct {
mu sync.Mutex
password string
tokens map[string]bool
codes map[string]bool
pairs int
seq int
}
func newPairService(t *testing.T, password string) (*pairService, *httptest.Server) {
t.Helper()
s := &pairService{password: password, tokens: map[string]bool{}, codes: map[string]bool{}}
srv := httptest.NewServer(http.HandlerFunc(s.handle))
t.Cleanup(srv.Close)
return s, srv
}
func (s *pairService) authorized(r *http.Request) bool {
user, pass, ok := r.BasicAuth()
if !ok || user != "opencode" {
return false
}
s.mu.Lock()
defer s.mu.Unlock()
return pass == s.password || s.tokens[pass]
}
func (s *pairService) handle(w http.ResponseWriter, r *http.Request) {
switch {
case r.URL.Path == "/api/pair" && r.Method == http.MethodPost:
if !s.authorized(r) {
w.WriteHeader(http.StatusUnauthorized)
return
}
s.mu.Lock()
s.seq++
code := "code" + string(rune('0'+s.seq))
s.codes[code] = true
s.pairs++
s.mu.Unlock()
writeJSON(w, map[string]any{"code": code, "expires_in": 300})
case strings.HasPrefix(r.URL.Path, "/auth/connect/"):
code := strings.TrimPrefix(r.URL.Path, "/auth/connect/")
s.mu.Lock()
ok := s.codes[code]
delete(s.codes, code)
token := "token" + string(rune('0'+s.seq))
if ok {
s.tokens[token] = true
}
s.mu.Unlock()
if !ok {
w.WriteHeader(http.StatusUnauthorized)
return
}
writeJSON(w, map[string]any{"token": token})
case r.URL.Path == "/api/info":
if !s.authorized(r) {
w.WriteHeader(http.StatusUnauthorized)
return
}
writeJSON(w, map[string]any{"version": "2.0.20", "urls": []string{}})
case r.URL.Path == "/api/event":
if !s.authorized(r) {
w.WriteHeader(http.StatusUnauthorized)
return
}
w.Header().Set("Content-Type", "text/event-stream")
w.WriteHeader(http.StatusOK)
default:
w.WriteHeader(http.StatusNotFound)
}
}
func (s *pairService) pairCalls() int {
s.mu.Lock()
defer s.mu.Unlock()
return s.pairs
}
func writeJSON(w http.ResponseWriter, body any) {
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(body)
}
// TestPairEndpointExchangesCodeForToken pins the pairing contract the installed
// 2.0.20 service exposes: POST /api/pair (authenticated) issues a single-use
// code and GET /auth/connect/{code} returns the token used as the basic
// password.
func TestPairEndpointExchangesCodeForToken(t *testing.T) {
service, srv := newPairService(t, "service-password")
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
token, err := PairEndpoint(ctx, srv.URL, "service-password")
if err != nil {
t.Fatalf("PairEndpoint: %v", err)
}
if token == "" {
t.Fatal("PairEndpoint returned an empty token")
}
if service.pairCalls() != 1 {
t.Fatalf("pair calls = %d, want 1", service.pairCalls())
}
if _, err := PairEndpoint(ctx, srv.URL, ""); err == nil {
t.Fatal("PairEndpoint with no bootstrap password succeeded")
}
}
// TestOpenEndpointAttachedPairsStoresAndReuses pins the whole point: with no
// explicit password the broker pairs once, stores the token in an owner-only
// file beside the other configuration, and a later start reuses it instead of
// pairing again.
func TestOpenEndpointAttachedPairsStoresAndReuses(t *testing.T) {
service, srv := newPairService(t, "service-password")
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
credentialPath := filepath.Join(t.TempDir(), "opencode-endpoint.json")
first, err := OpenEndpointAttached(ctx, srv.URL, "", "service-password", credentialPath)
if err != nil {
t.Fatalf("first attach: %v", err)
}
if first.Mode != "paired" {
t.Fatalf("first attach mode = %q, want paired", first.Mode)
}
first.Connection.Close()
info, err := os.Stat(credentialPath)
if err != nil {
t.Fatalf("paired credential was not stored: %v", err)
}
if info.Mode().Perm() != 0600 {
t.Fatalf("stored credential mode = %v, want 0600", info.Mode().Perm())
}
if service.pairCalls() != 1 {
t.Fatalf("pair calls after first attach = %d, want 1", service.pairCalls())
}
second, err := OpenEndpointAttached(ctx, srv.URL, "", "service-password", credentialPath)
if err != nil {
t.Fatalf("second attach: %v", err)
}
if second.Mode != "paired-stored" {
t.Fatalf("second attach mode = %q, want paired-stored", second.Mode)
}
second.Connection.Close()
if service.pairCalls() != 1 {
t.Fatalf("a reused token triggered a re-pair: pair calls = %d, want 1", service.pairCalls())
}
}
// TestOpenEndpointAttachedRepairsRefusedStoredCredential pins the recovery: a
// token the service has refused is cleared and replaced by one fresh pairing,
// never left to fail closed.
func TestOpenEndpointAttachedRepairsRefusedStoredCredential(t *testing.T) {
service, srv := newPairService(t, "service-password")
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
credentialPath := filepath.Join(t.TempDir(), "opencode-endpoint.json")
if err := WritePairedCredential(credentialPath, srv.URL, "stale-token"); err != nil {
t.Fatalf("seed stale credential: %v", err)
}
attach, err := OpenEndpointAttached(ctx, srv.URL, "", "service-password", credentialPath)
if err != nil {
t.Fatalf("attach after refusal: %v", err)
}
attach.Connection.Close()
if attach.Mode != "paired" {
t.Fatalf("attach mode = %q, want paired after a refused stored token", attach.Mode)
}
if service.pairCalls() != 1 {
t.Fatalf("pair calls = %d, want exactly one re-pair", service.pairCalls())
}
token, found, err := ReadPairedCredential(credentialPath, srv.URL)
if err != nil || !found || token == "stale-token" {
t.Fatalf("stored credential after repair = %q,%v,%v want a fresh token", token, found, err)
}
}
// TestOpenEndpointAttachedExplicitPasswordSkipsPairing pins that an explicit
// password (the operator's password-file reference) is used as given and no
// pairing is attempted.
func TestOpenEndpointAttachedExplicitPasswordSkipsPairing(t *testing.T) {
service, srv := newPairService(t, "service-password")
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
attach, err := OpenEndpointAttached(ctx, srv.URL, "service-password", "service-password", filepath.Join(t.TempDir(), "unused.json"))
if err != nil {
t.Fatalf("attach with explicit password: %v", err)
}
attach.Connection.Close()
if attach.Mode != "password-file" {
t.Fatalf("attach mode = %q, want password-file", attach.Mode)
}
if service.pairCalls() != 0 {
t.Fatalf("an explicit password triggered a pairing: pair calls = %d", service.pairCalls())
}
}
// TestReadServiceCredential pins the bootstrap read: the service state file is
// held to the private-file rule and only its password is returned.
func TestReadServiceCredential(t *testing.T) {
path := filepath.Join(t.TempDir(), "service.json")
if err := os.WriteFile(path, []byte(`{"url":"http://0.0.0.0:49374","password":"bootstrap"}`), 0600); err != nil {
t.Fatal(err)
}
if got, err := ReadServiceCredential(path); err != nil || got != "bootstrap" {
t.Fatalf("ReadServiceCredential = %q,%v want bootstrap", got, err)
}
if err := os.Chmod(path, 0644); err != nil {
t.Fatal(err)
}
if _, err := ReadServiceCredential(path); err == nil {
t.Fatal("a world-readable service credential was accepted")
}
if got, err := ReadServiceCredential(""); err != nil || got != "" {
t.Fatalf("empty path = %q,%v want no credential", got, err)
}
}
// TestReadPairedCredentialIsEndpointScoped pins that a token paired for one
// endpoint is never offered to another.
func TestReadPairedCredentialIsEndpointScoped(t *testing.T) {
path := filepath.Join(t.TempDir(), "opencode-endpoint.json")
if err := WritePairedCredential(path, "http://127.0.0.1:1", "token"); err != nil {
t.Fatal(err)
}
if _, found, err := ReadPairedCredential(path, "http://127.0.0.1:2"); err != nil || found {
t.Fatalf("foreign endpoint = found %v, err %v; want not found", found, err)
}
if token, found, err := ReadPairedCredential(path, "http://127.0.0.1:1"); err != nil || !found || token != "token" {
t.Fatalf("matching endpoint = %q,%v,%v want token", token, found, err)
}
if _, found, err := ReadPairedCredential(filepath.Join(t.TempDir(), "absent.json"), "http://127.0.0.1:1"); err != nil || found {
t.Fatalf("absent file = found %v, err %v; want not found", found, err)
}
}
+10 -3
View File
@@ -22,7 +22,14 @@ type SystemStatus struct {
Addresses []NetworkAddress `json:"addresses"`
Server ServiceStatus `json:"server"`
Ntfy ServiceStatus `json:"ntfy"`
Topic string `json:"topic,omitempty"`
NtfyUser string `json:"ntfy_user,omitempty"`
Note string `json:"note"`
// OpenCode reports how brokered chat is attached to OpenCode. Health is
// "endpoint" when attached to the operator's configured endpoint,
// "fallback" when that endpoint could not be attached and chat fell back to
// the server's own instance, "spawned" when no endpoint is configured, and
// "unavailable" when chat is disabled. URL is the configured endpoint, if
// any. It never carries a credential.
OpenCode ServiceStatus `json:"opencode"`
Topic string `json:"topic,omitempty"`
NtfyUser string `json:"ntfy_user,omitempty"`
Note string `json:"note"`
}
+28
View File
@@ -0,0 +1,28 @@
package protocol
import (
"encoding/json"
"strings"
"testing"
)
// TestSystemStatusOpenCodeField pins the wire shape the server and every client
// agree on: the OpenCode attachment report is a nested "opencode" object and it
// carries no credential field.
func TestSystemStatusOpenCodeField(t *testing.T) {
encoded, err := json.Marshal(SystemStatus{OpenCode: ServiceStatus{Health: "endpoint", URL: "http://127.0.0.1:49374"}})
if err != nil {
t.Fatal(err)
}
text := string(encoded)
if !strings.Contains(text, `"opencode":{"health":"endpoint"`) {
t.Fatalf("opencode status not encoded as expected: %s", text)
}
var decoded SystemStatus
if err := json.Unmarshal(encoded, &decoded); err != nil {
t.Fatal(err)
}
if decoded.OpenCode.Health != "endpoint" || decoded.OpenCode.URL != "http://127.0.0.1:49374" {
t.Fatalf("round trip lost the opencode status: %+v", decoded.OpenCode)
}
}
+28
View File
@@ -50,6 +50,34 @@ func TestStatusRPCReportsServerAndNtfyWithoutSecrets(t *testing.T) {
}
}
// TestStatusReportsOpenCodeAttachment pins that get_status carries how chat is
// attached to OpenCode, so an endpoint that could not be attached shows as
// "fallback" instead of silently disappearing, and that the report never
// contains a credential.
func TestStatusReportsOpenCodeAttachment(t *testing.T) {
options := Options{OpenCodeStatus: protocol.ServiceStatus{Health: "fallback", URL: "http://127.0.0.1:49374"}}
srv := httptest.NewServer(HandlerWithOptions(context.Background(), options))
defer srv.Close()
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
c, err := client.Open(ctx, "ws"+strings.TrimPrefix(srv.URL, "http")+"/connect")
if err != nil {
t.Fatal(err)
}
defer c.Close()
response, err := c.Call(ctx, protocol.Message{Type: protocol.GetStatus})
if err != nil {
t.Fatal(err)
}
if response.Status == nil || response.Status.OpenCode.Health != "fallback" || response.Status.OpenCode.URL != "http://127.0.0.1:49374" {
t.Fatalf("opencode status not reported: %+v", response.Status)
}
encoded, _ := json.Marshal(response.Status)
if strings.Contains(string(encoded), "password") || strings.Contains(string(encoded), "token") {
t.Fatalf("status leaked a credential-shaped field: %s", encoded)
}
}
func TestStatusUnconfiguredUnhealthyAndIPv6Candidates(t *testing.T) {
t.Setenv("PIPELINES_NTFY_URL", "")
t.Setenv("PIPELINES_NTFY_PUBLIC_URL", "")
+11
View File
@@ -27,6 +27,13 @@ type Options struct {
// chat_* request with a protocol error; a configured server passes an
// *opencode.Chat bound to the owned endpoint.
Chat chatBroker
// OpenCodeStatus is the honest report of how chat is attached to OpenCode,
// echoed on get_status: "endpoint" when the broker is attached to the
// operator's configured endpoint, "fallback" when that endpoint could not be
// attached and chat fell back to the server's own instance, "spawned" when
// no endpoint is configured, and "unavailable" when chat is disabled. It
// carries the endpoint URL but never a credential.
OpenCodeStatus protocol.ServiceStatus
// OperatorRegistry is the operator-session registry chat_sessions lists and
// chat_create/chat_directories read. When nil, HandlerWithOptions derives it
// from the first store; when neither is available chat_sessions returns an
@@ -173,6 +180,10 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin
if request.Type == protocol.GetStatus {
response.Type = protocol.Status
response.Status = systemStatus(r, started, runErr)
// How chat is attached to OpenCode is part of the server's status:
// a configured endpoint that could not be attached reports
// "fallback" here rather than silently disappearing.
response.Status.OpenCode = options.OpenCodeStatus
} else if request.Type == protocol.Ping {
response.Time = time.Now().UTC().Format(time.RFC3339)
} else if request.Type == protocol.ListTemplates {