@matuto-ai/opencode-psst-connector 0.0.0-stage → 0.6.0

package/plugin/index.mjs

@@ -0,0 +1,18 @@
+import { tool } from '../src/tool-schema.mjs';
+import { loadBrokerReference } from '../src/reference.mjs';
+import { readExistingConnection } from '../src/enrollment.mjs';
+import { readInstallation } from '../src/installation.mjs';
+import { setupNativePlugin } from '../src/native-plugin.mjs';
+
+// Structurally the public @opencode/plugin Plugin.define({ id, setup }) contract.
+// define is identity-only; the package never installs a host, runtime or CLI.
+export default {
+  id: 'matuto.psst',
+  async setup(ctx) {
+    const reference = await loadBrokerReference();
+    const connectionFile = ctx.options?.connectionFile ?? process.env.PSST_CONFIG_FILE;
+    const runtime = await setupNativePlugin({ ctx, reference, tool, metadataOptions: ctx.options ?? {}, setupEnabled: !connectionFile,
+      loadSettings: readOptions => connectionFile ? readExistingConnection(connectionFile, readOptions) : readInstallation(undefined, readOptions) });
+    return runtime.dispose;
+  },
+};

package/plugin/tui.mjs

@@ -0,0 +1,160 @@
+import { randomUUID } from 'node:crypto';
+import { SETUP_RPC } from '../src/setup-rpc.mjs';
+import { installationDirectory } from '../src/installation.mjs';
+import { createPresenceWriter, presenceDirectory } from '../src/active-presence.mjs';
+
+export default {
+  id: 'matuto.psst',
+  setup(ctx) {
+    let writer, directory, last, lastWrite = 0, warned = false;
+    const offline = () => {
+      if (!warned) ctx.ui?.toast?.show?.({ title: 'Psst offline', message: 'Active-chat messaging requires a local TUI sharing the server private directory.', variant: 'warning' });
+      warned = true;
+    };
+    if (ctx.app?.version !== '2.2.5' || typeof ctx.ui?.router?.current !== 'function' || typeof ctx.storage?.memory !== 'function') { offline(); return; }
+    const [memory, update] = ctx.storage.memory('psst-active-owner', { initial: { owner: randomUUID(), seq: 0 } });
+    const counter = { get seq() { return memory.seq; }, set seq(value) { update(draft => { draft.seq = value; }); } };
+    const tick = () => {
+      try {
+        const route = ctx.ui.router.current(), location = ctx.location;
+        if (!location) throw new Error('native_selection_location_unavailable');
+        const nextDirectory = presenceDirectory(installationDirectory(), location);
+        if (nextDirectory !== directory) {
+          writer?.stop(); writer = undefined; directory = undefined;
+          writer = createPresenceWriter({ directory: nextDirectory, owner: memory.owner, counter });
+          directory = nextDirectory; last = undefined;
+        }
+        const selected = route.type === 'session' ? route.sessionID : null;
+        if (selected !== last || Date.now() - lastWrite >= 1000) { writer.write(selected); last = selected; lastWrite = Date.now(); }
+        warned = false;
+      } catch { try { writer?.stop(); } catch {} writer = undefined; directory = undefined; offline(); }
+    };
+    const stopSetupUI = registerSetupUI(ctx, () => { tick(); return !!writer; });
+    tick(); const timer = setInterval(tick, 250); timer.unref?.();
+    return () => { stopSetupUI(); clearInterval(timer); try { writer?.stop(); } catch {} };
+  },
+};
+
+
+const stateMessages = {
+  setup_needed: 'Enter your broker URL with /psst-setup.',
+  pending: 'Waiting for human approval in the broker admin UI. Use /psst-status to check.',
+  approved: 'Broker authorization approved.',
+  denied: 'The approval request was denied. A new request requires confirmation in /psst-setup.',
+  expired: 'The approval request expired. A new request requires confirmation in /psst-setup.',
+  revoked: 'The authorization was revoked. A new request requires confirmation in /psst-setup.',
+  paused: 'Local setup is paused. Existing authorization and local data are retained.',
+  setup_blocked: 'Setup could not continue. Check /psst-status before retrying.',
+  setup_owner_recovery_required: 'Setup ownership needs recovery. Existing authorization and local data are retained.',
+};
+function brokerOrigin(value) {
+  if (typeof value !== 'string' || value.length > 2048 || /[\s\x00-\x1f\x7f-\x9f]/u.test(value)) throw Error('invalid_url');
+  let url;
+  try { url = new URL(value); } catch { throw Error('invalid_url'); }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw Error('invalid_url');
+  return url.origin;
+}
+function statusMessage(result) {
+  // Never render exception strings or arbitrary server fields, including paths,
+  // credentials and terminal controls. Public approval URLs have one fixed path.
+  const setupMessage = stateMessages[result?.state];
+  let message = result?.connected === true
+    ? 'Psst is connected for this selected chat.' + (setupMessage && result.state !== 'setup_needed' ? ` Existing connection stays active. Setup: ${setupMessage}` : '')
+    : setupMessage ?? 'Psst is not connected. Use /psst-setup to configure it.';
+  if (result?.authorization_state === 'expired') message = 'The current authorization expired. Use /psst-setup for an explicitly approved replacement. Existing local data is retained.';
+  if (result?.authorization_state === 'rejected') message = 'The broker rejected the current authorization. Use /psst-setup for an explicitly approved replacement. Existing local data is retained.';
+  if (typeof result?.approval_url === 'string' && result.approval_url.length <= 2048) {
+    try {
+      const url = new URL(result.approval_url);
+      if (url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash && url.pathname === '/admin') message += ` Approve at ${url.origin}/admin.`;
+    } catch {}
+  }
+  if (typeof result?.request_id === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(result.request_id)) message += ` Request: ${result.request_id}.`;
+  return message;
+}
+function registerSetupUI(ctx, available) {
+  // Presence-only hosts/tests still work; never touch the client without the
+  // supported native command and dialog APIs.
+  if (typeof ctx.keymap?.layer !== 'function' || typeof ctx.ui?.dialog?.prompt !== 'function'
+    || typeof ctx.ui?.dialog?.confirm !== 'function') return () => {};
+  let disposed = false, active;
+  const toast = (message, variant = 'info') => { if (!disposed) ctx.ui.toast.show({ title: 'Psst', message, variant, duration: 12000 }); };
+  const selection = () => {
+    const route = ctx.ui.router.current();
+    if (route?.type !== 'session' || typeof route.sessionID !== 'string' || !/^[A-Za-z0-9_.:-]{1,256}$/.test(route.sessionID) || !ctx.location) throw Error('selection_changed');
+    return { sessionID: route.sessionID, directory: ctx.location.directory, workspaceID: ctx.location.workspaceID };
+  };
+  const run = async kind => {
+    if (disposed) return;
+    if (active) { toast('Finish or dismiss the current Psst dialog first.', 'warning'); return; }
+    const controller = new AbortController();
+    active = controller;
+    let timer, check, blur;
+    try {
+      const selected = selection();
+      if (!available()) throw Error('local_unavailable');
+      const location = { ...ctx.location };
+      check = () => {
+        try { const current = selection();
+          if (JSON.stringify(current) !== JSON.stringify(selected)) controller.abort();
+        } catch { controller.abort(); }
+      };
+      blur = () => controller.abort();
+      ctx.renderer?.on?.('blur', blur);
+      ctx.renderer?.on?.('frame', check);
+      timer = setInterval(check, 50); timer.unref?.();
+      controller.signal.addEventListener('abort', () => {
+        clearInterval(timer);
+        ctx.renderer?.off?.('blur', blur);
+        ctx.renderer?.off?.('frame', check);
+      }, { once: true });
+      const verify = () => {
+        check();
+        if (disposed || controller.signal.aborted) throw Error('selection_changed');
+        if (!available()) throw Error('local_unavailable');
+      };
+      const rpc = ctx.client.rpc(SETUP_RPC);
+      const call = async (method, input) => {
+        verify();
+        const result = await rpc[method]({ sessionID: selected.sessionID, ...input }, { location, signal: AbortSignal.any([controller.signal, AbortSignal.timeout(15000)]) });
+        verify(); return result;
+      };
+      if (kind === 'setup') {
+        const value = await ctx.ui.dialog.prompt({ title: 'Set up Psst', description: 'Enter only your HTTPS broker URL. Approval happens in the broker admin UI; never paste a token or credential.', placeholder: 'https://broker.example.com' });
+        if (value === undefined) return;
+        verify();
+        const broker_url = brokerOrigin(value);
+        const status = await call('status', { broker_url });
+        let replacement_confirmed = false;
+        if (status?.replacement_confirmation_required === true) {
+          if (typeof status.request_id !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(status.request_id)) throw Error('invalid_status');
+          replacement_confirmed = await ctx.ui.dialog.confirm({ title: 'Replace Psst authorization?', message: 'This creates a new approval request and, after approval, new credential-bound addresses. Old addresses will not become the new identity. Old local data is retained. Continue?', label: { confirm: 'Create new request', cancel: 'Keep existing' } }) === true;
+          verify();
+          if (!replacement_confirmed) return;
+        }
+        const result = await call('setup', { broker_url, ...(replacement_confirmed ? { replacement_confirmed: true, replacement_request_id: status.request_id } : {}) });
+        toast(statusMessage(result));
+      } else toast(statusMessage(await call(kind, {})));
+    } catch (error) {
+      const message = error?.message === 'invalid_url'
+        ? 'Enter an HTTPS broker origin only, without credentials, path, query or fragment.'
+        : controller.signal.aborted || error?.message === 'selection_changed'
+          ? 'Psst action stopped because the selected chat or terminal focus changed. Run it again in the intended chat.'
+          : error?.message === 'local_unavailable'
+            ? 'Setup requires a local TUI sharing the server private directory.'
+            : 'Psst action could not complete. Check /psst-status before retrying; do not paste credentials.';
+      toast(message, 'warning');
+    } finally {
+      clearInterval(timer);
+      if (blur) ctx.renderer?.off?.('blur', blur);
+      if (check) ctx.renderer?.off?.('frame', check);
+      if (active === controller) active = undefined;
+    }
+  };
+  ctx.keymap.layer(() => ({ mode: 'global', commands: [
+    { id: 'psst-setup', title: 'Psst: Set up broker', group: 'Psst', palette: true, slash: { name: 'psst-setup' }, run: () => run('setup') },
+    { id: 'psst-status', title: 'Psst: Check status', group: 'Psst', palette: true, slash: { name: 'psst-status' }, run: () => run('status') },
+    { id: 'psst-cancel-setup', title: 'Psst: Pause setup', group: 'Psst', palette: true, slash: { name: 'psst-cancel-setup' }, run: () => run('cancel') },
+  ] }));
+  return () => { disposed = true; active?.abort(); };
+}

