@letterblack/lbe-sdk 0.4.0

package/dist/index.js

@@ -0,0 +1,678 @@
+import crypto from'crypto';import fs from'fs';import os from'os';import path from'path';
+import nacl from'tweetnacl';import{canonicalize}from'json-canonicalize';
+import{runValidationPipeline,checkNonce,checkRateLimit,computeAuditHash,classifyRisk,shouldRollback}from'./engine.js';
+
+// ── Ed25519 sign / verify ─────────────────────────────────────────────────────
+function b64d(s){return Buffer.from(s,'base64')}
+function b64e(b){return Buffer.from(b).toString('base64')}
+function verifyEd25519({payloadObj,sigB64,pubKeyB64}){
+  try{
+    let msg=Buffer.from(canonicalize(payloadObj),'utf8');
+    let ok=nacl.sign.detached.verify(new Uint8Array(msg),new Uint8Array(b64d(sigB64)),new Uint8Array(b64d(pubKeyB64)));
+    return{valid:ok,message:ok?'Signature verified':'Signature verification failed'}
+  }catch(e){return{valid:false,message:`Signature verification error: ${e.message}`}}
+}
+function generateKeyPair(){let k=nacl.sign.keyPair();return{publicKey:b64e(k.publicKey),secretKey:b64e(k.secretKey)}}
+function signPayload({payloadObj,secretKeyB64}){
+  try{
+    let msg=Buffer.from(canonicalize(payloadObj),'utf8');
+    let sig=nacl.sign.detached(new Uint8Array(msg),new Uint8Array(b64d(secretKeyB64)));
+    return{signature:b64e(sig),error:null}
+  }catch(e){return{signature:null,error:`Signing failed: ${e.message}`}}
+}
+
+// ── Atomic file write ─────────────────────────────────────────────────────────
+var LOCK_OPTS={timeoutMs:5000,pollMs:15,staleMs:30000};
+function lockPath(p){return p+'.lock'}
+function tryLock(p){
+  try{let fd=fs.openSync(p,'wx');fs.writeSync(fd,`pid:${process.pid}:${Date.now()}`);fs.closeSync(fd);return true}
+  catch(e){if(e.code==='EEXIST'||e.code==='EPERM'||e.code==='EBUSY'||e.code==='EACCES')return false;throw e}
+}
+function stalePurge(p,ms){try{if(Date.now()-fs.statSync(p).mtimeMs>ms)fs.unlinkSync(p)}catch{}}
+function busySleep(ms){let end=Date.now()+ms;while(Date.now()<end)try{Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,Math.max(1,end-Date.now()))}catch{}}
+function withLock(p,opts,fn){
+  let{timeoutMs,pollMs,staleMs}={...LOCK_OPTS,...(typeof opts==='function'?{}:opts)};
+  let cb=typeof opts==='function'?opts:fn;
+  let lp=lockPath(p);fs.mkdirSync(path.dirname(p),{recursive:true});
+  let deadline=Date.now()+timeoutMs,acquired=false;
+  while(!acquired){acquired=tryLock(lp);if(!acquired){if(Date.now()>=deadline){stalePurge(lp,staleMs);acquired=tryLock(lp);if(acquired)break;let e=new Error(`withLock: timeout ${lp}`);e.code='ELOCKTIMEOUT';throw e}stalePurge(lp,staleMs);busySleep(pollMs+Math.floor(Math.random()*pollMs))}}
+  try{return cb()}finally{try{fs.unlinkSync(lp)}catch{}}
+}
+function atomicWrite(p,data,opts={}){
+  fs.mkdirSync(path.dirname(p),{recursive:true});
+  let tmp=path.join(path.dirname(p),`.tmp-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`);
+  try{fs.writeFileSync(tmp,data,opts);fs.renameSync(tmp,p)}
+  catch(e){try{fs.existsSync(tmp)&&fs.unlinkSync(tmp)}catch{}throw e}
+}
+function readJson(p){
+  try{if(!fs.existsSync(p))return null;return JSON.parse(fs.readFileSync(p,'utf8'))}
+  catch{return null}
+}
+
+// ── Flag extraction ───────────────────────────────────────────────────────────
+// Only field presence + format checks. No governance logic.
+
+function schemaFlags(cmd){
+  let has=k=>cmd!=null&&Object.prototype.hasOwnProperty.call(cmd,k);
+  let isStr=v=>typeof v==='string';
+  let p=cmd?.payload,sig=cmd?.signature;
+  return{
+    hasId:has('id'),idValid:isStr(cmd?.id)&&/^[A-Z_]+$/.test(cmd.id)&&cmd.id.length>=1&&cmd.id.length<=50,
+    hasCommandId:has('commandId'),commandIdValid:isStr(cmd?.commandId)&&/^[a-f0-9-]+$/.test(cmd.commandId)&&cmd.commandId.length===36,
+    hasRequesterId:has('requesterId'),requesterIdValid:isStr(cmd?.requesterId)&&cmd.requesterId.length>=3&&cmd.requesterId.length<=100,
+    hasSessionId:has('sessionId'),sessionIdValid:isStr(cmd?.sessionId)&&cmd.sessionId.length>=3,
+    hasTimestamp:has('timestamp'),timestampValid:typeof cmd?.timestamp==='number'&&cmd.timestamp>=1e9,
+    hasNonce:has('nonce'),nonceValid:isStr(cmd?.nonce)&&cmd.nonce.length>=32&&cmd.nonce.length<=128,
+    hasRequires:has('requires'),requiresValid:Array.isArray(cmd?.requires)&&cmd.requires.length>=1&&cmd.requires.every(isStr),
+    hasPayload:has('payload')&&typeof p==='object'&&p!==null&&!Array.isArray(p),
+    hasPayloadAdapter:p!=null&&Object.prototype.hasOwnProperty.call(p,'adapter'),payloadAdapterValid:isStr(p?.adapter),
+    hasSignature:has('signature')&&typeof sig==='object'&&sig!==null&&!Array.isArray(sig),
+    hasSignatureAlg:sig!=null&&Object.prototype.hasOwnProperty.call(sig,'alg'),signatureAlgValid:sig?.alg==='ed25519',
+    hasSignatureKeyId:sig!=null&&Object.prototype.hasOwnProperty.call(sig,'keyId'),
+    hasSignatureSig:sig!=null&&Object.prototype.hasOwnProperty.call(sig,'sig'),signatureSigValid:isStr(sig?.sig)&&sig.sig.length>=10,
+    hasRisk:has('risk'),riskValid:['LOW','MEDIUM','HIGH','CRITICAL'].includes(cmd?.risk),
+  }
+}
+
+function policyFlags(policy,cmd){
+  let hasP=!!(policy&&policy.default==='DENY'&&policy.requesters&&typeof policy.requesters==='object');
+  let rp=policy?.requesters?.[cmd.requesterId];
+  let cmdId=(cmd?.id||'').toLowerCase();
+  let commandAllowed=!!(rp?.allowCommands?.some(c=>c.toLowerCase()===cmdId));
+  let adapterAllowed=!!(rp?.allowAdapters?.includes(cmd.payload?.adapter));
+  let filesystemRequired=!!(cmd.payload?.cwd);
+  let filesystemRootsDefined=false,filesystemOk=false,pathDenied=false;
+  if(filesystemRequired){
+    let roots=rp?.filesystem?.roots??[];
+    filesystemRootsDefined=roots.length>0;
+    if(filesystemRootsDefined){
+      let cwd=path.resolve(cmd.payload.cwd);
+      filesystemOk=roots.some(r=>{let rr=path.resolve(r);return cwd===rr||cwd.startsWith(rr+path.sep)});
+      pathDenied=(rp?.filesystem?.denyPatterns??[]).some(pat=>new RegExp('^'+pat.replace(/\./g,'\\.').replace(/\*\*/g,'.*').replace(/\*/g,'[^/]*')+'$').test(cwd));
+    }
+  }
+  let shellRequired=false,shellCommandOk=true;
+  if(cmd.id==='RUN_SHELL'){
+    shellRequired=true;
+    let allow=rp?.exec?.allowCmds??[],deny=rp?.exec?.denyCmds??[],sc=cmd.payload?.cmd;
+    if(deny.includes(sc))shellCommandOk=false;
+    else shellCommandOk=allow.length===0||allow.includes(sc);
+  }
+  return{policyConfigured:hasP,requesterConfigured:!!rp,commandAllowed,adapterAllowed,filesystemRequired,filesystemRootsDefined,filesystemOk,pathDenied,shellRequired,shellCommandOk}
+}
+
+// ── Key lifecycle ─────────────────────────────────────────────────────────────
+var KEY_ID_RE=/^[A-Za-z0-9:_-]{3,128}$/;
+function isValidKeyId(id){return typeof id==='string'&&KEY_ID_RE.test(id)&&id!=='default'}
+
+function loadKeyStore(p){
+  let rp=path.resolve(p);
+  if(!fs.existsSync(rp))return{ok:false,reason:'KEY_STORE_MISSING',message:`Key store not found: ${rp}`,store:null};
+  try{
+    let s=JSON.parse(fs.readFileSync(rp,'utf-8'));
+    if(!s||typeof s!='object'||typeof s.trustedKeys!='object')return{ok:false,reason:'KEY_STORE_INVALID',message:`Invalid key store format: ${rp}`,store:null};
+    return{ok:true,reason:null,message:'Key store loaded',store:s}
+  }catch(e){return{ok:false,reason:'KEY_STORE_INVALID_JSON',message:`Unable to parse key store: ${e.message}`,store:null}}
+}
+
+function resolveKeyFlags(keyStore,keyId,requesterId,now=new Date()){
+  let base={keyIdFormatValid:false,keyFound:false,keyNotDeprecated:false,keyRequesterMatches:false,keyNotBeforeOk:false,keyNotExpired:false,keyLifecycleFieldsPresent:false,publicKey:null};
+  if(!keyStore||!keyId)return base;
+  if(!isValidKeyId(keyId))return base;
+  base.keyIdFormatValid=true;
+  let entry=keyStore.trustedKeys?.[keyId];
+  if(!entry)return base;
+  base.keyFound=true;
+  base.keyNotDeprecated=!entry.deprecated;
+  base.keyRequesterMatches=!entry.requesterId||entry.requesterId===requesterId;
+  let nb=entry.notBefore||entry.validFrom,exp=entry.expiresAt||entry.validUntil;
+  base.keyLifecycleFieldsPresent=typeof nb==='string'&&typeof exp==='string';
+  if(base.keyLifecycleFieldsPresent){
+    let nd=new Date(nb),ed=new Date(exp);
+    if(!isNaN(nd.getTime())&&!isNaN(ed.getTime())&&nd<ed){base.keyNotBeforeOk=now>=nd;base.keyNotExpired=now<ed}
+  }
+  base.publicKey=entry.publicKey??null;
+  return base
+}
+
+// ── Policy version guard ──────────────────────────────────────────────────────
+function parseVer(v){
+  if(typeof v==='number'&&Number.isFinite(v))return{ok:true,kind:'int',parts:[Math.floor(v)],raw:String(v)};
+  if(typeof v!=='string'||!v.trim())return{ok:false,reason:'POLICY_VERSION_INVALID',message:'Policy version required'};
+  let r=v.trim();
+  if(/^\d+$/.test(r))return{ok:true,kind:'int',parts:[Number(r)],raw:r};
+  let s=r.replace(/^v/i,'');
+  if(/^\d+(\.\d+){0,2}$/.test(s)){let p=s.split('.').map(Number);while(p.length<3)p.push(0);return{ok:true,kind:'semver',parts:p,raw:r}}
+  return{ok:false,reason:'POLICY_VERSION_INVALID',message:`Unsupported policy version format '${v}'`}
+}
+function cmpVer(a,b){let n=Math.max(a.parts.length,b.parts.length);for(let i=0;i<n;i++){let x=a.parts[i]??0,y=b.parts[i]??0;if(x>y)return 1;if(x<y)return-1}return 0}
+function parseTs(v){
+  if(typeof v==='number'&&Number.isFinite(v))return{ok:true,epochSec:v>1e12?Math.floor(v/1e3):Math.floor(v)};
+  if(typeof v!=='string'||!v.trim())return{ok:false,reason:'POLICY_CREATED_AT_INVALID',message:'Policy createdAt required'};
+  let ms=Date.parse(v);return isNaN(ms)?{ok:false,reason:'POLICY_CREATED_AT_INVALID',message:`Invalid createdAt '${v}'`}:{ok:true,epochSec:Math.floor(ms/1e3)}
+}
+function readPolicyState(p){
+  if(!fs.existsSync(p))return{schemaVersion:'1',lastAccepted:null,updatedAt:null};
+  try{let s=JSON.parse(fs.readFileSync(p,'utf8'));if(!s||typeof s!=='object')throw new Error('invalid');return{schemaVersion:String(s.schemaVersion||'1'),lastAccepted:s.lastAccepted&&typeof s.lastAccepted==='object'?s.lastAccepted:null,updatedAt:s.updatedAt||null}}
+  catch(e){throw new Error(`Policy state at ${p} is corrupt: ${e.message}`)}
+}
+function validatePolicyVersionGuard({policyObj,statePath,persist=true,nowSec=Math.floor(Date.now()/1e3),maxSkewSec=31536000}){
+  let av=parseVer(policyObj?.version);if(!av.ok)return{ok:false,...av,updated:false};
+  let at2=parseTs(policyObj?.createdAt);if(!at2.ok)return{ok:false,...at2,updated:false};
+  if(Math.abs(nowSec-at2.epochSec)>maxSkewSec)return{ok:false,reason:'POLICY_CREATED_AT_SKEW_EXCEEDED',message:`Policy createdAt skew exceeds ${maxSkewSec}s`,updated:false};
+  let state;try{state=readPolicyState(statePath)}catch(e){return{ok:false,reason:'POLICY_STATE_CORRUPT',message:e.message,updated:false}}
+  let prev=state.lastAccepted,pv=null,pt2=null,cmp=0;
+  if(prev){pv=parseVer(prev.version);pt2=parseTs(prev.createdAt);
+    if(pv.ok&&pt2.ok){cmp=cmpVer(av,pv);
+      if(cmp<0)return{ok:false,reason:'POLICY_VERSION_REGRESSION',message:`Version regression: '${av.raw}' < '${pv.raw}'`,updated:false};
+      if(cmp===0&&at2.epochSec<pt2.epochSec)return{ok:false,reason:'POLICY_CREATED_AT_REGRESSION',message:'Policy createdAt must increase',updated:false};
+      if(cmp>0&&at2.epochSec<pt2.epochSec)return{ok:false,reason:'POLICY_CREATED_AT_REGRESSION',message:'Policy createdAt must increase with version',updated:false};
+    }
+  }
+  let changed=!prev||!pv?.ok||!pt2?.ok||cmp>0||(cmp===0&&at2.epochSec>pt2.epochSec);
+  if(persist&&changed)atomicWrite(statePath,JSON.stringify({schemaVersion:'1',lastAccepted:{version:policyObj.version,createdAt:policyObj.createdAt,environment:policyObj.environment||null},updatedAt:new Date().toISOString()},null,2),{encoding:'utf8'});
+  return{ok:true,reason:null,message:'Policy version guard passed',updated:changed}
+}
+
+// ── Policy signature verification ─────────────────────────────────────────────
+function verifyPolicySig({policyObj,keyStore,policySigPath='./config/policy.sig.json',allowUnsigned=false}){
+  let p=path.resolve(policySigPath);
+  if(!fs.existsSync(p))return allowUnsigned?{ok:true,skipped:true,reason:'POLICY_SIGNATURE_SKIPPED',message:`Policy sig not found: ${p} (allowed by flag)`}:{ok:false,skipped:false,reason:'POLICY_SIGNATURE_MISSING',message:`Policy sig not found: ${p}`};
+  let env;try{env=JSON.parse(fs.readFileSync(p,'utf-8'))}catch(e){return{ok:false,skipped:false,reason:'POLICY_SIGNATURE_INVALID',message:`Cannot parse policy sig: ${e.message}`}};
+  if(!env||env.alg!=='ed25519'||typeof env.keyId!=='string'||typeof env.sig!=='string')return{ok:false,skipped:false,reason:'POLICY_SIGNATURE_INVALID',message:'Policy sig must include {alg,keyId,sig}'};
+  if(!keyStore)return{ok:false,skipped:false,reason:'POLICY_SIGNER_KEY_STORE_UNAVAILABLE',message:'Key store required for policy sig verification'};
+  let kf=resolveKeyFlags(keyStore,env.keyId,undefined,new Date());
+  if(!kf.keyFound||!kf.keyNotExpired)return{ok:false,skipped:false,reason:'POLICY_SIGNER_NOT_TRUSTED',message:`Key '${env.keyId}' not trusted or expired`};
+  let v=verifyEd25519({payloadObj:policyObj,sigB64:env.sig,pubKeyB64:kf.publicKey});
+  return v.valid?{ok:true,skipped:false,reason:null,message:'Policy signature verified',keyId:env.keyId}:{ok:false,skipped:false,reason:'POLICY_SIGNATURE_INVALID',message:v.message}
+}
+
+// ── Invariant gate ────────────────────────────────────────────────────────────
+class InvariantGateError extends Error{constructor(msg,checks,failures){super(msg);this.name='InvariantGateError';this.checks=checks;this.failures=failures}}
+function dirWritable(d){try{fs.accessSync(d,fs.constants.W_OK);return true}catch{try{fs.mkdirSync(d,{recursive:true});return true}catch{return false}}}
+function runInvariantGate(paths,policy,keyStore){
+  let c={},f=[];
+  c.policy_structure=!!(policy&&policy.default==='DENY'&&policy.requesters&&typeof policy.requesters==='object'&&typeof policy.version!=='undefined');
+  if(!c.policy_structure)f.push('Policy missing required fields: version, requesters, default=DENY');
+  c.keys_available=!!(keyStore&&typeof keyStore==='object'&&Object.keys(keyStore).length>0);
+  if(!c.keys_available)f.push('No trusted keys loaded — provide config/keys.json');
+  for(let[k,p2]of[['audit_log_writable',paths.auditLog],['nonce_db_writable',paths.nonceDb],['rate_limit_writable',paths.rateLimit]]){c[k]=dirWritable(path.dirname(p2));if(!c[k])f.push(`${k} directory not writable: ${path.dirname(p2)}`)}
+  c.secret_key_present=!!paths.secretKey;if(!c.secret_key_present)f.push('secretKey not provided to createLBE()');
+  return{ok:f.length===0,checks:c,failures:f}
+}
+function assertInvariantGate(paths,policy,keyStore){
+  let r=runInvariantGate(paths,policy,keyStore);
+  if(!r.ok){let n=r.failures.length;throw new InvariantGateError(`Invariant gate: ${n} violation${n===1?'':'s'} — ${r.failures.join(' | ')}`,r.checks,r.failures)}
+  return r
+}
+
+// ── Logger ────────────────────────────────────────────────────────────────────
+var LEVELS={DEBUG:0,INFO:1,WARN:2,ERROR:3};
+function createLogger({level='INFO',maxHistory=500,silent=false}={}){
+  let threshold=LEVELS[level]??LEVELS.INFO,history=[];
+  function emit(lvl,scope,msg,meta){
+    let e={ts:new Date().toISOString(),level:lvl,scope,message:msg,...(meta!==undefined?{meta}:{})};
+    if(history.length>=maxHistory)history.shift();history.push(e);
+    if(!silent&&LEVELS[lvl]>=threshold)process.stderr.write((meta!==undefined?`[${lvl}] [${scope}] ${msg} ${JSON.stringify(meta)}`:`[${lvl}] [${scope}] ${msg}`)+'\n')
+  }
+  function scope(s){return{debug:(m,d)=>emit('DEBUG',s,m,d),info:(m,d)=>emit('INFO',s,m,d),warn:(m,d)=>emit('WARN',s,m,d),error:(m,d)=>emit('ERROR',s,m,d)}}
+  return{scope,debug:(m,d)=>emit('DEBUG','lbe',m,d),info:(m,d)=>emit('INFO','lbe',m,d),warn:(m,d)=>emit('WARN','lbe',m,d),error:(m,d)=>emit('ERROR','lbe',m,d),exportLogs:()=>[...history],clearHistory:()=>{history.length=0},get historyLength(){return history.length}}
+}
+
+// ── Nonce / rate-limit IO helpers ─────────────────────────────────────────────
+// WASM owns the logic. These helpers serialize/deserialize the text-format DB.
+function loadNonceEntries(dbPath){
+  try{if(!fs.existsSync(dbPath))return[];let db=JSON.parse(fs.readFileSync(dbPath,'utf8'));return(db?.entries??[]).map(e=>`${e.key}:${e.timestamp}`)}
+  catch{return[]}
+}
+function saveNonceEntries(dbPath,text){
+  let entries=text.split('\n').filter(Boolean).map(line=>{let i=line.lastIndexOf(':');return{key:line.slice(0,i),timestamp:parseInt(line.slice(i+1),10)||0}});
+  atomicWrite(dbPath,JSON.stringify({entries},null,2),{encoding:'utf8'})
+}
+function loadRateEntries(dbPath){
+  try{if(!fs.existsSync(dbPath))return[];let db=JSON.parse(fs.readFileSync(dbPath,'utf8'));return(db?.entries??[]).map(e=>`${e.requesterId}:${e.timestamp}`)}
+  catch{return[]}
+}
+function saveRateEntries(dbPath,text){
+  let entries=text.split('\n').filter(Boolean).map(line=>{let i=line.lastIndexOf(':');return{requesterId:line.slice(0,i),timestamp:parseInt(line.slice(i+1),10)||0}});
+  atomicWrite(dbPath,JSON.stringify({entries},null,2),{encoding:'utf8'})
+}
+
+// ── Validation — thin orchestrator; all decisions delegate to WASM ────────────
+function validate({commandObj,pubKeyB64,keyStore,nonceDbPath,rateLimitDbPath,policy,policyStatePath}){
+  let result={valid:false,commandId:commandObj?.commandId,checks:{},errors:[]};
+  let nowSec=Math.floor(Date.now()/1e3);
+  let maxClockSkewSec=Number.isFinite(policy?.security?.maxClockSkewSec)?policy.security.maxClockSkewSec:600;
+
+  // Policy version guard (meta-check on the policy itself, not the command)
+  if(policyStatePath&&policy?.version!==undefined){
+    try{
+      let vg=validatePolicyVersionGuard({policyObj:policy,statePath:policyStatePath});
+      result.checks.policyVersion=vg.ok;
+      if(!vg.ok){result.errors.push({type:'POLICY_VERSION_INVALID',message:vg.message});return result}
+    }catch{result.checks.policyVersion=true}
+  }else{result.checks.policyVersion=true}
+
+  // Extract structured flag sets for WASM
+  let sf=schemaFlags(commandObj);
+  let keyId=commandObj?.signature?.keyId;
+  let kf=resolveKeyFlags(keyStore,keyId,commandObj?.requesterId,new Date());
+
+  // Ed25519 signature verification (stays in JS — well-known algorithm via tweetnacl)
+  let signatureValid=false,effectivePubKey=kf.publicKey||pubKeyB64;
+  if(effectivePubKey){
+    let body={...commandObj};delete body.signature;
+    signatureValid=verifyEd25519({payloadObj:body,sigB64:commandObj?.signature?.sig,pubKeyB64:effectivePubKey}).valid;
+  }
+
+  // Rate limit — WASM sliding-window logic, state stored in JS file
+  let rateLimitOk=true,rateLimitRetryAfterSec=0;
+  if(signatureValid&&rateLimitDbPath){
+    let rateCfg=policy?.requesters?.[commandObj.requesterId]?.rateLimit||{};
+    let dflt=policy?.security?.defaultRateLimit||{};
+    let rr=checkRateLimit({windowSec:rateCfg.windowSec??dflt.windowSec??60,maxRequests:rateCfg.maxRequests??dflt.maxRequests??30,nowSec,requesterId:commandObj.requesterId,existingEntries:loadRateEntries(rateLimitDbPath)});
+    rateLimitOk=rr.ok;rateLimitRetryAfterSec=rr.retryAfterSec;
+    saveRateEntries(rateLimitDbPath,rr.updatedEntriesText??'');
+  }
+
+  // Nonce check — WASM dedup logic, state stored in JS file
+  let nonceOk=true;
+  let nonceKey=`${commandObj?.requesterId}|${commandObj?.sessionId}|${commandObj?.nonce}`;
+  if(signatureValid&&rateLimitOk&&nonceDbPath){
+    let nr2=checkNonce({ttlSec:3600,nowSec,newKey:nonceKey,existingEntries:loadNonceEntries(nonceDbPath)});
+    nonceOk=nr2.ok;
+    if(nr2.ok)saveNonceEntries(nonceDbPath,nr2.updatedEntriesText??'');
+  }
+
+  // Policy flags
+  let pf=policyFlags(policy,commandObj??{});
+
+  // WASM pipeline — single call owns all governance decisions
+  let pipe=runValidationPipeline({...sf,cmdTimestamp:commandObj?.timestamp??0,nowSec,maxClockSkewSec,...kf,signatureValid,rateLimitOk,rateLimitRetryAfterSec,nonceOk,...pf});
+
+  // Map pipeline result to the checks surface
+  result.checks.schema=pipe.ok||pipe.stage>0;
+  result.checks.timestamp=pipe.ok||pipe.stage>1;
+  result.checks.keyId=pipe.ok||pipe.stage>2;
+  result.checks.signature=pipe.ok||pipe.stage>3;
+  result.checks.rateLimit=pipe.ok||pipe.stage>4;
+  result.checks.nonce=pipe.ok||pipe.stage>5;
+  result.checks.policy=pipe.ok;
+
+  if(!pipe.ok){
+    let s=pipe.stageLabel;
+    if(s==='schema'){result.checks.schema=false;result.errors.push({type:'SCHEMA_ERROR',message:pipe.schemaError||'Schema invalid'})}
+    else if(s==='timestamp'){result.checks.timestamp=false;result.errors.push({type:'TIMESTAMP_SKEW_EXCEEDED',message:`Command timestamp skew ${pipe.skewSec}s exceeds allowed ${maxClockSkewSec}s`})}
+    else if(s==='key'){result.checks.keyId=false;result.checks.signature=false;let kr=pipe.keyReason||'KEY_ERROR';result.errors.push({type:kr,message:kr})}
+    else if(s==='signature'){result.checks.signature=false;result.errors.push({type:'SIGNATURE_INVALID',message:effectivePubKey?'Signature verification failed':'No public key available'})}
+    else if(s==='rate_limit'){result.checks.rateLimit=false;result.errors.push({type:'RATE_LIMIT_EXCEEDED',message:`Rate limit exceeded. Retry after ${pipe.retryAfterSec}s`})}
+    else if(s==='nonce'){result.checks.nonce=false;result.errors.push({type:'REPLAY_NONCE',message:'Nonce has already been used'})}
+    else if(s==='policy'&&pipe.policyResult){result.checks.policy=false;result.errors.push({type:pipe.policyResult.reason,message:pipe.policyResult.message})}
+    else result.errors.push({type:'VALIDATION_FAILED',message:`Failed at stage: ${s}`});
+    return result
+  }
+
+  result.valid=true;
+  result.risk=classifyRisk(commandObj.id,commandObj.payload?.cmd==='rm');
+  result.message='Command validation successful';
+  return result
+}
+
+// ── Audit log ─────────────────────────────────────────────────────────────────
+// Hash-chain computation delegates to WASM (SHA-256). File IO stays in JS.
+function getLastHash(auditPath){
+  try{
+    if(!fs.existsSync(auditPath))return'GENESIS';
+    let lines=fs.readFileSync(auditPath,'utf8').trim().split('\n').filter(Boolean);
+    if(!lines.length)return'GENESIS';
+    return JSON.parse(lines[lines.length-1]).hash||'GENESIS'
+  }catch{return'GENESIS'}
+}
+function appendAuditEntry(auditPath,entry){
+  let dir=path.dirname(auditPath);fs.mkdirSync(dir,{recursive:true});
+  return withLock(auditPath,()=>{
+    let prevHash=getLastHash(auditPath);
+    let body={...entry,prevHash,timestamp:new Date().toISOString()};delete body.hash;
+    let entryJson=JSON.stringify(body);
+    let hash=computeAuditHash(prevHash,entryJson);
+    let line=JSON.stringify({...body,hash})+'\n';
+    let existing=fs.existsSync(auditPath)?fs.readFileSync(auditPath,'utf8'):'';
+    atomicWrite(auditPath,existing+line,{encoding:'utf8'});
+    return{success:true,hash,prevHash,message:'Audit entry appended'}
+  })
+}
+
+// ── Adapters (readable — execution only, no governance) ───────────────────────
+async function noopAdapter(cmd){
+  return{adapter:'noop',commandId:cmd.commandId,command:cmd.id,status:'completed',output:`[NOOP] Would execute: ${cmd.id} on adapter: ${cmd.payload?.adapter}`,exitCode:0,timestamp:new Date().toISOString()}
+}
+
+import{spawnSync}from'child_process';
+function parseArgs(args){
+  if(args===undefined)return{ok:true,args:[]};
+  if(!Array.isArray(args))return{ok:false,error:'payload.args must be an array'};
+  let out=[];for(let a of args){if(typeof a!=='string'&&typeof a!=='number'&&typeof a!=='boolean')return{ok:false,error:'payload.args may only contain string, number, or boolean'};out.push(String(a))}
+  return{ok:true,args:out}
+}
+async function shellAdapter(cmd,_policy,rp){
+  let t=cmd.payload,allowed=rp?.exec?.allowCmds??[],denied=rp?.exec?.denyCmds??[];
+  if(t.adapter!=='shell')return{adapter:'shell',commandId:cmd.commandId,status:'error',error:'Adapter mismatch',exitCode:1};
+  if(denied.includes(t.cmd))return{adapter:'shell',commandId:cmd.commandId,status:'blocked',error:`Command '${t.cmd}' is denied`,exitCode:2};
+  if(allowed.length>0&&!allowed.includes(t.cmd))return{adapter:'shell',commandId:cmd.commandId,status:'blocked',error:`Command '${t.cmd}' not in allowlist`,exitCode:2};
+  let roots=rp?.filesystem?.roots??[];
+  if(!roots.some(r=>{let rp2=path.resolve(r),cwd2=path.resolve(t.cwd);return cwd2===rp2||cwd2.startsWith(rp2+path.sep)}))
+    return{adapter:'shell',commandId:cmd.commandId,status:'blocked',error:`CWD '${t.cwd}' not authorized`,exitCode:2};
+  let pa=parseArgs(t.args);if(!pa.ok)return{adapter:'shell',commandId:cmd.commandId,status:'blocked',error:pa.error,exitCode:2};
+  try{
+    let r=spawnSync(t.cmd,pa.args,{cwd:t.cwd,timeout:30000,encoding:'utf8',maxBuffer:1024*1024,stdio:['pipe','pipe','pipe'],shell:false});
+    if(r.error)throw r.error;
+    let out=`${r.stdout||''}${r.stderr||''}`,code=r.status??1;
+    if(code!==0)return{adapter:'shell',commandId:cmd.commandId,command:t.cmd,status:'error',error:out||`Exit ${code}`,exitCode:code,timestamp:new Date().toISOString()};
+    return{adapter:'shell',commandId:cmd.commandId,command:t.cmd,status:'completed',output:out,exitCode:0,timestamp:new Date().toISOString()}
+  }catch(e){return{adapter:'shell',commandId:cmd.commandId,command:t.cmd,status:'error',error:e.message,exitCode:1,timestamp:new Date().toISOString()}}
+}
+
+var MAX_READ_BYTES=10*1024*1024;
+function absTarget(t,cwd){return t?path.isAbsolute(t)?path.resolve(t):path.resolve(cwd||process.cwd(),t):null}
+function inRoots(p2,roots){return roots.some(r=>{let rr=path.resolve(r);return p2===rr||p2.startsWith(rr+path.sep)})}
+function matchDeny(p2,patterns){for(let pat of patterns||[])if(new RegExp('^'+pat.replace(/\./g,'\\.').replace(/\*\*/g,'.*').replace(/\*/g,'[^/\\\\]*')+'$').test(p2))return pat;return null}
+function fileBlocked(cmd,code,msg){return{adapter:'file',commandId:cmd.commandId,status:'blocked',errorCode:code,error:msg,exitCode:2}}
+function fileError(cmd,code,msg,bk=null){return{adapter:'file',commandId:cmd.commandId,status:'error',errorCode:code,error:msg,backup:bk?{path:bk.backupPath,existed:bk.existed,hash:bk.hash,createdAt:bk.createdAt}:null,exitCode:1}}
+function makeBackup(target,backupDir){
+  fs.mkdirSync(backupDir,{recursive:true});
+  let tp=path.resolve(target),existed=fs.existsSync(tp),data=existed?fs.readFileSync(tp):null;
+  let hash=data?crypto.createHash('sha256').update(data).digest('hex'):null;
+  let bname=path.basename(tp).replace(/[^a-zA-Z0-9._-]/g,'_');
+  let bpath=existed?path.join(backupDir,`${Date.now()}-${hash.slice(0,8)}-${bname}`):null;
+  if(existed&&data!==null)atomicWrite(bpath,data);
+  return{originalPath:tp,backupPath:bpath,existed,hash,createdAt:new Date().toISOString()}
+}
+function restoreBackup(bk){
+  if(!bk)return{restored:false,error:'No backup metadata'};
+  if(!bk.existed)try{fs.existsSync(bk.originalPath)&&fs.unlinkSync(bk.originalPath);return{restored:true,action:'deleted'}}catch(e){return{restored:false,error:e.message}}
+  if(!bk.backupPath||!fs.existsSync(bk.backupPath))return{restored:false,error:'Backup file missing: '+bk.backupPath};
+  try{atomicWrite(bk.originalPath,fs.readFileSync(bk.backupPath));return{restored:true,action:'restored'}}catch(e){return{restored:false,error:e.message}}
+}
+async function fileAdapter(cmd,_policy,rp){
+  let t=cmd.payload,action=t.action,cwd=t.cwd||process.cwd(),target=absTarget(t.target,cwd);
+  if(!action)return fileBlocked(cmd,'FILE_NO_ACTION','payload.action required');
+  if(!target&&action!=='noop')return fileBlocked(cmd,'FILE_NO_TARGET','payload.target required');
+  let roots=rp?.filesystem?.roots??[];if(roots.length===0)return fileBlocked(cmd,'FILE_NO_ROOTS','No filesystem roots defined');
+  if(!inRoots(target,roots))return fileBlocked(cmd,'FILE_OUTSIDE_ROOT',`'${target}' outside allowed roots`);
+  let denied=matchDeny(target,rp?.filesystem?.denyPatterns);if(denied)return fileBlocked(cmd,'FILE_PATH_DENIED',`'${target}' matches deny pattern: ${denied}`);
+  if(action==='read'){
+    if(!fs.existsSync(target))return fileError(cmd,'FILE_NOT_FOUND',`Not found: ${target}`);
+    try{let stat=fs.statSync(target);if(stat.size>MAX_READ_BYTES)return fileError(cmd,'FILE_TOO_LARGE','File exceeds 10 MB');let out=fs.readFileSync(target,'utf8');return{adapter:'file',action,commandId:cmd.commandId,status:'completed',target,output:out,bytesRead:stat.size,exitCode:0}}
+    catch(e){return fileError(cmd,'FILE_READ_ERROR',e.message)}
+  }
+  let bk=null;try{bk=makeBackup(target,rp?.backupDir||path.join(os.homedir(),'.lbe','backups'))}catch{}
+  if(action==='write'||action==='patch'){
+    if(t.content==null)return fileError(cmd,`FILE_MISSING_CONTENT`,'payload.content required');
+    try{atomicWrite(target,t.content,{encoding:'utf8'});return{adapter:'file',action,commandId:cmd.commandId,status:'completed',target,backup:bk?{path:bk.backupPath,existed:bk.existed,hash:bk.hash}:null,output:`Wrote ${Buffer.byteLength(t.content,'utf8')} bytes to ${target}`,exitCode:0}}
+    catch(e){restoreBackup(bk);return fileError(cmd,`FILE_${action.toUpperCase()}_ERROR`,e.message,bk)}
+  }
+  if(action==='delete'){
+    if(!fs.existsSync(target))return fileError(cmd,'FILE_NOT_FOUND',`Not found: ${target}`);
+    try{fs.unlinkSync(target);return{adapter:'file',action,commandId:cmd.commandId,status:'completed',target,backup:bk?{path:bk.backupPath,existed:bk.existed,hash:bk.hash}:null,output:`Deleted ${target}`,exitCode:0}}
+    catch(e){return fileError(cmd,'FILE_DELETE_ERROR',e.message,bk)}
+  }
+  return fileBlocked(cmd,'FILE_UNKNOWN_ACTION',`Unknown action: '${action}'`)
+}
+
+async function observerAdapter(cmd){
+  if(!(cmd.id||'').toUpperCase().startsWith('OBSERVE'))return{adapter:'observer',commandId:cmd.commandId,status:'error',error:`Observer adapter only handles OBSERVE_* commands`,exitCode:1};
+  let{source,context,issueType,description,severity,metadata}=cmd.payload||{};
+  if(!issueType||!description)return{adapter:'observer',commandId:cmd.commandId,status:'error',error:'Observer payload must include issueType and description',exitCode:1};
+  let levels=['low','medium','high','critical'];
+  if(severity&&!levels.includes(severity))return{adapter:'observer',commandId:cmd.commandId,status:'error',error:`Invalid severity '${severity}'`,exitCode:1};
+  return{adapter:'observer',commandId:cmd.commandId,status:'recorded',timestamp:new Date().toISOString(),requesterId:cmd.requesterId,observation:{source:source||'unknown',context:context||'unknown',issueType,description,severity:severity||'info',metadata:metadata||{}},exitCode:0}
+}
+
+var ADAPTERS={noop:noopAdapter,shell:shellAdapter,file:fileAdapter,observer:observerAdapter};
+var ADAPTER_NAMES=Object.keys(ADAPTERS);
+async function runAdapter(name,cmd,policy,rp){
+  let fn=ADAPTERS[name];
+  if(!fn)return{adapter:name,commandId:cmd.commandId,status:'error',error:`Adapter '${name}' not found`,exitCode:1};
+  try{return await fn(cmd,policy,rp)}catch(e){return{adapter:name,commandId:cmd.commandId,status:'error',error:`Adapter execution failed: ${e.message}`,exitCode:9}}
+}
+
+// ── Approval token store ──────────────────────────────────────────────────────
+var _checkpointStore=null;
+class CheckpointStore{
+  constructor(p){this.dbPath=p||path.resolve('data/checkpoints.db.json');this.store={checkpoints:{},tokens:{}};this._load()}
+  _load(){let r=readJson(this.dbPath);if(r){this.store=r;this.store.checkpoints=this.store.checkpoints||{};this.store.tokens=this.store.tokens||{}}}
+  _save(){atomicWrite(this.dbPath,JSON.stringify(this.store,null,2),{encoding:'utf8'})}
+  saveToken(id,data){this.store.tokens[id]={tokenId:id,...data,createdAt:Date.now()};this._save()}
+  getToken(id){return this.store.tokens[id]||null}
+  removeToken(id){if(this.store.tokens[id]){delete this.store.tokens[id];this._save();return true}return false}
+}
+function getCheckpointStore(p){return _checkpointStore||(_checkpointStore=new CheckpointStore(p))}
+
+var _approvalGate=null;
+class ApprovalGate{
+  constructor(p){this.store=getCheckpointStore(p);this._pending=new Map()}
+  createToken(jobId,ctx={}){
+    let id=crypto.randomBytes(16).toString('hex');
+    this.store.saveToken(id,{jobId,context:ctx,status:'pending',expiresAt:Date.now()+86400000});
+    return id
+  }
+  awaitApproval(id){
+    let t=this.store.getToken(id);
+    if(!t)return Promise.reject(new Error(`Approval token ${id} not found`));
+    if(t.status!=='pending')return Promise.reject(new Error(`Token ${id} not pending (${t.status})`));
+    if(Date.now()>t.expiresAt){this.store.removeToken(id);return Promise.reject(new Error(`Token ${id} expired`))}
+    return new Promise((res,rej)=>{this._pending.set(id,{resolve:res,reject:rej})})
+  }
+  approve(id,data={}){
+    let t=this.store.getToken(id);if(!t)throw new Error('Token not found');if(t.status!=='pending')throw new Error('Token not pending');
+    this.store.saveToken(id,{...t,status:'approved',approverData:data,resolvedAt:Date.now()});
+    let p=this._pending.get(id);if(p){p.resolve({approved:true,approverData:data});this._pending.delete(id)}return true
+  }
+  deny(id,reason='Manually denied'){
+    let t=this.store.getToken(id);if(!t)throw new Error('Token not found');if(t.status!=='pending')throw new Error('Token not pending');
+    this.store.saveToken(id,{...t,status:'denied',reason,resolvedAt:Date.now()});
+    let p=this._pending.get(id);if(p){p.reject(new Error(`Approval denied: ${reason}`));this._pending.delete(id)}return true
+  }
+}
+function getApprovalGate(p){return _approvalGate||(_approvalGate=new ApprovalGate(p))}
+
+// ── State directory resolver ──────────────────────────────────────────────────
+function resolveStateDir(rootDir,state){
+  let rp=path.resolve(rootDir||process.cwd());
+  if(!state||state==='local'){let h=crypto.createHash('sha256').update(rp).digest('hex').slice(0,16);return path.join(os.homedir(),'.lbe','workspaces',h)}
+  if(state==='workspace')return path.join(rp,'.lbe');
+  if(state&&typeof state==='object'&&state.adapter)return null;
+  throw new Error(`createLBE: unknown state option: ${JSON.stringify(state)}`)
+}
+
+// ── Risk helpers ──────────────────────────────────────────────────────────────
+var INTENT_TO_CMD={patch_file:'PATCH_FILE',write_file:'WRITE_FILE',read_file:'READ_FILE',delete_file:'DELETE_FILE',run_shell:'RUN_SHELL',echo:'ECHO'};
+var INTENT_TO_ADAPTER={PATCH_FILE:'file',WRITE_FILE:'file',READ_FILE:'file',DELETE_FILE:'file',RUN_SHELL:'shell',ECHO:'noop'};
+var HIGH_RISK=new Set(['HIGH','CRITICAL']);
+function needsApproval(risk,rp){
+  if(!rp?.requireApproval)return false;
+  let r=rp.requireApproval;
+  if(r===true)return true;
+  if(Array.isArray(r))return r.includes(risk)||r.includes('*')||(HIGH_RISK.has(risk)&&r.includes('HIGH+'));
+  return false
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function deepFreeze(obj){
+  if(obj===null||typeof obj!=='object'||Object.isFrozen(obj))return obj;
+  Object.freeze(obj);
+  for(let k of Object.getOwnPropertyNames(obj)){let v=obj[k];if(typeof v==='object'&&v!==null&&!Object.isFrozen(v))deepFreeze(v)}
+  return obj
+}
+function payloadHash(obj){return crypto.createHash('sha256').update(JSON.stringify(obj)).digest('hex')}
+
+// ── createLBE ─────────────────────────────────────────────────────────────────
+export function createLBE(options={}){
+  // Auto-provision keypair when rootDir is provided without secretKey
+  if(options.rootDir&&!options.secretKey){
+    let kp=generateKeyPair(),kid=options.keyId||'sdk-auto-key';
+    options={defaultActor:'agent:sdk',logLevel:'WARN',...options,secretKey:kp.secretKey,keyId:kid,
+      keyStore:options.keyStore||makeKeyStore({publicKey:kp.publicKey,keyId:kid}),
+      policy:options.policy||{version:1,default:'DENY',requesters:{'agent:sdk':{allowCommands:['write_file','read_file','patch_file','delete_file'],allowAdapters:['file'],filesystem:{roots:[options.rootDir],denyPatterns:['*.key','*.env','*.secret']}}}}
+    }
+  }
+  let{secretKey,keyId='sdk-key-v1',sessionId,defaultActor='agent:sdk',policy:inlinePolicy,keyStore:inlineKeyStore,
+    policyPath,keysStorePath,policySigPath,policyStatePath,nonceDbPath,rateLimitDbPath,auditLogPath,backupDir,
+    allowUnsignedPolicy=false,state='local',rootDir,
+    logLevel=process.env.LBE_LOG_LEVEL||'INFO',logSilent=process.env.LBE_LOG_SILENT==='1'}=options;
+
+  let sd=resolveStateDir(rootDir,state);
+  let paths={
+    secretKey,
+    policy:policyPath||path.resolve('config/policy.default.json'),
+    keys:keysStorePath||path.resolve('config/keys.json'),
+    policySig:policySigPath||path.resolve('config/policy.sig.json'),
+    policyState:policyStatePath||path.join(sd,'policy.state.json'),
+    nonceDb:nonceDbPath||path.join(sd,'nonce.db.json'),
+    rateLimit:rateLimitDbPath||path.join(sd,'rate-limit.db.json'),
+    auditLog:auditLogPath||path.join(sd,'audit.log.jsonl'),
+    backupDir:backupDir||path.join(sd,'backups'),
+  };
+
+  let log=createLogger({level:logLevel,silent:logSilent});
+  let exec_log=log.scope('Executor'),val_log=log.scope('Validator'),pol_log=log.scope('Policy');
+
+  async function execute({actor,intent,target,content,args=[],transaction={}}){
+    let tx={validate:true,backup:true,rollbackOnFailure:true,audit:true,...transaction};
+    exec_log.info('execute() called',{actor,intent,target});
+
+    // Load policy
+    let policy;
+    if(inlinePolicy){policy=inlinePolicy;pol_log.debug('Using inline policy',{version:policy.version})}
+    else{try{policy=JSON.parse(fs.readFileSync(paths.policy,'utf8'));pol_log.debug('Policy loaded',{version:policy.version})}
+         catch(e){pol_log.error('Policy load failed',{error:e.message});return{ok:false,stage:'policy_load',error:'POLICY_LOAD_FAILED',message:e.message}}}
+
+    // Load key store
+    let keyStore;
+    if(inlineKeyStore){keyStore=inlineKeyStore;val_log.debug('Using inline keyStore')}
+    else{let kr=loadKeyStore(paths.keys);keyStore=kr.ok?kr.store:null;val_log.debug('Keys loaded',{ok:kr.ok})}
+
+    deepFreeze(policy);if(keyStore)deepFreeze(keyStore);
+
+    // Invariant gate
+    try{let ig=assertInvariantGate(paths,policy,keyStore);val_log.debug('Invariant gate passed',ig.checks)}
+    catch(e){if(e instanceof InvariantGateError)return{ok:false,stage:'invariant_gate',error:'INVARIANT_GATE_FAILED',message:e.message,checks:e.checks,failures:e.failures};throw e}
+
+    // Policy signature check (only for file-loaded policy)
+    if(!inlinePolicy){
+      let ps=verifyPolicySig({policyObj:policy,keyStore,policySigPath:paths.policySig,allowUnsigned:allowUnsignedPolicy});
+      if(!ps.ok){pol_log.error('Policy sig invalid',{reason:ps.reason});return{ok:false,stage:'policy_sig',error:ps.reason,message:ps.message}}
+      let vg=validatePolicyVersionGuard({policyObj:policy,statePath:paths.policyState});
+      if(!vg.ok){pol_log.error('Policy version guard failed',{reason:vg.reason});return{ok:false,stage:'policy_version',error:vg.reason,message:vg.message}}
+      pol_log.debug('Policy sig and version valid')
+    }
+
+    if(!secretKey)return{ok:false,stage:'sign',error:'NO_SECRET_KEY',message:'createLBE requires secretKey'};
+
+    // Build and sign command
+    let nowSec=Math.floor(Date.now()/1e3),nonce=crypto.randomBytes(32).toString('hex');
+    let sid=sessionId||`sdk-${Date.now()}`,commandId=crypto.randomUUID();
+    let cmdName=INTENT_TO_CMD[intent]||intent.toUpperCase().replace(/-/g,'_');
+    let adapter=INTENT_TO_ADAPTER[cmdName]||'noop';
+    exec_log.debug('Command built',{commandId,cmd:cmdName,adapter});
+
+    let body={id:cmdName,commandId,requesterId:actor,sessionId:sid,timestamp:nowSec,nonce,requires:['policy','signature'],
+      payload:{adapter,action:intent.includes('_')?intent.split('_')[0]:intent,target:target?path.resolve(target):null,content:content||null,args,cwd:target?path.dirname(path.resolve(target)):process.cwd()}};
+    let signed=signPayload({payloadObj:body,secretKeyB64:secretKey});
+    if(signed.error){exec_log.error('Signing failed',{error:signed.error});return{ok:false,stage:'sign',commandId,error:'SIGN_FAILED',message:signed.error}}
+    let cmd={...body,signature:{alg:'ed25519',keyId,sig:signed.signature}};
+
+    // Validate — thin JS orchestrator + WASM decisions
+    let val=validate({commandObj:cmd,keyStore,nonceDbPath:paths.nonceDb,rateLimitDbPath:paths.rateLimit,policy,policyStatePath:inlinePolicy?null:paths.policyState});
+    if(!val.valid){
+      val_log.warn('Validation failed',{error:val.errors[0]?.type,checks:val.checks});
+      if(tx.audit)appendAuditEntry(paths.auditLog,{commandId,status:'rejected',requesterId:actor,payloadHash:payloadHash(cmd),reason:val.errors[0]?.type,intent});
+      return{ok:false,stage:'validate',commandId,error:val.errors[0]?.type,message:val.errors[0]?.message,checks:val.checks,operationLog:log.exportLogs()}
+    }
+    val_log.info('Validation passed',{risk:val.risk,checks:val.checks});
+
+    // Approval gate
+    let risk=val.risk||'LOW';
+    let rp=policy.requesters?.[actor];
+    if(needsApproval(risk,rp)){
+      exec_log.warn('Approval required',{risk,commandId});
+      let token=getApprovalGate(paths.policyState).createToken(commandId,{actor,intent,target,risk,commandId:cmdName});
+      return{ok:false,stage:'approval_pending',commandId,approvalToken:token,risk,message:`${risk} risk operation requires approval. Token: ${token}`,operationLog:log.exportLogs()}
+    }
+
+    // Backup
+    let bk=null;
+    if(tx.backup&&target){
+      let isWrite=['write','patch','delete'].includes(body.payload.action);
+      try{bk=makeBackup(path.resolve(target),paths.backupDir);exec_log.debug('Backup created',{existed:bk.existed})}
+      catch(e){if(isWrite){exec_log.error('Backup failed — aborting',{error:e.message});return{ok:false,stage:'backup',error:'BACKUP_FAILED',message:e.message}};exec_log.warn('Backup failed (non-fatal)',{error:e.message})}
+    }
+
+    // Execute
+    exec_log.info('Executing adapter',{adapter,target});
+    let adResult;
+    try{adResult=await runAdapter(adapter,cmd,policy,rp)}
+    catch(e){adResult={adapter,commandId,status:'error',error:e.message,exitCode:1}}
+    exec_log.debug('Adapter returned',{status:adResult.status,exitCode:adResult.exitCode});
+
+    // Post-execution validation
+    let failed=adResult.status==='error'||(adResult.exitCode!==0&&adResult.exitCode!==undefined);
+    let postCheck=null;
+    if(tx.validate&&target&&!failed){
+      let writeActions=['write','patch'];
+      if(writeActions.includes(body.payload.action)){
+        let exists=fs.existsSync(path.resolve(target));
+        postCheck={ok:exists,check:'target_exists',target};
+        if(!exists){exec_log.error('Post-exec validation failed',{target});adResult.status='error'}
+      }
+    }
+
+    // Rollback — WASM decides whether to rollback
+    let rollbackResult=null;
+    if((failed||(postCheck&&!postCheck.ok))&&tx.rollbackOnFailure&&bk){
+      let doRollback=shouldRollback({execFailed:failed,postCheckFailed:postCheck&&!postCheck.ok,backupExists:!!bk.backupPath,rollbackEnabled:true});
+      if(doRollback)try{rollbackResult=restoreBackup(bk);exec_log.warn('Rollback executed',rollbackResult)}catch(e){rollbackResult={restored:false,error:e.message};exec_log.error('Rollback failed',{error:e.message})}
+    }
+
+    if(tx.audit)appendAuditEntry(paths.auditLog,{commandId,status:rollbackResult?.restored?'rolled_back':adResult.status||'completed',requesterId:actor,payloadHash:payloadHash(cmd),executionHash:payloadHash(adResult),adapter,intent,riskLevel:risk,exitCode:adResult.exitCode||0,rolledBack:rollbackResult?.restored||false});
+
+    let ok=!failed&&(!postCheck||postCheck.ok);
+    exec_log.info('execute() complete',{ok,risk});
+    return{ok,commandId,intent,actor,target,risk,stage:ok?'executed':'failed',status:adResult.status,output:adResult.output||null,exitCode:adResult.exitCode??0,checks:val.checks,backup:bk?{path:bk.backupPath,existed:bk.existed,hash:bk.hash}:null,rollback:rollbackResult,postValidation:postCheck,operationLog:logLevel==='DEBUG'?log.exportLogs():undefined}
+  }
+
+  return{
+    execute,
+    exportLogs:()=>log.exportLogs(),
+    async writeFile(target,content){
+      let r=await execute({actor:defaultActor,intent:'write_file',target,content,transaction:{backup:true,rollbackOnFailure:true,audit:true}});
+      if(!r.ok){let e=new Error(`LBE write failed [${r.error||r.stage}]${r.message?': '+r.message:''}`);e.lbeResult=r;throw e}return r
+    },
+    async readFile(target){
+      let r=await execute({actor:defaultActor,intent:'read_file',target,transaction:{audit:true}});
+      if(!r.ok){let e=new Error(`LBE read failed [${r.error||r.stage}]${r.message?': '+r.message:''}`);e.lbeResult=r;throw e}return r.output
+    },
+  }
+}
+
+// ── sandbox ───────────────────────────────────────────────────────────────────
+export function sandbox(rootDir,options={}){
+  let{audit=false,rollback=false}=options;
+  let rp=path.resolve(rootDir);
+  let lbe=createLBE({rootDir:rp,state:options.state||'local',logSilent:true});
+  let abs=p=>path.isAbsolute(p)?p:path.join(rp,p);
+  let tx={backup:rollback,rollbackOnFailure:rollback,audit};
+  function blocked(method,r){let e=new Error(`sandbox.${method} blocked [${r.error}]${r.message?': '+r.message:''}`);e.lbeResult=r;return e}
+  return{
+    async write(p,content){let r=await lbe.execute({actor:'agent:sdk',intent:'write_file',target:abs(p),content,transaction:tx});if(!r.ok)throw blocked('write',r)},
+    async read(p){let r=await lbe.execute({actor:'agent:sdk',intent:'read_file',target:abs(p),transaction:{audit}});if(!r.ok)throw blocked('read',r);return r.output},
+    async patch(p,content){let r=await lbe.execute({actor:'agent:sdk',intent:'patch_file',target:abs(p),content,transaction:tx});if(!r.ok)throw blocked('patch',r)},
+    lbe,
+  }
+}
+
+// ── makeKeyStore convenience helper ──────────────────────────────────────────
+function makeKeyStore({publicKey,keyId,validDays=365}){
+  let now=new Date(),exp=new Date(now.getTime()+validDays*24*3600*1e3);
+  return{defaultKeyId:keyId,trustedKeys:{[keyId]:{publicKey,notBefore:now.toISOString(),expiresAt:exp.toISOString()}}}
+}