@mirrowel/opencode-openshare 0.2.0 → 0.3.0-dev.1

package/README.md

@@ -3,6 +3,8 @@
 The opencode side of [Open(code)Share](../README.md) — session sharing for
 OpenCode v1 and v2, self-hosted on your own worker.
 
+Every plugin config key, its file chain, and the cross-package config surface are inventoried in [../CONFIGURATION.md](../CONFIGURATION.md).
+
 ## Artifacts
 
 | Artifact | What it is | Share mode |
@@ -12,8 +14,9 @@ OpenCode v1 and v2, self-hosted on your own worker.
 | `ci/openshare.js` | single-file, zero-dependency bundle of the same engine (committed; rebuilt by `npm run build`) | all-mode **by default** — it declares no TUI entry, but an explicit `shareMode` in config/env still wins |
 
 All three are behavior-identical where they overlap — `npm run
-test:regression` proves the single file and the package match the frozen
-original (`reference/openshare.legacy.js`) on the full share lifecycle.
+test:regression` drives the single file and the package entry through
+the same real lifecycle (a local worker, a mock provider, a real
+`opencode serve`) and diffs the resulting share data.
 
 ## Install
 
@@ -59,12 +62,26 @@ spec `"file:///…/openshare/share-plugin"` in both config files (run
 no build at all: [`ci/openshare.js`](ci/README.md), committed ready to
 use.
 
-**With no token the plugin enrolls itself** on first contact: public
-servers (hoster set `AUTH_MODE=public`) take anyone; private ones need
-a `code` from the hoster (activation-budgeted invite). The enrolled
-token persists to `~/.config/opencode/openshare.config.json` — enroll
-once per server, then it just works. A revoked token re-enrolls the
-same way (public/code available); if enrollment is impossible the
+**Server-held config sets**: set `configSet` (or
+`OPENSHARE_CONFIG_SET`) to pick a named set provisioned on your server
+token - the server applies its auth/TTL at create (nothing sensitive in
+the repo), and suggests modelLabel/shareMode which the plugin adopts once
+per boot when you haven't set them locally.
+
+**Identity is never assumed**: with no token configured the plugin does
+NOT silently enroll. A configured `code` IS expressed
+intent — the engine enrolls with it headlessly (the CI shape). Without
+one: public servers share **anonymously** (ownerless shares under the
+server's global anonymous caps), private servers refuse with guidance.
+Onboarding happens through the ask-once TUI flow — `/share` first run
+or `/openshare` → Servers → Connect to a server offers "Onboard (get an
+account)" vs "Stay anonymous" (with the differences explained), detects
+whether a code is needed, and only then prompts for one; the outcome is
+remembered per server (token = onboarded, `anonymous` flag = declined,
+onboard later via the server menu's Enroll now). The enrolled token
+persists to `~/.config/opencode/openshare.config.json` — enroll once per
+server, then it just works. A revoked token re-enrolls the same way
+(code configured / codeless server); if enrollment is impossible the
 plugin says so on stderr and stops — no retry storms.
 
 ## Share modes
@@ -78,7 +95,7 @@ No selfwiring: which parts you install IS the switch.
 
 Manual mode stores the opt-in in session metadata:
 `metadata.openshare = { v: 2, enabled: true, opts? }` with per-session
-overrides (`ttlDays`, `authLogin`, `authPassword`, `modelLabel`). The
+overrides (`ttlHours`, `authLogin`, `authPassword`, `modelLabel`). The
 per-server binding map (`servers: {url: {id, secret, rev, url}}`) is
 written next to it — legacy flat bindings migrate at read. The key is
 stripped from everything synced and never reaches viewers.
@@ -87,6 +104,19 @@ On OpenCode v2: the package declaring its `tui` entrypoint is the presence
 signal (the v2 host auto-loads it); the single file declares none and
 stays all-mode.
 
+## Trust controls (config)
+
+Client-side redaction runs at the engine's single enqueue choke point
+(backfill and live events both), so stripped secrets never reach a
+queue, spool or wire:
+
+- `redact.patterns` — extra regexes (strings) redacted beside the built-in
+  detectors on UNGATED shares only (a gated share is already
+  login-private): GitHub/AWS/Slack/Google key shapes, `sk-` keys, Bearer
+  tokens, PEM private-key blocks, `.env`-shaped assignments and
+  connection-string passwords, replaced with `[redacted:<kind>]`. The
+  consent dialog previews counts and the first hits.
+
 ## TUI
 
 - `/share` — share the session (explicit consent on EVERY creation —
@@ -94,12 +124,13 @@ stays all-mode.
   session, shares the whole family. Already shared → the session menu,
   identical to `/openshare → This session`: copy links (per server, or
   all), stop sharing — delete or leave a snapshot, per-server stop on
-  multi-server shares —, share to another server, session TTL and read
+  multi-server shares —, share to another server, session TTL, read
   auth. A credential conflict opens the collision dialog (copy debug
   info / share on a new share / don't share).
 - `/openshare` — grouped settings (compact root with live summaries →
   focused submenus): This session (share/stop — delete or leave a
-  snapshot —, TTL override, session read auth), **Servers** (connection
+  snapshot —, TTL override, session read auth),
+  **Servers** (connection
   AND membership: legacy pair, connect, enroll, rotate, get-a-user-token
   for root holders, disconnect, per-server **admin panel** — users,
   tokens, codes, shares, purge —, test, remove), Sharing (share mode +
@@ -124,7 +155,7 @@ stays all-mode.
 npm install
 npm run build         # tsc -> dist/ + bun bundle -> ci/openshare.js (Bun on PATH)
 npm run typecheck
-npm run test          # full matrix via the parallel driver (~4.5 min)
+npm run test          # full matrix via the parallel driver (~2.5 min)
 npm run test:quick     # everyday gate (~90s): parity + manual core + TUI + v2 + auth
 ```
 