package/src/active-presence.mjs

@@ -0,0 +1,97 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, openSync, closeSync, fstatSync, readFileSync, writeFileSync, renameSync, unlinkSync, lstatSync, realpathSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { privateDirectory } from './config.mjs';
+import { canonical } from '../vendor/broker/src/protocol.mjs';
+
+// Availability preference, NOT authentication. Processes with the same UID can
+// forge this signal. It never supplies a binding, credential or tool authority.
+export const PRESENCE_TTL = 5000;
+const validID = s => typeof s === 'string' && /^[A-Za-z0-9_.:-]{1,256}$/.test(s);
+const ownerID = s => typeof s === 'string' && /^[a-f0-9-]{36}$/.test(s);
+export function processIdentity(pid = process.pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) throw new Error('native_selection_invalid');
+  if (process.platform !== 'linux') { process.kill(pid, 0); return { pid, start: null, boot: null }; }
+  const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+  return { pid, start: stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19], boot: readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim() };
+}
+function checkedDirectory(path) {
+  const s = lstatSync(path);
+  if (!s.isDirectory() || s.isSymbolicLink() || s.mode & 0o077 || process.getuid && s.uid !== process.getuid() || realpathSync(path) !== path) throw new Error('native_selection_path_unsafe');
+  return path;
+}
+export function presenceDirectory(root, location, { create = false } = {}) {
+  checkedDirectory(root);
+  const directory = realpathSync(location.directory);
+  const key = createHash('sha256').update(canonical({ directory, workspaceID: location.workspaceID ?? null })).digest('hex');
+  const path = join(root, 'active-tui-' + key);
+  if (create) privateDirectory(path);
+  return checkedDirectory(path);
+}
+function read(path) {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const s = fstatSync(fd);
+    if (!s.isFile() || s.nlink !== 1 || s.mode & 0o077 || process.getuid && s.uid !== process.getuid() || s.size > 2048) throw new Error('native_selection_invalid');
+    return JSON.parse(readFileSync(fd, 'utf8'));
+  } finally { closeSync(fd); }
+}
+export function createPresenceWriter({ directory, owner = randomUUID(), counter = { seq: 0 }, now = Date.now }) {
+  checkedDirectory(directory);
+  if (!ownerID(owner)) throw new Error('native_selection_invalid');
+  const identity = processIdentity(), path = join(directory, owner + '.json');
+  const generation = randomUUID();
+  let stopped = false;
+  return {
+    owner,
+    write(sessionID) {
+      if (stopped || sessionID !== null && !validID(sessionID)) throw new Error('native_selection_invalid');
+      checkedDirectory(directory);
+      const value = { version: 1, owner, ...identity, generation, seq: ++counter.seq, issued: now(), sessionID };
+      const temp = join(directory, `.${owner}-${randomUUID()}.tmp`);
+      let fd;
+      try {
+        fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        writeFileSync(fd, JSON.stringify(value)); closeSync(fd); fd = undefined;
+        renameSync(temp, path);
+      } finally { if (fd !== undefined) closeSync(fd); try { unlinkSync(temp); } catch {} }
+    },
+    stop() { stopped = true; try { checkedDirectory(directory); if (read(path).generation === generation) unlinkSync(path); } catch (e) { if (e.code !== 'ENOENT') throw e; } },
+  };
+}
+export function createPresenceReader({ directory, now = Date.now }) {
+  const seen = new Map();
+  return {
+    selected() {
+      checkedDirectory(directory);
+      const names = readdirSync(directory).filter(n => n.endsWith('.json'));
+      if (names.length > 4096) throw new Error('native_selection_owner_limit');
+      const selected = new Set(); let liveOwners = 0;
+      for (const [id, value] of seen) if (value.expires <= now()) seen.delete(id);
+      for (const name of names) {
+        try {
+          const v = read(join(directory, name)), time = now();
+          // Dedicated ephemeral files only; never remove bindings or journals.
+          if (v.version === 1 && ownerID(v.owner) && name === v.owner + '.json' && Number.isSafeInteger(v.issued) && time - v.issued >= PRESENCE_TTL) {
+            if (canonical(read(join(directory, name))) === canonical(v)) unlinkSync(join(directory, name));
+            continue;
+          }
+          if (v.version !== 1 || !ownerID(v.owner) || name !== v.owner + '.json' || !Number.isSafeInteger(v.seq) || v.seq < 1
+            || !Number.isSafeInteger(v.issued) || v.issued > time || time - v.issued >= PRESENCE_TTL
+            || v.sessionID !== null && !validID(v.sessionID)) continue;
+          const identity = processIdentity(v.pid);
+          if (identity.start !== v.start || identity.boot !== v.boot) continue;
+          const previous = seen.get(v.owner);
+          if (previous && (v.seq < previous.seq || v.seq === previous.seq && canonical(v) !== previous.value)) continue;
+          liveOwners++;
+          if (!seen.has(v.owner) && seen.size >= 128) continue;
+          seen.set(v.owner, { seq: v.seq, value: canonical(v), expires: v.issued + PRESENCE_TTL });
+          if (v.sessionID) selected.add(v.sessionID);
+        } catch { /* A malformed/stale owner is not a reason to activate anything. */ }
+      }
+      for (const [id, value] of seen) if (value.expires <= now()) seen.delete(id);
+      if (liveOwners > 64) throw new Error('native_selection_owner_limit');
+      return selected;
+    },
+  };
+}

