@matuto-ai/opencode-broker-connector 0.1.1 → 0.3.0

package/src/setup-ui.mjs

@@ -0,0 +1,100 @@
+import { loadApprovalHelper } from './approval-helper.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { installationDirectory, readSelection, selectInstallation, savePending, updatePending } from './installation.mjs';
+
+/** Host-owned form, not a model tool or a conversation command. */
+export async function installSetupUI(api, { directory = installationDirectory(), loadHelper = loadApprovalHelper,
+  select = selectInstallation, pause = (signal, ms = 2000) => delay(ms, undefined, { signal }) } = {}) {
+  let current, pending;
+  const cancel = (pause = true) => {
+    current?.abort(); current = undefined;
+    if (pause && pending) { try { updatePending({ directory, flowId: pending.flowId, paused: true }); } catch {} }
+    pending = undefined;
+  };
+  api.lifecycle.onDispose(() => cancel(false));
+  function toast(message, variant = 'info') { api.ui.toast({ title: 'Psst', message, variant, duration: 6000 }); }
+  function start() {
+    cancel();
+    const controller = new AbortController(); current = controller;
+    const alive = () => current === controller && !controller.signal.aborted && !api.lifecycle.signal.aborted;
+    let submitted = false, transitioning = false;
+    const close = () => { if (!transitioning && current === controller) cancel(); };
+    function replace(render) { transitioning = true; try { api.ui.dialog.replace(render, close); } finally { transitioning = false; } }
+    replace(() => api.ui.DialogPrompt({
+      title: 'Psst setup — broker URL', placeholder: 'https://broker.example',
+      onCancel: close,
+      onConfirm: async value => {
+        if (!alive() || submitted) return;
+        submitted = true;
+        try {
+          const brokerUrl = new URL(value.trim());
+          if (brokerUrl.protocol !== 'https:' || brokerUrl.username || brokerUrl.password || brokerUrl.search || brokerUrl.hash || brokerUrl.pathname !== '/') throw new Error();
+          const helper = await loadHelper();
+          if (!alive()) return;
+          const selected = readSelection(directory);
+          const expectedRevision = selected?.revision ?? null;
+          const options = { directory, brokerUrl: brokerUrl.href, clientType: 'opencode' };
+          const prior = helper.readApprovalState(options);
+          async function enroll(replaceRequestId) {
+            if (!alive()) return;
+            pending = savePending({ directory, brokerUrl: brokerUrl.href, expectedRevision, requestId: replaceRequestId ? null : prior?.requestId ?? null });
+            const flowId = pending.flowId;
+            replace(() => api.ui.DialogAlert({ title: 'Psst approval pending',
+              message: 'Preparing the durable request. Close to pause; setup resumes the same request.',
+              onConfirm: close }));
+            async function retry(operation) {
+              while (alive()) {
+                try { return await operation(); }
+                catch (error) { if (!error.retryable) throw error; await pause(controller.signal, Math.min(300000, Math.max(2000, error.retryAfterMs || 2000))); }
+              }
+              throw new Error('psst_setup_cancelled');
+            }
+            let result = await retry(() => helper.beginApproval({ ...options, ...(replaceRequestId ? { replaceRequestId } : {}) }));
+            const requestId = result.requestId;
+            if (!replaceRequestId && prior?.state === 'pending' && requestId !== prior.requestId) throw new Error('psst_request_changed');
+            if (alive()) {
+              updatePending({ directory, flowId, requestId });
+              if (result.state === 'pending') replace(() => api.ui.DialogAlert({
+                title: 'Psst approval pending',
+                message: `Open ${new URL('/admin', brokerUrl).href}
+Request ID: ${requestId}
+Approve only the matching OpenCode request. Close to pause; setup resumes this same request.`,
+                onConfirm: close }));
+            }
+            while (alive() && result.state === 'pending') {
+              await pause(controller.signal);
+              if (alive()) {
+                result = await retry(() => helper.pollApproval(options));
+                if (result.requestId !== requestId) throw new Error('psst_request_changed');
+              }
+            }
+            if (!alive()) return;
+            if (result.state !== 'approved') { toast(`Request ${result.state}. Run setup explicitly to request replacement.`, 'warning'); close(); api.ui.dialog.clear(); return; }
+            await select({ directory, connectionFile: result.connectionFile, expectedRevision, signal: controller.signal, pendingFlowId: flowId });
+            if (!alive()) return;
+            close(); api.ui.dialog.clear();
+            toast(process.env.PSST_CONFIG_FILE
+              ? 'Approved installation saved. The explicit PSST_CONFIG_FILE override still takes precedence; restart without it to use the saved approval. Existing connections are unchanged.'
+              : 'Approved installation saved. New sessions connect automatically; existing sessions retain their authorization. Receive remains cooperative.', 'success');
+          }
+          if (prior && prior.state !== 'pending' && (prior.state !== 'approved' || selected?.connectionFile === prior.connectionFile)) {
+            replace(() => api.ui.DialogConfirm({ title: 'Replace Psst authorization?',
+              message: 'Request a new authorization? The current connection and unread messages remain unchanged until approval; existing sessions keep their connection.',
+              onCancel: close, onConfirm: () => {
+                // The native confirmation clears its dialog after this callback.
+                transitioning = true; queueMicrotask(() => { transitioning = false; void enroll(prior.requestId).catch(failed); });
+              } }));
+          } else await enroll();
+        } catch { failed(); }
+        function failed() {
+          if (!alive()) return;
+          toast('Setup paused. Check the URL, private configuration and broker availability; retry setup to resume the same request. No credentials were replaced.', 'warning');
+          cancel(false); api.ui.dialog.clear();
+        }
+      },
+    }));
+  }
+  api.keymap.registerLayer({ commands: [{ name: 'psst.setup', title: 'Psst: setup broker connection',
+    category: 'Psst', namespace: 'palette', slashName: 'psst-setup', run: start }],
+    bindings: [{ key: 'ctrl+alt+p', cmd: 'psst.setup', desc: 'Set up Psst broker connection' }] });
+}