@@ -133,20 +164,11 @@ watchdogged, port-swept, and drives real `opencode serve` instances with
 a mock OpenAI-compatible provider — except where noted). The canonical
 suite table — what each covers, including the big/backends scale suites —
 lives in [`../DEVELOPMENT.md`](../DEVELOPMENT.md#test-suites); the
-commands:
-
-- `test:regression` — parity of legacy / single-file / package across the
-  full lifecycle.
-- `test:manual` — the engine scenarios (dormancy, backfill, tombstones,
-  timers, turn sockets, all-mode gating).
-- `test:tui-flow` — share/manager flows, config write targets, enrollment,
-  admin console, gone detection.
-- `test:v2` — the v2 adapter against a scripted mock v2 host.
-- `test:auth` / `test:server-auth` — the identity contract (52 checks)
-  against the Cloudflare worker and the Bun backend.
-- `test:enroll` / `test:server-enroll`, `test:fanout`, `test:big` /
-  `test:server-big` — enrollment lifecycle, multi-server fan-out,
-  big-session scale (both backends).
+everyday commands:
+
+- `test:quick` — the everyday gate: parity + manual core + TUI + v2 + auth.
+- `test:auth` / `test:server-auth` — the identity contract against the
+  Cloudflare worker and the Bun backend.
 - `test:cli`, `node scripts/npm-e2e.mjs` — real `opencode run` / the
   published npm package — on demand only.
 

package/ci/README.md

@@ -31,10 +31,22 @@ README's [Configuration](../../README.md#configuration)):
 
 ```
 OPENSHARE_WORKER_URL=https://your-host
-OPENSHARE_CREATE_TOKEN=…            # legacy: root token
+OPENSHARE_CREATE_TOKEN=:            # legacy: root token
 OPENSHARE_URL_FILE=share-urls.txt   # each share URL appended + stderr line
 ```
 
+CI conveniences:
+
+- `OPENSHARE_CONFIG_JSON` - the whole config as one env var (same keys as
+  the config file), when mounting a file is awkward. A specific
+  `OPENSHARE_*` var still wins over it.
+- `OPENSHARE_URL_FILE_FORMAT=json` - urlFile lines become
+  `{"id":"…","url":"…","status":"…","gated":false}` objects, one per
+  line, so workflow steps read fields instead of parsing URLs.
+- `meta` in the config stamps free-form labels (env-interpolated, e.g.
+  `"branch": "${GITHUB_REF_NAME}"`) onto every share - visible in the
+  server's admin shares listing.
+
 ```jsonc
 // openshare.config.json — enrollment shape (no root token needed)
 {
@@ -44,14 +56,29 @@ OPENSHARE_URL_FILE=share-urls.txt   # each share URL appended + stderr line
 }
 ```
 
-With no token held, the bundle **enrolls itself** on first contact
-(public servers take anyone; private ones consume the one-time code) and
-persists the token to `~/.config/opencode/openshare.config.json` —
-enroll once, then every run just shares. A revoked token re-enrolls the
-same way; if enrollment is impossible the error lands on stderr and
-sharing stops (no retry storms). The bundle also supports **fan-out**:
-multiple `active` servers in the `servers` group each get the session
-(one urlFile line per server).
+With no token held the bundle never silently enrolls: a configured
+`code` enrolls with it headlessly (the CI shape — each code use is one
+enrollment); without one, public servers share anonymously (ownerless
+shares under the server's global anonymous caps) and private servers
+refuse with guidance. When enrollment does run, the token persists to
+`~/.config/opencode/openshare.config.json` — enroll once, then every
+run just shares. A revoked token re-enrolls the same way (code
+configured / codeless server); if enrollment is impossible the error
+lands on stderr and sharing stops (no retry storms).
+
+**Ephemeral runners** (GitHub-hosted, containers): do NOT enroll through
+a code - each fresh machine would burn one activation. Ask the hoster
+for a pre-registered token and pass it via `OPENSHARE_CREATE_TOKEN`
+(or the config's token field); registered tokens skip enrollment
+entirely and never expire on their own. A **scoped** token
+(`POST /api/token {"kind":"scoped"}`, minted by any full token) is the
+right credential here: it creates within its limits, reaches only the
+shares it created, and revoking it never freezes the owner's account.
+Point `OPENCODE_CONFIG_DIR` (or mount) the settings home at a cached
+path only if you want the token persisted; env alone is enough.
+
+The bundle also supports **fan-out**: multiple `active` servers in the
+`servers` group each get the session (one urlFile line per server).
 
 On OpenCode v2, plugin targets should be directories/packages — wrap this
 file in a folder with a `package.json` exporting it (`{"exports": {".": "./openshare.js"}}`)