package/src/approval-helper.mjs

@@ -0,0 +1,11 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const APPROVAL_SHA256 = 'a60c3a0ccd7deb50556586cd67841bb89a300ea3c7f1af3a91d437f856b7a2d5';
+export async function loadApprovalHelper() {
+  const path = fileURLToPath(new URL('../vendor/enrollment/approval.mjs', import.meta.url));
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536
+    || createHash('sha256').update(readFileSync(path)).digest('hex') !== APPROVAL_SHA256) throw new Error('approval_snapshot_mismatch');
+  return import('../vendor/enrollment/approval.mjs');
+}

package/src/config.mjs

@@ -0,0 +1,50 @@
+import { openSync, closeSync, readFileSync, fstatSync, constants, mkdirSync, lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, dirname, resolve } from 'node:path';
+const fail = () => { throw new Error('psst_configuration_invalid'); };
+const plain = value => value && typeof value === 'object' && !Array.isArray(value);
+export function readConfig(path) {
+  if (typeof path !== 'string' || !isAbsolute(path)) fail();
+  let fd, marked = false;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.mode & 0o077 || stat.size > 16384 || process.getuid && stat.uid !== process.getuid()) fail();
+    let value = JSON.parse(readFileSync(fd, 'utf8'));
+    if (value?.format === 'broker-client-bundle-v1') {
+      const allowed = ['format', 'protocol_version', 'broker_url', 'token_file', 'file_paths_relative_to', 'authorization_header', 'authorization_scheme', 'insecure_development', 'allowed_client_types', 'scope', 'ca_file', 'enrollment_receipt_file', 'registration_version'];
+      if (Object.keys(value).some(key => !allowed.includes(key)) || value.protocol_version !== '1'
+        || value.registration_version !== undefined && ![1,2].includes(value.registration_version)
+        || value.file_paths_relative_to !== 'connection_file_directory' || value.authorization_header !== 'Authorization'
+        || value.authorization_scheme !== 'Bearer' || value.insecure_development !== false
+        || !Array.isArray(value.allowed_client_types) || value.allowed_client_types.length !== 1 || value.allowed_client_types[0] !== 'opencode'
+        || value.enrollment_receipt_file !== undefined && value.enrollment_receipt_file !== 'enrollment.json'
+        || value.token_file !== 'token' || typeof value.scope !== 'string') fail();
+      marked = value.enrollment_receipt_file === 'enrollment.json';
+      const base = dirname(realpathSync(path));
+      value = { broker: { url: value.broker_url, tokenFile: resolve(base, value.token_file),
+        ...(value.registration_version !== undefined ? { registrationVersion: value.registration_version } : {}),
+        ...(value.ca_file ? { caFile: resolve(base, value.ca_file) } : {}) }, stateDirectory: resolve(base, 'state') };
+    }
+    if (!plain(value) || Object.keys(value).some(key => !['broker', 'stateDirectory', 'name', 'project', 'projectEnv'].includes(key))
+      || !plain(value.broker) || Object.keys(value.broker).some(key => !['url', 'tokenFile', 'caFile', 'registrationVersion'].includes(key))
+      || typeof value.stateDirectory !== 'string' || !isAbsolute(value.stateDirectory)
+      || value.broker.registrationVersion !== undefined && ![1, 2].includes(value.broker.registrationVersion)
+      || typeof value.broker.tokenFile !== 'string' || !isAbsolute(value.broker.tokenFile)
+      || value.broker.caFile !== undefined && (typeof value.broker.caFile !== 'string' || !isAbsolute(value.broker.caFile))
+      || value.project !== undefined && (typeof value.project !== 'string' || !value.project.trim() || [...value.project].length > 256 || /[\x00-\x1f\x7f-\x9f]/.test(value.project))
+      || value.projectEnv !== undefined && (typeof value.projectEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value.projectEnv))
+      || value.name !== undefined && (typeof value.name !== 'string' || !value.name.trim() || value.name.length > 100 || /[\x00-\x1f\x7f]/.test(value.name))) fail();
+    const url = new URL(value.broker.url);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') fail();
+    if (marked) Object.defineProperty(value, 'enrollmentReceiptRequired', { value: true });
+    return value;
+  } catch { fail(); }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+export function privateDirectory(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077 || realpathSync(path) !== path
+    || process.getuid && stat.uid !== process.getuid()) fail();
+  return path;
+}