package/vendor/enrollment/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Orsolon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/enrollment/ORIGIN.md

@@ -0,0 +1,20 @@
+# Shared enrollment helper
+
+Unmodified `reference/enrollment.mjs` from `matuto-ai/psst` commit `3e908e79966d886a02d372c103e31dec6e900c1a`, independently compared byte-for-byte with the remote committed source. Upstream PR #18 is pending review/merge; this commit pin is not a deployment or release claim.
+
+SHA-256: `afeab00d7c2d6768d3537bd7c350e249768897bf81eff9b4ae9796f7c3f9dbe9`.
+
+Runtime hash checked by `src/enrollment.mjs` before import. MIT license copied alongside. The existing pinned broker transport/runtime remains unchanged at its separate origin.
+
+Source: https://github.com/matuto-ai/psst/blob/3e908e79966d886a02d372c103e31dec6e900c1a/reference/enrollment.mjs
+Operator guide at that commit: https://github.com/matuto-ai/psst/blob/3e908e79966d886a02d372c103e31dec6e900c1a/docs/pairing-operator.md
+
+## URL-only approval helper
+
+`approval.mjs` is vendored byte-for-byte from `matuto-ai/psst` commit
+`72f5d2d1b834e02cfb6b2f7dc11c6f1a55729344`, path `reference/approval.mjs`,
+Git blob `8e6128c22835e66c0ab50aa15c27ff16d33e1169`, SHA-256
+`a60c3a0ccd7deb50556586cd67841bb89a300ea3c7f1af3a91d437f856b7a2d5`.
+This is the explicit broker PR #22 dependency, not a claim of a deployed release.
+The connector checks the digest before importing it. The old enrollment helper
+remains unchanged for legacy bundles/receipts.

package/vendor/enrollment/approval.mjs