package/src/enrollment.mjs

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readConfig } from './config.mjs';
+
+export const ENROLLMENT_SHA256 = 'afeab00d7c2d6768d3537bd7c350e249768897bf81eff9b4ae9796f7c3f9dbe9';
+async function helper() {
+  const path = fileURLToPath(new URL('../vendor/enrollment/enrollment.mjs', import.meta.url));
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536
+    || createHash('sha256').update(readFileSync(path)).digest('hex') !== ENROLLMENT_SHA256) throw new Error('enrollment_snapshot_mismatch');
+  return import('../vendor/enrollment/enrollment.mjs');
+}
+
+/** Legacy environment mode may load an existing bundle, never issue credentials. */
+export async function readExistingConnection(path, { identityRecovery = false } = {}) {
+  const settings = readConfig(path);
+  if (settings.enrollmentReceiptRequired) {
+    try { settings.enrollment = (await helper()).readEnrollmentReceipt({ connectionFile: path, clientType: 'opencode' }); }
+    catch (error) {
+      // The pinned helper checks receipt/token/type/origin integrity before its
+      // final expiry check. This mode is only for existing identity discovery,
+      // never connection, activation, selection or enrollment.
+      if (!identityRecovery || error.code !== 'credential_expired') throw error;
+      settings.authorizationExpired = true;
+    }
+  }
+  return settings;
+}
+
+/** Only the native explicit-connect command calls this. No model tool accepts a secret. */
+export function createConnectionLoader({ directory, stateHome = process.env.XDG_STATE_HOME || join(homedir(), '.local', 'state'),
+  loadHelper = helper } = {}) {
+  if (!isAbsolute(directory) || !isAbsolute(stateHome)) throw new Error('private_directory_required');
+  return async function connectFile(path, { clientType, sessionID }) {
+    if (clientType !== 'opencode' || typeof path !== 'string' || !isAbsolute(path)
+      || /[\x00-\x1f\x7f]/.test(path) || typeof sessionID !== 'string' || !sessionID) throw new Error('private_file_required');
+    let settings;
+    try { settings = readConfig(path); } catch { /* The shared helper independently validates pairing files. */ }
+    if (settings) {
+      // The explicit bundle marker makes missing/corrupt receipts fatal.
+      if (settings.enrollmentReceiptRequired) {
+        const api = await loadHelper();
+        settings.enrollment = api.readEnrollmentReceipt({ connectionFile: path, clientType });
+      }
+    } else {
+      const api = await loadHelper();
+      const key = createHash('sha256').update(JSON.stringify([resolve(directory), sessionID])).digest('hex');
+      const result = await api.connectPairingFile({ pairingFile: path,
+        directory: join(stateHome, 'psst', 'opencode', key), clientType });
+      settings = readConfig(result.connectionFile);
+      settings.enrollment = api.readEnrollmentReceipt({ connectionFile: result.connectionFile, clientType });
+    }
+    if (settings.enrollment && Date.parse(settings.enrollment.expiresAt) <= Date.now()) throw new Error('credential_expired');
+    return settings;
+  };
+}

package/src/identity-recovery.mjs

@@ -0,0 +1,94 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readdirSync, lstatSync, openSync, closeSync, readFileSync, fstatSync, constants } from 'node:fs';
+import { join } from 'node:path';
+import { canonical, validateUuid } from '../vendor/broker/src/protocol.mjs';
+import { privateDirectory } from './config.mjs';
+import { nativeSessionBinding } from './native-delivery.mjs';
+
+// Private persisted names remain compatible; the public plugin is only matuto.psst.
+export function readNativeBindings(settings) {
+  if (!settings) return [];
+  try { lstatSync(settings.stateDirectory); } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  privateDirectory(settings.stateDirectory);
+  const names=readdirSync(settings.stateDirectory).filter(name=>name.startsWith('opencode-v2-'));
+  if(names.length>256)throw new Error('identity_recovery_scan_limit');
+  const records=[];
+  for(const name of names){
+    if(!/^opencode-v2-[a-f0-9]{64}$/.test(name))throw new Error('identity_recovery_invalid');
+    const directory=privateDirectory(join(settings.stateDirectory,name));
+    const fd=openSync(join(directory,'binding.json'),constants.O_RDONLY|constants.O_NOFOLLOW);let record;
+    try{const stat=fstatSync(fd);if(!stat.isFile()||stat.mode&0o077||stat.size>8192||process.getuid&&stat.uid!==process.getuid())throw new Error('identity_recovery_invalid');record=JSON.parse(readFileSync(fd,'utf8'));}finally{closeSync(fd);}
+    if(record.version!==1||Object.keys(record).sort().join(',')!=='binding,broker,identity,version')throw new Error('identity_recovery_invalid');
+    const b=record.binding;
+    if(canonical(nativeSessionBinding({id:b?.sessionID,projectID:b?.projectID,location:b?.location,time:{created:b?.created}},b?.hostID))!==canonical(b))throw new Error('identity_recovery_invalid');
+    if(Object.keys(record.identity??{}).sort().join(',')!=='client_id,client_type,session_instance_id'||record.identity.client_type!=='opencode')throw new Error('identity_recovery_invalid');
+    validateUuid(record.identity.client_id);validateUuid(record.identity.session_instance_id);
+    const hash=createHash('sha256').update(canonical({binding:b,broker:record.broker})).digest('hex');
+    if(name!=='opencode-v2-'+hash)throw new Error('identity_recovery_invalid');
+    if(record.broker===settings.broker.url)records.push(record);
+  }
+  return records;
+}
+
+export async function recoverHostAnchor({storage,session,settings,directory,workspaceID}) {
+  const saved=await storage.get('psst-v2-host-id');
+  const records=readNativeBindings(settings);
+  // Shared approved installations may hold mailboxes belonging to other native
+  // hosts. An existing anchor is not replaced based on unrelated manifests.
+  if(saved!==undefined)return saved;
+  async function freshAnchor(){
+    let names=[];
+    try{if(settings)names=readdirSync(settings.stateDirectory);}catch(error){if(error.code!=='ENOENT')throw error;}
+    for(const name of names.filter(n=>n.startsWith('opencode-')&&!n.startsWith('opencode-v2-'))){
+      const path=join(settings.stateDirectory,name),stat=lstatSync(path);
+      if(stat.isSymbolicLink())throw new Error('identity_recovery_invalid');
+      if(!stat.isDirectory())continue;
+      privateDirectory(path);
+      // The old classic layout has no exact current native-session proof.
+      // Keep it intact instead of allocating a replacement identity.
+      throw new Error('identity_legacy_migration_required');
+    }
+    const id=randomUUID();await storage.set('psst-v2-host-id',id);return id;
+  }
+  const candidates=records.filter(r=>r.binding.location.directory===directory
+    && r.binding.location.workspaceID===workspaceID);
+  const anchors=new Set(),deadline=Date.now()+5000;
+  let index=0,incomplete=false,unproven=false;
+  await Promise.all(Array.from({length:Math.min(4,candidates.length)},async()=>{
+    while(index<candidates.length){
+      const record=candidates[index++],remaining=deadline-Date.now();
+      if(remaining<=0){incomplete=true;return;}
+      const signal=AbortSignal.timeout(Math.max(1,Math.min(2000,remaining)));let listener,info;
+      try{
+        info=await Promise.race([session.get({sessionID:record.binding.sessionID},{signal}),
+          new Promise((_,reject)=>{listener=()=>reject(new Error('identity_recovery_timeout'));signal.addEventListener('abort',listener,{once:true});})]);
+      }catch(error){
+        // The official public API tags absent sessions. Other failures are not
+        // evidence that a second anchor is unrelated; preserve and stop.
+        if(error?._tag!=='SessionNotFoundError'||error.sessionID!==record.binding.sessionID){incomplete=true;return;}
+        continue;
+      }finally{if(listener)signal.removeEventListener('abort',listener);}
+      // A successful lookup with a changed or unusable live binding is not
+      // absence. It must not authorize a fresh anchor or partial recovery.
+      if(!info||info.parentID||info.time?.archived){unproven=true;continue;}
+      try{
+        if(canonical(nativeSessionBinding(info,record.binding.hostID))===canonical(record.binding))anchors.add(record.binding.hostID);
+        else unproven=true;
+      }catch{unproven=true;}
+    }
+  }));
+  if(incomplete)throw new Error('identity_recovery_incomplete');
+  if(anchors.size>1)throw new Error('identity_recovery_ambiguous');
+  if(unproven)throw new Error('identity_recovery_required');
+  // No candidate, or every candidate positively absent in this native store:
+  // allocate an independent host without adopting or changing old mailboxes.
+  if(!anchors.size)return freshAnchor();
+  const [hostID]=anchors;
+  await storage.set('psst-v2-host-id',hostID);
+  return hostID;
+}
+
+export function assertExistingBinding(settings,binding){
+  const matches=readNativeBindings(settings).filter(r=>r.binding.sessionID===binding.sessionID);
+  if(matches.length>1||matches.some(r=>canonical(r.binding)!==canonical(binding)))throw new Error('identity_recovery_conflict');
+}