@@ -0,0 +1,181 @@
+// Single-file helper deliberately vendorable by native connectors. Never emits secrets.
+import { randomBytes, randomUUID, createHash } from 'node:crypto';
+import { openSync, closeSync, fstatSync, readFileSync, writeFileSync, fsyncSync, renameSync, unlinkSync, mkdirSync, lstatSync, realpathSync, readdirSync, constants } from 'node:fs';
+import { resolve, dirname, join, isAbsolute } from 'node:path';
+import https from 'node:https';
+import { DatabaseSync } from 'node:sqlite';
+
+const TYPES = ['pi','claude-code','opencode','antigravity-cli'];
+const fail = (code, effect = 'not_applied', retryable=false, retryAfterMs=2000) => { const e = new Error(code); Object.assign(e,{code,effect,retryable,...(retryable?{retryAfterMs:Math.max(1000,Math.min(300000,Math.ceil(retryAfterMs)))}:{})}); throw e; };
+const hash = value => createHash('sha256').update(value).digest('hex');
+function privateDir(path) {
+  if (!isAbsolute(path)) fail('private_directory_required');
+  mkdirSync(path, {recursive:true, mode:0o700});
+  const s = lstatSync(path);
+  if (!s.isDirectory() || s.isSymbolicLink() || realpathSync(path) !== resolve(path) || (s.mode & 0o077) || (process.getuid && s.uid !== process.getuid())) fail('private_directory_required');
+}
+function privateRead(path) {
+  if (!isAbsolute(path) || realpathSync(dirname(path)) !== resolve(dirname(path))) fail('private_file_required');
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const s = fstatSync(fd);
+    if (!s.isFile() || s.size > 65536 || (s.mode & 0o077) || (process.getuid && s.uid !== process.getuid())) fail('private_file_required');
+    return readFileSync(fd,'utf8');
+  } finally { closeSync(fd); }
+}
+function save(path, text) {
+  // Reject unsafe existing destinations rather than silently repairing their mode.
+  try { privateRead(path); } catch(e) { if(e.code !== 'ENOENT') throw e; }
+  const temp = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(temp, constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,0o600);
+  try { writeFileSync(fd,text); fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(temp,path);
+  const d = openSync(dirname(path),constants.O_RDONLY);try { fsyncSync(d); } finally { closeSync(d); }
+}
+function origin(value) {
+  let u; try { u = new URL(value); } catch { fail('https_origin_required'); }
+  if (typeof value !== 'string' || /[\u0000-\u0020\u007f]/u.test(value) || u.protocol !== 'https:' || u.username || u.password || u.pathname !== '/' || u.search || u.hash) fail('https_origin_required');
+  return u.origin;
+}
+const stateNames=['pending','approved','denied','expired','revoked'];
+const uuid=/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function locations({brokerUrl,directory,clientType}) {
+  if(!TYPES.includes(clientType))fail('invalid_client_type');
+  if(!isAbsolute(directory))fail('private_directory_required');
+  const broker=origin(brokerUrl),root=join(directory,'approvals',hash(broker+'\0'+clientType));
+  return {broker,root,current:join(root,'current.json'),clientType};
+}
+function load(loc) {
+  let pointer;try{pointer=JSON.parse(privateRead(loc.current));}catch(e){if(e.code==='ENOENT')return null;throw e;}
+  if(!pointer||!uuid.test(pointer.requestId))fail('invalid_approval_state');
+  const dir=join(loc.root,pointer.requestId),state=JSON.parse(privateRead(join(dir,'attempt.json')));
+  if(state.requestId!==pointer.requestId||state.brokerUrl!==loc.broker||state.clientType!==loc.clientType
+    ||!/^[A-Za-z0-9_-]{43}$/.test(state.token)||!stateNames.includes(state.state)
+    ||typeof state.label!=='string'||state.label.length>80)fail('invalid_approval_state');
+  return {state,dir};
+}
+function visible({state,dir}) {
+  const result={requestId:state.requestId,approvalUrl:state.brokerUrl+'/admin',state:state.state,requestExpiresAt:state.requestExpiresAt??null};
+  if(state.state==='approved'){
+    if(!state.credential||Date.parse(state.credential.expires_at)<=Date.now())return {...result,state:'expired'};
+    result.connectionFile=join(dir,'connection.json');
+    Object.assign(result,readEnrollmentReceipt({connectionFile:result.connectionFile,clientType:state.clientType}));
+  }
+  return result;
+}
+function sanitized(e) {
+  if(e.effect&&/^[a-z_]+$/.test(e.code))throw e;
+  fail('approval_local_error','unknown');
+}
+export function readApprovalState(options) {
+  try{const item=load(locations(options));return item?visible(item):null;}catch(e){sanitized(e);}
+}
+function request(broker,method,path,token,input) {
+  return new Promise((resolvePromise,reject)=>{
+    const body=input===undefined?undefined:JSON.stringify(input);
+    const transportError=()=>Object.assign(new Error('approval_transport_error'),{code:'approval_transport_error',effect:'unknown',retryable:true,retryAfterMs:2000});
+    const req=https.request(new URL(path,broker),{method,headers:{Authorization:`Enrollment ${token}`,...(body?{'Content-Type':'application/json','Content-Length':Buffer.byteLength(body)}:{})}},res=>{
+      let size=0;const chunks=[];
+      res.on('data',chunk=>{size+=chunk.length;if(size>16384)res.destroy();else chunks.push(chunk);});
+      res.on('error',()=>reject(transportError()));
+      res.on('end',()=>{try{resolvePromise({status:res.statusCode,retryAfter:res.headers['retry-after'],body:JSON.parse(Buffer.concat(chunks).toString('utf8'))});}catch{reject(Object.assign(new Error('invalid_response'),{code:'invalid_response',effect:'unknown',retryable:false}));}});
+    });
+    const timer=setTimeout(()=>req.destroy(),10000);req.on('close',()=>clearTimeout(timer));
+    req.on('error',()=>reject(transportError()));req.end(body);
+  });
+}
+function publish(item,result,broker,clientType){
+  const {state,dir}=item;
+  if(!result||result.request_id!==state.requestId||!stateNames.includes(result.state)
+    ||!Number.isFinite(Date.parse(result.request_expires_at)))fail('invalid_response','unknown');
+  if(result.state==='approved'){
+    const c=result.credential;
+    if(!c||c.protocol_version!=='1'||c.client_type!==clientType||!/^enrolled-[0-9a-f-]{36}$/.test(c.credential_id)
+      ||!/^installation-[0-9a-f-]{36}$/.test(c.adapter_id)||!Array.isArray(c.scopes)||!c.scopes.length||c.scopes.length>32
+      ||c.scopes.some(s=>typeof s!=='string'||!/^[-a-zA-Z0-9_.]{1,128}$/.test(s))||!Number.isFinite(Date.parse(c.expires_at)))fail('invalid_response','unknown');
+    if(Date.parse(c.expires_at)<=Date.now())fail('credential_expired');
+    save(join(dir,'token'),state.token+'\n');
+    save(join(dir,'enrollment.json'),JSON.stringify({format:'psst-enrollment-receipt-v1',broker_url:broker,...c,token_sha256:hash(state.token)})+'\n');
+    save(join(dir,'connection.json'),JSON.stringify({format:'broker-client-bundle-v1',protocol_version:'1',broker_url:broker,token_file:'token',enrollment_receipt_file:'enrollment.json',file_paths_relative_to:'connection_file_directory',authorization_header:'Authorization',authorization_scheme:'Bearer',insecure_development:false,allowed_client_types:[clientType],scope:c.scopes[0]})+'\n');
+    state.credential=c;
+  }
+  state.state=result.state;state.requestExpiresAt=result.request_expires_at;
+  save(join(dir,'attempt.json'),JSON.stringify(state)+'\n');return visible(item);
+}
+async function operate(options,begin,{transport=request,pollIntervalMs=2000}={}) {
+  let lock;
+  try {
+    const loc=locations(options);
+    if(!begin&&!load(loc))fail('approval_setup_required');
+    privateDir(options.directory);privateDir(join(options.directory,'approvals'));privateDir(loc.root);
+    const lockPath=join(loc.root,'.owner.sqlite');
+    try{privateRead(lockPath);}catch(e){if(e.code!=='ENOENT')throw e;}
+    const fd=openSync(lockPath,constants.O_WRONLY|constants.O_CREAT|constants.O_NOFOLLOW,0o600);closeSync(fd);
+    try{lock=new DatabaseSync(lockPath);lock.exec('PRAGMA journal_mode=DELETE; PRAGMA locking_mode=EXCLUSIVE; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner(id INTEGER);');}
+    catch{fail('approval_busy','not_applied',true);}
+    let item=load(loc);
+    if(begin){
+      const replacement=options.replaceRequestId;
+      if(replacement!==undefined&&(!uuid.test(replacement)||!item))fail('selection_conflict');
+      if(replacement!==undefined&&item.state.requestId!==replacement&&item.state.parentRequestId!==replacement)fail('selection_conflict');
+      if(replacement!==undefined&&item.state.requestId===replacement&&item.state.state==='pending')fail('selection_conflict');
+      if(!item||(replacement!==undefined&&item.state.requestId===replacement)){
+        if(readdirSync(loc.root).length>=130)fail('approval_capacity');
+        const label=options.label??options.clientType;
+        if(typeof label!=='string'||label.length>80||/[\u0000-\u001f\u007f]/u.test(label))fail('invalid_request');
+        const state={requestId:randomUUID(),parentRequestId:replacement??null,brokerUrl:loc.broker,clientType:options.clientType,label,token:randomBytes(32).toString('base64url'),state:'pending'};
+        const dir=join(loc.root,state.requestId);privateDir(dir);
+        save(join(dir,'attempt.json'),JSON.stringify(state)+'\n');
+        save(loc.current,JSON.stringify({requestId:state.requestId})+'\n');item={state,dir};
+      }
+    }
+    if(!item)fail('approval_setup_required');
+    if(item.state.state!=='pending')return visible(item);
+    const s=item.state;
+    if(Number.isFinite(s.retryAt)&&s.retryAt>Date.now()&&s.retryAt-Date.now()<=300000)fail(s.retryCode??'rate_limited',s.retryEffect??'unknown',true,s.retryAt-Date.now());
+    if(!begin){
+      const now=Date.now();
+      if(Number.isFinite(s.lastPollAt)&&now>=s.lastPollAt&&now-s.lastPollAt<pollIntervalMs)return visible(item);
+      s.lastPollAt=now;save(join(item.dir,'attempt.json'),JSON.stringify(s)+'\n');
+    }
+    const path=begin?'/v1/enrollment-requests':`/v1/enrollment-requests/${s.requestId}`;
+    const response=await transport(loc.broker,begin?'POST':'GET',path,s.token,begin?{request_id:s.requestId,client_type:s.clientType,label:s.label}:undefined);
+    if(![200,201].includes(response.status)){
+      const code=response.body?.error?.code;
+      let retryAfterMs=response.status===429?60000:5000;
+      if(typeof response.retryAfter==='string'){
+        const seconds=/^[0-9]{1,6}$/.test(response.retryAfter)?Number(response.retryAfter):NaN;
+        const parsed=Number.isFinite(seconds)?seconds*1000:Date.parse(response.retryAfter)-Date.now();
+        if(Number.isFinite(parsed))retryAfterMs=Math.max(1000,Math.min(300000,Math.ceil(parsed)));
+      }
+      if([429,503].includes(response.status)){s.retryAt=Date.now()+retryAfterMs;s.retryCode=code==='not_ready'||code==='storage_unavailable'?code:'rate_limited';s.retryEffect=response.body?.error?.effect==='not_applied'?'not_applied':'unknown';save(join(item.dir,'attempt.json'),JSON.stringify(s)+'\n');}
+      fail(['unauthenticated','forbidden','invalid_request','idempotency_conflict','rate_limited','not_ready','storage_unavailable'].includes(code)?code:'invalid_response',response.body?.error?.effect==='not_applied'?'not_applied':'unknown',[429,503].includes(response.status),retryAfterMs);
+    }
+    delete s.retryAt;delete s.retryCode;delete s.retryEffect;
+    return publish(item,response.body,loc.broker,options.clientType);
+  }catch(e){sanitized(e);}finally{try{lock?.close();}catch{}}
+}
+export const beginApproval=(options,testOptions)=>operate(options,true,testOptions);
+export const pollApproval=(options,testOptions)=>operate(options,false,testOptions);
+
+/** Read only for a helper-enrolled bundle. Missing/corrupt receipt is not a legacy fallback. */
+export function readEnrollmentReceipt({connectionFile,clientType}) {
+  try {
+    if(!TYPES.includes(clientType))fail('invalid_client_type');
+    const bundle=JSON.parse(privateRead(connectionFile));
+    const receipt=JSON.parse(privateRead(join(dirname(connectionFile),'enrollment.json')));
+    const token=privateRead(join(dirname(connectionFile),'token')).trim();
+    if(bundle?.format!=='broker-client-bundle-v1'||bundle.protocol_version!=='1'||bundle.token_file!=='token'||bundle.enrollment_receipt_file!=='enrollment.json'
+      ||bundle.authorization_scheme!=='Bearer'||bundle.authorization_header!=='Authorization'||bundle.insecure_development!==false
+      ||!Array.isArray(bundle.allowed_client_types)||bundle.allowed_client_types.length!==1||bundle.allowed_client_types[0]!==clientType
+      ||receipt?.format!=='psst-enrollment-receipt-v1'||receipt.protocol_version!=='1'||receipt.client_type!==clientType
+      ||receipt.broker_url!==origin(bundle.broker_url)||!/^[A-Za-z0-9_-]{43}$/.test(token)||receipt.token_sha256!==hash(token)
+      ||!/^enrolled-[0-9a-f-]{36}$/.test(receipt.credential_id)||!/^installation-[0-9a-f-]{36}$/.test(receipt.adapter_id)
+      ||!Array.isArray(receipt.scopes)||!receipt.scopes.length||receipt.scopes[0]!==bundle.scope||!Number.isFinite(Date.parse(receipt.expires_at)))fail('invalid_enrollment_receipt');
+    if(Date.parse(receipt.expires_at)<=Date.now())fail('credential_expired');
+    return {credentialId:receipt.credential_id,expiresAt:receipt.expires_at};
+  } catch(e) {
+    if(e.effect&&/^[a-z_]+$/.test(e.code))throw e;
+    fail('invalid_enrollment_receipt');
+  }
+}

package/vendor/enrollment/enrollment.mjs

@@ -0,0 +1,137 @@
+// Single-file helper deliberately vendorable by native connectors. Never emits secrets.
+import { randomBytes, randomUUID, createHash } from 'node:crypto';
+import { openSync, closeSync, fstatSync, readFileSync, writeFileSync, fsyncSync, renameSync, unlinkSync, mkdirSync, lstatSync, realpathSync, readdirSync, constants } from 'node:fs';
+import { resolve, dirname, join, isAbsolute } from 'node:path';
+import https from 'node:https';
+import { DatabaseSync } from 'node:sqlite';
+
+const TYPES = ['pi','claude-code','opencode','antigravity-cli'];
+const fail = (code, effect = 'not_applied') => { const e = new Error(code); e.code = code; e.effect = effect; throw e; };
+const hash = value => createHash('sha256').update(value).digest('hex');
+function privateDir(path) {
+  if (!isAbsolute(path)) fail('private_directory_required');
+  mkdirSync(path, {recursive:true, mode:0o700});
+  const s = lstatSync(path);
+  if (!s.isDirectory() || s.isSymbolicLink() || realpathSync(path) !== resolve(path) || (s.mode & 0o077) || (process.getuid && s.uid !== process.getuid())) fail('private_directory_required');
+}
+function privateRead(path) {
+  if (!isAbsolute(path) || realpathSync(dirname(path)) !== resolve(dirname(path))) fail('private_file_required');
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const s = fstatSync(fd);
+    if (!s.isFile() || s.size > 65536 || (s.mode & 0o077) || (process.getuid && s.uid !== process.getuid())) fail('private_file_required');
+    return readFileSync(fd,'utf8');
+  } finally { closeSync(fd); }
+}
+function save(path, text) {
+  // Reject unsafe existing destinations rather than silently repairing their mode.
+  try { privateRead(path); } catch(e) { if(e.code !== 'ENOENT') throw e; }
+  const temp = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(temp, constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,0o600);
+  try { writeFileSync(fd,text); fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(temp,path);
+  const d = openSync(dirname(path),constants.O_RDONLY);try { fsyncSync(d); } finally { closeSync(d); }
+}
+function origin(value) {
+  let u; try { u = new URL(value); } catch { fail('https_origin_required'); }
+  if (typeof value !== 'string' || /[\u0000-\u0020\u007f]/u.test(value) || u.protocol !== 'https:' || u.username || u.password || u.pathname !== '/' || u.search || u.hash) fail('https_origin_required');
+  return u.origin;
+}
+function post(url, secret, body) {
+  return new Promise((resolvePromise,reject) => {
+    const request = https.request(new URL('/v1/enrollments',url), {method:'POST',headers:{Authorization:`Pairing ${secret}`,'Content-Type':'application/json','Content-Length':Buffer.byteLength(body)}, timeout:10000}, response => {
+      let size=0;const chunks=[];
+      response.on('data',chunk=>{size+=chunk.length;if(size>16384)response.destroy(new Error('invalid_response'));else chunks.push(chunk);});
+      response.on('error',()=>reject(Object.assign(new Error('enrollment_transport_error'),{code:'enrollment_transport_error',effect:'unknown'})));
+      response.on('end',()=>{
+        try { resolvePromise({status:response.statusCode,body:JSON.parse(Buffer.concat(chunks).toString('utf8'))}); }
+        catch { reject(Object.assign(new Error('invalid_response'),{code:'invalid_response',effect:'unknown'})); }
+      });
+    });
+    const deadline=setTimeout(()=>request.destroy(),10000);
+    request.on('close',()=>clearTimeout(deadline));
+    request.on('timeout',()=>request.destroy());
+    request.on('error',()=>reject(Object.assign(new Error('enrollment_transport_error'),{code:'enrollment_transport_error',effect:'unknown'})));
+    request.end(body);
+  });
+}
+/** Explicit connect only. The optional transport is a test seam, never a user configuration field. */
+export async function connectPairingFile({pairingFile,directory,clientType,brokerUrl}, {transport = post} = {}) {
+  let lock, lockPath;
+  try {
+    if (!TYPES.includes(clientType)) fail('invalid_client_type');
+    const pair = JSON.parse(privateRead(pairingFile));
+    if (!pair || pair.format !== 'psst-pairing-v1' || pair.client_type !== clientType || typeof pair.pairing_secret !== 'string'
+      || !/^[A-Za-z0-9_-]{43}$/.test(pair.pairing_secret) || !Number.isFinite(Date.parse(pair.expires_at))) fail('invalid_pairing_file');
+    const broker = origin(pair.broker_url);
+    if (brokerUrl !== undefined && origin(brokerUrl) !== broker) fail('broker_origin_mismatch');
+    privateDir(directory);
+    lockPath = join(directory,'.enrollment-owner.sqlite');
+    // Kernel-held SQLite lock survives no process crash; no stale PID or lock deletion.
+    try { privateRead(lockPath); } catch(e) { if(e.code!=='ENOENT')throw e; }
+    const ownerFd=openSync(lockPath,constants.O_WRONLY|constants.O_CREAT|constants.O_NOFOLLOW,0o600);closeSync(ownerFd);
+    try {
+      lock = new DatabaseSync(lockPath);
+      lock.exec('PRAGMA journal_mode=DELETE; PRAGMA locking_mode=EXCLUSIVE; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner (id INTEGER);');
+    } catch { try{lock?.close();}catch{}lock=undefined;fail('enrollment_busy'); }
+    // Per-grant attempts preserve old credentials for uncertain recovery and explicit replacement.
+    const attempts = join(directory,'enrollments');privateDir(attempts);
+    const key = hash(pair.pairing_secret), attemptDir = join(attempts,key);
+    if (!readdirSync(attempts).includes(key) && readdirSync(attempts).length >= 64) fail('enrollment_capacity');
+    privateDir(attemptDir);
+    const stateFile = join(attemptDir,'attempt.json');
+    let state;
+    try { state = JSON.parse(privateRead(stateFile)); }
+    catch(e) {
+      if(e.code !== 'ENOENT')throw e;
+      state = {broker_url:broker,client_type:clientType,enrollment_id:randomUUID(),token:randomBytes(32).toString('base64url')};
+      save(stateFile,JSON.stringify(state)+'\n'); // fsync before any issuance can happen
+    }
+    if (state.broker_url !== broker || state.client_type !== clientType || !/^[A-Za-z0-9_-]{43}$/.test(state.token)
+      || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(state.enrollment_id)) fail('invalid_enrollment_state');
+    const response = await transport(broker,pair.pairing_secret,JSON.stringify({enrollment_id:state.enrollment_id,client_type:clientType,token_sha256:hash(state.token)}));
+    if (![200,201].includes(response.status)) {
+      const code = response.body?.error?.code;
+      fail(['unauthenticated','forbidden','invalid_request','idempotency_conflict','rate_limited','not_ready','storage_unavailable'].includes(code)?code:'invalid_response',response.body?.error?.effect==='not_applied'?'not_applied':'unknown');
+    }
+    const result = response.body;
+    if (!result || result.protocol_version !== '1' || result.client_type !== clientType || !/^enrolled-[0-9a-f-]{36}$/.test(result.credential_id)
+      || !/^installation-[0-9a-f-]{36}$/.test(result.adapter_id) || !Array.isArray(result.scopes) || !result.scopes.length || result.scopes.length>32
+      || result.scopes.some(s=>typeof s!=='string'||!/^[-a-zA-Z0-9_.]{1,128}$/.test(s)) || !Number.isFinite(Date.parse(result.expires_at))) fail('invalid_response','unknown');
+    if(Date.parse(result.expires_at)<=Date.now())fail('credential_expired','unknown');
+    save(join(attemptDir,'token'),state.token+'\n');
+    const bundle = {format:'broker-client-bundle-v1',protocol_version:'1',broker_url:broker,token_file:'token',enrollment_receipt_file:'enrollment.json',file_paths_relative_to:'connection_file_directory',authorization_header:'Authorization',authorization_scheme:'Bearer',insecure_development:false,allowed_client_types:[clientType],scope:result.scopes[0]};
+    const connectionFile = join(attemptDir,'connection.json');
+    // Publish receipt before bundle: the returned bundle always has its token-bound receipt.
+    save(join(attemptDir,'enrollment.json'),JSON.stringify({format:'psst-enrollment-receipt-v1',broker_url:broker,...result,token_sha256:hash(state.token)})+'\n');
+    save(connectionFile,JSON.stringify(bundle,null,2)+'\n');
+    return {connectionFile,credentialId:result.credential_id,expiresAt:result.expires_at};
+  } catch(e) {
+    if (e.effect && /^[a-z_]+$/.test(e.code)) throw e;
+    fail('enrollment_local_error','unknown');
+  } finally {
+    if (lock !== undefined) { try { lock.close(); } catch { /* Never replace a sanitized result with raw filesystem details. */ } }
+  }
+}
+
+/** Read only for a helper-enrolled bundle. Missing/corrupt receipt is not a legacy fallback. */
+export function readEnrollmentReceipt({connectionFile,clientType}) {
+  try {
+    if(!TYPES.includes(clientType))fail('invalid_client_type');
+    const bundle=JSON.parse(privateRead(connectionFile));
+    const receipt=JSON.parse(privateRead(join(dirname(connectionFile),'enrollment.json')));
+    const token=privateRead(join(dirname(connectionFile),'token')).trim();
+    if(bundle?.format!=='broker-client-bundle-v1'||bundle.protocol_version!=='1'||bundle.token_file!=='token'||bundle.enrollment_receipt_file!=='enrollment.json'
+      ||bundle.authorization_scheme!=='Bearer'||bundle.authorization_header!=='Authorization'||bundle.insecure_development!==false
+      ||!Array.isArray(bundle.allowed_client_types)||bundle.allowed_client_types.length!==1||bundle.allowed_client_types[0]!==clientType
+      ||receipt?.format!=='psst-enrollment-receipt-v1'||receipt.protocol_version!=='1'||receipt.client_type!==clientType
+      ||receipt.broker_url!==origin(bundle.broker_url)||!/^[A-Za-z0-9_-]{43}$/.test(token)||receipt.token_sha256!==hash(token)
+      ||!/^enrolled-[0-9a-f-]{36}$/.test(receipt.credential_id)||!/^installation-[0-9a-f-]{36}$/.test(receipt.adapter_id)
+      ||!Array.isArray(receipt.scopes)||!receipt.scopes.length||receipt.scopes[0]!==bundle.scope||!Number.isFinite(Date.parse(receipt.expires_at)))fail('invalid_enrollment_receipt');
+    if(Date.parse(receipt.expires_at)<=Date.now())fail('credential_expired');
+    return {credentialId:receipt.credential_id,expiresAt:receipt.expires_at};
+  } catch(e) {
+    if(e.effect&&/^[a-z_]+$/.test(e.code))throw e;
+    fail('invalid_enrollment_receipt');
+  }
+}