package/src/installation.mjs

@@ -0,0 +1,127 @@
+import { openSync, closeSync, readFileSync, writeFileSync, fsyncSync, fstatSync, lstatSync, realpathSync, renameSync, unlinkSync, constants } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { privateDirectory } from './config.mjs';
+import { readExistingConnection } from './enrollment.mjs';
+
+export function installationDirectory(env = process.env) {
+  const directory = env.PSST_OPENCODE_CONFIG_DIR || join(env.OPENCODE_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'opencode'), 'psst');
+  if (!isAbsolute(directory)) throw new Error('psst_private_absolute_directory_required');
+  return directory;
+}
+function read(path) {
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.mode & 0o077 || stat.size > 8192 || process.getuid && stat.uid !== process.getuid()) throw new Error();
+    const value = JSON.parse(readFileSync(fd, 'utf8'));
+    if (value?.format !== 'psst-opencode-installation-v1' || typeof value.revision !== 'string'
+      || !isAbsolute(value.connectionFile) || Object.keys(value).some(k => !['format', 'revision', 'connectionFile'].includes(k))) throw new Error();
+    return value;
+  } catch (error) { if (error.code === 'ENOENT') return null; throw new Error('psst_installation_invalid'); }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+export function readSelection(directory = installationDirectory()) {
+  try {
+    const stat = lstatSync(directory);
+    if (!isAbsolute(directory) || !stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077
+      || realpathSync(directory) !== directory || process.getuid && stat.uid !== process.getuid()) throw new Error('psst_installation_invalid');
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  return read(join(directory, 'installation.json'));
+}
+export async function readInstallation(directory = installationDirectory(), readOptions) {
+  const selected = readSelection(directory);
+  return selected ? readExistingConnection(selected.connectionFile, readOptions) : undefined;
+}
+/** No network. Compare-and-swap fences concurrent UI flows; never deletes old bundles/inboxes. */
+export async function selectInstallation({ directory = installationDirectory(), connectionFile, expectedRevision, signal, pendingFlowId, verify }) {
+  await readExistingConnection(connectionFile); // exact broker approval receipt, type, URL and token binding
+  if (verify !== undefined && (typeof verify !== 'function' || !await verify())) throw new Error('psst_setup_binding_changed');
+  return withSelectionLock(directory, () => {
+  let temp;
+  try {
+    if (signal?.aborted) throw new Error('psst_setup_cancelled');
+    if (pendingFlowId) {
+      const pending = readPendingFile(directory);
+      if (!pending || pending.paused || pending.flowId !== pendingFlowId) throw new Error('psst_setup_cancelled');
+    }
+    const previous = readSelection(directory);
+    if (pendingFlowId && previous?.connectionFile === connectionFile) {
+      writePending(directory, { ...readPendingFile(directory), paused: true });
+      return previous; // Reconcile crash after committed selection, not a replacement.
+    }
+    if ((previous?.revision ?? null) !== expectedRevision) throw new Error('psst_selection_changed');
+    const value = { format: 'psst-opencode-installation-v1', revision: randomUUID(), connectionFile };
+    temp = join(directory, `.selection-${randomUUID()}`);
+    const out = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try { writeFileSync(out, JSON.stringify(value) + '\n'); fsyncSync(out); } finally { closeSync(out); }
+    renameSync(temp, join(directory, 'installation.json')); temp = null;
+    const dir = openSync(directory, constants.O_RDONLY); try { fsyncSync(dir); } finally { closeSync(dir); }
+    if (pendingFlowId) writePending(directory, { ...readPendingFile(directory), paused: true });
+    return value;
+  } finally { if (temp) unlinkSync(temp); }
+  });
+}
+
+function readPendingFile(directory) {
+  let fd;
+  try {
+    fd = openSync(join(directory, 'pending.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.mode & 0o077 || stat.size > 8192 || process.getuid && stat.uid !== process.getuid()) throw new Error();
+    const value = JSON.parse(readFileSync(fd, 'utf8'));
+    const url = new URL(value.brokerUrl);
+    if (value.format !== 'psst-opencode-pending-v1' || typeof value.flowId !== 'string' || typeof value.paused !== 'boolean'
+      || value.expectedRevision !== null && typeof value.expectedRevision !== 'string'
+      || value.requestId !== null && typeof value.requestId !== 'string'
+      || value.previousRequestId !== undefined && value.previousRequestId !== null && typeof value.previousRequestId !== 'string'
+      || value.owner !== undefined && (!value.owner || Object.keys(value.owner).sort().join(',') !== 'binding,sessionID'
+        || typeof value.owner.sessionID !== 'string' || value.owner.sessionID.length > 256
+        || typeof value.owner.binding !== 'string' || value.owner.binding.length > 4096)
+      || url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error();
+    return value;
+  } catch (error) { if (error.code === 'ENOENT') return null; throw new Error('psst_pending_invalid'); }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+export function readPending(directory = installationDirectory()) {
+  readSelection(directory); // existing directory ownership/canonical-path check, no creation
+  return readPendingFile(directory);
+}
+function withSelectionLock(directory, action) {
+  privateDirectory(directory);
+  const lock = join(directory, 'installation-lock.sqlite');
+  try { const fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); closeSync(fd); }
+  catch (error) { if (error.code !== 'EEXIST') throw new Error('psst_selection_busy'); }
+  const stat = lstatSync(lock);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.mode & 0o077 || process.getuid && stat.uid !== process.getuid()) throw new Error('psst_installation_invalid');
+  let db;
+  try {
+    db = new DatabaseSync(lock); db.exec('PRAGMA busy_timeout=0; BEGIN IMMEDIATE');
+    const result = action(); db.exec('COMMIT'); return result;
+  } finally { db?.close(); } // OS releases the lock even after a killed process; no stale-lock reset.
+}
+function writePending(directory, value) {
+  const temp = join(directory, `.pending-${randomUUID()}`);
+  const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try { writeFileSync(fd, JSON.stringify(value) + '\n'); fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(temp, join(directory, 'pending.json'));
+  const dir = openSync(directory, constants.O_RDONLY); try { fsyncSync(dir); } finally { closeSync(dir); }
+}
+export function savePending({ directory = installationDirectory(), brokerUrl, expectedRevision, requestId = null, previousRequestId, owner }) {
+  return withSelectionLock(directory, () => {
+    readPendingFile(directory); // Explicit setup is not permission to reset corrupt state.
+    const value = { format: 'psst-opencode-pending-v1', flowId: randomUUID(), brokerUrl, expectedRevision, requestId, paused: false, ...(owner ? { owner } : {}), ...(previousRequestId ? { previousRequestId } : {}) };
+    writePending(directory, value); return value;
+  });
+}
+export function updatePending({ directory = installationDirectory(), flowId, paused, requestId }) {
+  return withSelectionLock(directory, () => {
+    const value = readPendingFile(directory);
+    if (!value || value.flowId !== flowId) return false;
+    writePending(directory, { ...value, ...(paused !== undefined ? { paused } : {}), ...(requestId !== undefined ? { requestId } : {}) });
+    return true;
+  });
+}