@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/references/native/InsightInitialPublication.java

@@ -0,0 +1,142 @@
+package db;
+
+import com.google.gson.*;
+import com.xebyte.headless.GhidraServerManager;
+import db.buffers.*;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.*;
+import ghidra.framework.client.RepositoryAdapter;
+import ghidra.framework.data.OpenMode;
+import ghidra.framework.store.db.PackedDatabase;
+import ghidra.program.database.ProgramDB;
+import ghidra.util.task.TaskMonitor;
+import insight.InsightInitialJournal;
+import java.nio.file.*;
+import java.nio.channels.*;
+import java.util.*;
+
+/** Prepare under a unique staging name; only promote independently verified complete buffers.
+ * No checkout/check-in, overwrite or buffer write exists for the canonical target path. */
+class InsightInitialPublication {
+    static String text(JsonObject p,String k){return InsightInitialJournal.text(p,k);}
+    static void authority(RepositoryAdapter repo,boolean reader)throws Exception{
+        var user=repo.getUser();if(user==null||(reader?!user.isReadOnly():!user.hasWritePermission()))throw new SecurityException();
+    }
+    static void binding(Path root,JsonObject journal,JsonObject saved)throws Exception{
+        if(!text(journal,"intentHash").equals(InsightInitialJournal.hash(root.resolve("intent.json")))||!text(journal,"snapshotSha256").equals(text(saved,"snapshotSha256")))throw new SecurityException("Initial publication binding changed");
+    }
+    static boolean recovered(RepositoryAdapter repo,String name)throws Exception{
+        var versions=repo.getVersions("/",name);
+        return versions.length==1&&versions[0].getVersion()==1&&versions[0].getCreateTime()==0&&"<Recovered>".equals(versions[0].getComment());
+    }
+    static void verify(RepositoryAdapter repo,String name,String fileId,Path snapshot,String sha,String marker)throws Exception{
+        var item=repo.getItem("/",name);
+        if(item==null||!fileId.equals(item.getFileID())||item.getVersion()!=1||repo.isCheckinActive("/",name))throw new IllegalStateException("Initial item is not quiescent at version one");
+        var versions=repo.getVersions("/",name);
+        if(versions.length!=1||versions[0].getVersion()!=1||!marker.equals(versions[0].getComment())&&!recovered(repo,name))throw new SecurityException("Initial history changed");
+        DBHandle expected=PackedDatabase.getPackedDatabase(snapshot.toFile(),true,TaskMonitor.DUMMY).open(TaskMonitor.DUMMY);
+        try{
+            DBHandle observed=new DBHandle(repo.openDatabase("/",name,1,-1));
+            try{
+                if(expected.getDatabaseId()!=observed.getDatabaseId()||!InsightBlockTransfer.fingerprint(expected.getBufferMgr().getSourceFile()).equals(InsightBlockTransfer.fingerprint(observed.getBufferMgr().getSourceFile())))throw new SecurityException("Initial buffers differ");
+                Object consumer=new Object();ProgramDB program=new ProgramDB(observed,OpenMode.IMMUTABLE,TaskMonitor.DUMMY,consumer);
+                try{if(!sha.equals(program.getExecutableSHA256()))throw new SecurityException("Initial source changed");}finally{program.release(consumer);}
+            }finally{observed.close();}
+        }finally{expected.close();}
+    }
+    static void release(RepositoryAdapter repo,String name,JsonObject j)throws Exception{
+        if(!j.has("checkoutId"))return;
+        for(var held:repo.getCheckouts("/",name))if(held.getCheckoutId()==j.get("checkoutId").getAsLong()){
+            if(!held.getUser().equals(repo.getUser().getName())||held.getCheckoutVersion()>1||repo.isCheckinActive("/",name))throw new SecurityException("Initial checkout remains active or foreign");
+            repo.terminateCheckout("/",name,held.getCheckoutId(),false);
+        }
+    }
+    public static void main(String[] args){var out=System.out;System.setOut(System.err);
+        try{
+            Path root=Path.of(args[0]);String operation=args[1];boolean readOnly=operation.startsWith("verify");JsonObject p=InsightInitialJournal.intent(root);
+            try(var channel=FileChannel.open(root.resolve("lock"),StandardOpenOption.CREATE,StandardOpenOption.WRITE);var lock=channel.tryLock()){
+                if(lock==null){out.println("{\"state\":\"busy\"}");System.exit(0);}
+                JsonObject saved=InsightInitialJournal.prepared(root);Path snapshot=root.resolve(text(saved,"snapshot")),journalPath=root.resolve("publication.json");
+                JsonObject j=Files.exists(journalPath)?InsightInitialJournal.read(journalPath):null;
+                if(j!=null)binding(root,j,saved);
+                Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+                String name=text(p,"target")+".bin",marker="insight target "+text(p,"target"),sha=text(p,"sha256");
+                var manager=new GhidraServerManager();manager.connect();var repo=manager.server().getRepository(text(p,"repository"));repo.connect();authority(repo,readOnly);
+                if(!repo.getUser().getName().equals(System.getenv("GHIDRA_SERVER_USER")))throw new SecurityException();
+                RepositoryAdapter observed=repo;
+                if(operation.equals("verify-stage")){
+                    if(j==null||!j.has("stage"))throw new SecurityException();
+                    verify(observed,text(j,"stage"),text(j,"fileId"),snapshot,sha,marker);
+                    JsonObject proof=j.deepCopy();proof.addProperty("verified",true);InsightInitialJournal.write(root.resolve("stage-verified.json"),proof);
+                    out.println("{\"state\":\"stage_verified\",\"version\":1,\"snapshotBuffersVerified\":true}");System.exit(0);
+                }
+                var canonical=observed.getItem("/",name);
+                if(canonical!=null){
+                    if(j==null)throw new SecurityException("Canonical item has no retained publication intent");
+                    String id=j.has("fileId")?text(j,"fileId"):text(p,"id");
+                    if(!id.equals(canonical.getFileID()))throw new SecurityException("Foreign canonical initial model");
+                    try{verify(observed,name,id,snapshot,sha,marker);}
+                    catch(Exception invalid){
+                        // Compatibility with an older interrupted direct create: preserve the
+                        // proven-owned, uncommitted <Recovered> object under quarantine. No delete.
+                        if(readOnly||j.has("stage")||!recovered(observed,name)||repo.isCheckinActive("/",name))throw invalid;
+                        release(repo,name,j);repo.moveItem("/","/",name,"__initial_abandoned_"+UUID.randomUUID().toString().replace("-",""));canonical=null;
+                        j.addProperty("phase","quarantined");InsightInitialJournal.write(root.resolve("legacy-quarantined.json"),j);
+                    }
+                    if(canonical!=null&&!readOnly)release(repo,name,j);
+                }
+                if(canonical==null){
+                    if(readOnly){out.println("{\"state\":\"absent\"}");System.exit(0);}
+                    if(repo.fileExists("/",name))throw new SecurityException("Canonical path is reserved");
+                    if(operation.equals("stage")){
+                    boolean staged=false;
+                    if(j!=null&&j.has("stage")){
+                        String stage=text(j,"stage");if(!stage.matches("__initial_[a-f0-9]{32}"))throw new SecurityException();
+                        var item=observed.getItem("/",stage);
+                        if(item!=null){
+                            if(!item.getFileID().equals(text(j,"fileId")))throw new SecurityException("Foreign staged initial model");
+                            try{verify(observed,stage,text(j,"fileId"),snapshot,sha,marker);staged=true;}
+                            catch(Exception incomplete){
+                                // Interrupted staging is unpublished. Keep its bytes and receipt;
+                                // start another uniquely named stage instead of overwriting it.
+                                if(!repo.isCheckinActive("/",stage))release(repo,stage,j);
+                            }
+                        }
+                    }
+                    if(!staged){
+                        int calls=j!=null&&j.has("createCalls")?j.get("createCalls").getAsInt():0;
+                        j=new JsonObject();j.addProperty("intentHash",InsightInitialJournal.hash(root.resolve("intent.json")));j.addProperty("snapshotSha256",text(saved,"snapshotSha256"));
+                        j.addProperty("stage","__initial_"+UUID.randomUUID().toString().replace("-",""));j.addProperty("fileId",UUID.randomUUID().toString());
+                        j.addProperty("pid",ProcessHandle.current().pid());j.addProperty("createCalls",calls+1);j.addProperty("phase","create_intent");
+                        Path attempt=root.resolve("create-"+UUID.randomUUID()+".json");InsightInitialJournal.write(attempt,j);InsightInitialJournal.write(journalPath,j);
+                        DBHandle expected=PackedDatabase.getPackedDatabase(snapshot.toFile(),true,TaskMonitor.DUMMY).open(TaskMonitor.DUMMY);
+                        try{
+                            var remote=repo.createDatabase("/",text(j,"stage"),expected.getBufferSize(),"Program",text(j,"fileId"),root.toString());
+                            j.addProperty("checkoutId",remote.getCheckinID());j.addProperty("phase","created");InsightInitialJournal.write(attempt,j);InsightInitialJournal.write(journalPath,j);
+                            try{remote.setVersionComment(marker);InsightBlockTransfer.copy((LocalBufferFile)expected.getBufferMgr().getSourceFile(),remote);if(!remote.setReadOnly())throw new IllegalStateException("Stage save not acknowledged");}
+                            finally{remote.dispose();}
+                        }finally{expected.close();}
+                        j.addProperty("phase","staged");InsightInitialJournal.write(attempt,j);InsightInitialJournal.write(journalPath,j);
+                    }
+                    String stage=text(j,"stage");verify(observed,stage,text(j,"fileId"),snapshot,sha,marker);release(repo,stage,j);
+                    if(repo.getCheckouts("/",stage).length!=0)throw new SecurityException("Stage retains foreign checkout");
+                        out.println("{\"state\":\"staged\",\"version\":1,\"snapshotBuffersVerified\":true}");System.exit(0);
+                    }
+                    if(!operation.equals("promote")||j==null)throw new SecurityException();
+                    JsonObject proof=InsightInitialJournal.read(root.resolve("stage-verified.json"));binding(root,proof,saved);
+                    if(!proof.get("verified").getAsBoolean()||!text(proof,"fileId").equals(text(j,"fileId"))||!text(proof,"stage").equals(text(j,"stage")))throw new SecurityException("Independent stage proof changed");
+                    String stage=text(j,"stage");verify(observed,stage,text(j,"fileId"),snapshot,sha,marker);
+                    if(repo.getCheckouts("/",stage).length!=0)throw new SecurityException("Stage retains checkout");
+                    j.addProperty("phase","promote_intent");InsightInitialJournal.write(journalPath,j);
+                    // Ghidra's server move rejects an existing destination; never overwrite it.
+                    try{repo.moveItem("/","/",stage,name);}catch(Exception lost){try{verify(observed,name,text(j,"fileId"),snapshot,sha,marker);}catch(Exception unproved){unproved.addSuppressed(lost);throw unproved;}}
+                    j.addProperty("phase","committed");InsightInitialJournal.write(journalPath,j);
+                    verify(observed,name,text(j,"fileId"),snapshot,sha,marker);
+                }
+                if(repo.getCheckouts("/",name).length!=0)throw new IllegalStateException("Initial checkout not released");
+                repo.disconnect();manager.server().disconnect();out.println(new Gson().toJson(Map.of("state",readOnly?"verified":"published","version",1,"snapshotBuffersVerified",true)));
+            }
+            System.exit(0);
+        }catch(Throwable failure){failure.printStackTrace(System.err);out.println("{\"state\":\"failed\"}");System.exit(1);}
+    }
+}

package/references/native/InsightKeytool.java

@@ -0,0 +1,16 @@
+import java.nio.file.*;
+import java.util.*;
+
+/** Fixed certificate preparation; the secret remains in the child environment. */
+class InsightKeytool {
+  public static void main(String[] args) throws Exception {
+    if(args.length!=1 || System.getenv("INSIGHT_KEYSTORE_PASSWORD")==null) throw new IllegalArgumentException();
+    var executable=Path.of(System.getProperty("java.home"),"bin",System.getProperty("os.name").startsWith("Windows")?"keytool.exe":"keytool");
+    var command=new ArrayList<String>(List.of(executable.toString(),"-genkeypair","-alias","insight","-keyalg","RSA","-keysize","2048",
+      "-dname","CN=GhidraServer","-ext","SAN=IP:127.0.0.1","-ext","KU=digitalSignature,keyEncipherment","-validity","3650",
+      "-keystore",args[0],"-storetype","PKCS12","-storepass:env","INSIGHT_KEYSTORE_PASSWORD"));
+    var process=new ProcessBuilder(command).redirectError(ProcessBuilder.Redirect.INHERIT).redirectOutput(ProcessBuilder.Redirect.DISCARD).start();
+    int code=process.waitFor(); if(code!=0) System.exit(code);
+    System.out.println("{\"state\":\"ready\"}");
+  }
+}

package/references/native/InsightNativeReceipt.java

@@ -0,0 +1,31 @@
+import com.google.gson.*;
+import java.nio.file.*;
+import java.nio.channels.FileChannel;
+import java.security.MessageDigest;
+import java.util.*;
+
+/** Domain-effect receipt: close/sync native outputs before acknowledging a file/database result. */
+class InsightNativeReceipt {
+    static void write(JsonObject request,Object value)throws Exception{
+        if(!request.has("receipt"))return;
+        Map<String,Object> result=new LinkedHashMap<>();result.put("request",request.get("request_id").getAsString());result.put("operation",request.get("operation").getAsString());result.put("value",value);
+        if(request.has("output")){
+            Path directory=Path.of(request.get("output").getAsString()).getParent();List<Object> files=new ArrayList<>();
+            try(var entries=Files.list(directory)){
+                for(Path file:entries.sorted().toList()){
+                    if(files.size()>=64||!Files.isRegularFile(file,LinkOption.NOFOLLOW_LINKS))throw new IllegalArgumentException("Native output manifest requires at most 64 regular files");
+                    long size=Files.size(file);if(size<1||size>4294967296L)throw new IllegalArgumentException("Native output exceeds artifact limits");
+                    MessageDigest hash=MessageDigest.getInstance("SHA-256");try(var input=Files.newInputStream(file)){byte[] buffer=new byte[65536];for(int count;(count=input.read(buffer))>=0;)if(count>0)hash.update(buffer,0,count);}
+                    try(FileChannel channel=FileChannel.open(file,StandardOpenOption.WRITE)){channel.force(true);}
+                    files.add(Map.of("name",file.getFileName().toString(),"size",size,"sha256",HexFormat.of().formatHex(hash.digest())));
+                }
+            }
+            if(files.isEmpty())throw new IllegalStateException("Native output is empty");result.put("files",files);
+        }
+        Path receipt=Path.of(request.get("receipt").getAsString()),temporary=receipt.resolveSibling("receipt-"+UUID.randomUUID()+".new");
+        Files.writeString(temporary,new GsonBuilder().serializeNulls().create().toJson(result),StandardOpenOption.CREATE_NEW);
+        try(FileChannel channel=FileChannel.open(temporary,StandardOpenOption.WRITE)){channel.force(true);}
+        Files.move(temporary,receipt,StandardCopyOption.ATOMIC_MOVE);
+        if(!System.getProperty("os.name").toLowerCase().contains("win"))try(FileChannel channel=FileChannel.open(receipt.getParent(),StandardOpenOption.READ)){channel.force(true);}
+    }
+}

package/references/native/InsightPlugins.java

@@ -0,0 +1,34 @@
+import insight.InsightExtensions;
+import com.google.gson.*;
+import ghidra.app.script.GhidraScript;
+import ghidra.framework.plugintool.*;
+import ghidra.util.classfinder.ClassSearcher;
+import java.util.*;
+import javax.swing.SwingUtilities;
+
+/** Enable/disable only plugins from explicitly consumed managed modules, in this GUI tool. */
+public class InsightPlugins extends GhidraScript {
+    public void run() throws Exception {
+        JsonObject p=JsonParser.parseString(new String(Base64.getDecoder().decode(getScriptArgs()[0]),java.nio.charset.StandardCharsets.UTF_8)).getAsJsonObject();
+        var tool=state.getTool();if(tool==null)throw new IllegalStateException("Owned GUI required");
+        final Object[] value={null};final Exception[] failure={null};
+        SwingUtilities.invokeAndWait(()->{try{
+            String operation=p.get("operation").getAsString();
+            if(operation.equals("set")){
+                String name=p.get("plugin").getAsString();Class<? extends Plugin> type=null;
+                for(var c:ClassSearcher.getClasses(Plugin.class))if(c.getName().equals(name)&&InsightExtensions.managed(c)){type=c;break;}
+                if(type==null)throw new IllegalArgumentException("Choose a plugin from an enabled managed module");
+                Plugin existing=tool.getManagedPlugins().stream().filter(x->x.getClass().getName().equals(name)).findFirst().orElse(null);
+                boolean enabled=p.get("enabled").getAsBoolean();
+                if(enabled&&existing==null)tool.addPlugin(name);else if(!enabled&&existing!=null)tool.removePlugins(List.of(existing));
+                if(tool.getManagedPlugins().stream().anyMatch(x->x.getClass().getName().equals(name))!=enabled)throw new IllegalStateException("Plugin enablement readback differs");
+                value[0]=Map.of("plugin",name,"enabled",enabled,"lifetime","current-gui-tool");
+            }else if(operation.equals("list")){
+                List<Object> rows=new ArrayList<>();for(Plugin plugin:tool.getManagedPlugins())if(InsightExtensions.managed(plugin.getClass()))rows.add(Map.of("id",plugin.getClass().getName(),"name",plugin.getName(),"enabled",true));
+                rows.sort(Comparator.comparing(r->((Map<?,?>)r).get("id").toString()));
+                if(rows.size()>100)throw new IllegalStateException("Managed GUI plugin inventory exceeds 100 entries");value[0]=Map.of("items",rows,"lifetime","current-gui-tool");
+            }else throw new IllegalArgumentException();
+        }catch(Exception e){failure[0]=e;}});
+        if(failure[0]!=null)throw failure[0];println("INSIGHT_PLUGINS:"+new Gson().toJson(value[0]));
+    }
+}

package/references/native/InsightProjectFiles.java

@@ -0,0 +1,92 @@
+import com.google.gson.*;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import ghidra.framework.model.*;
+import ghidra.base.project.GhidraProject;
+import ghidra.app.plugin.core.archive.ArchiveBridge;
+import ghidra.util.task.TaskMonitor;
+import java.nio.file.*;
+import java.util.*;
+import java.util.zip.*;
+import java.nio.channels.FileChannel;
+import java.security.MessageDigest;
+
+/** Operations are confined to a facade-owned project, never a research worker project. */
+class InsightProjectFiles {
+  static String string(JsonObject p,String key){return p.get(key).getAsString();}
+  static String path(JsonObject p,String key){String s=string(p,key);
+    if(!s.startsWith("/")||s.contains("\\")||s.contains("//")||Arrays.stream(s.split("/")).anyMatch(x->x.equals(".")||x.equals("..")))throw new IllegalArgumentException();return s;}
+  static DomainFolder folder(ProjectData data,String path){DomainFolder f=data.getFolder(path);if(f==null)throw new IllegalArgumentException("Folder not found");return f;}
+  static DomainFile file(ProjectData data,String path){DomainFile f=data.getFile(path);if(f==null)throw new IllegalArgumentException("File not found");return f;}
+  static Map<String,Object> describe(DomainFile f){return Map.of("name",f.getName(),"path",f.getPathname(),"type",f.getContentType());}
+  static String parent(String path){int at=path.lastIndexOf('/');return at==0?"/":path.substring(0,at);}
+  static String name(String path){String n=path.substring(path.lastIndexOf('/')+1);if(n.isEmpty()||n.startsWith("."))throw new IllegalArgumentException();return n;}
+  public static void main(String[] args){var out=System.out;System.setOut(System.err);GhidraProject project=null;
+    try{
+      if(args.length!=1)throw new IllegalArgumentException();
+      Path requestPath=Path.of(args[0]).toRealPath();String requestJson=Files.readString(requestPath);
+      JsonObject p=JsonParser.parseString(requestJson).getAsJsonObject();
+      Path root=Path.of(string(p,"root")).toRealPath();
+      JsonObject owner=JsonParser.parseString(Files.readString(root.resolve("owner.json"))).getAsJsonObject();
+      if(!string(owner,"project").equals(string(p,"project"))||!string(owner,"profile").equals(string(p,"profile")))throw new IllegalArgumentException("Ownership mismatch");
+      Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+      String op=string(p,"operation");Map<String,Object> result=new LinkedHashMap<>();result.put("project",string(p,"project"));
+      if(op.equals("restore")){
+        try(ZipFile zip=new ZipFile(string(p,"input"))){int count=0;long total=0;var entries=zip.entries();
+          while(entries.hasMoreElements()){ZipEntry entry=entries.nextElement();String n=entry.getName();Path relative=Path.of(n);
+            if(++count>100000||relative.isAbsolute()||n.contains("\\")||Arrays.stream(n.split("/")).anyMatch(x->x.equals(".."))||!root.resolve(relative).normalize().startsWith(root))throw new IllegalArgumentException("Archive entry escapes owned project");
+            if(entry.getSize()<0||entry.getSize()>4294967296L||(total+=entry.getSize())>4294967296L)throw new IllegalArgumentException("Archive exceeds restore limit");
+          }
+        }
+        ProjectLocator locator=new ProjectLocator(root.toString(),"project");
+        if(locator.getProjectDir().exists()||locator.getMarkerFile().exists())throw new IllegalArgumentException("Destination exists");
+        ArchiveBridge.restore(Path.of(string(p,"input")).toFile(),locator,TaskMonitor.DUMMY);
+      }
+      project=op.equals("create")?GhidraProject.createProject(root.toString(),"project",false):GhidraProject.openProject(root.toString(),"project",false);
+      ProjectData data=project.getProjectData();
+      if(op.equals("create")||op.equals("restore")||op.equals("open")||op.equals("close"))result.put("state",op.equals("close")?"closed":"ready");
+      else if(op.equals("info"))result.put("state","ready");
+      else if(op.equals("files")){
+        String selected=path(p,"path");DomainFolder f=folder(data,selected);
+        List<Map<String,Object>> entries=new ArrayList<>();
+        for(DomainFolder child:f.getFolders())entries.add(Map.of("name",child.getName(),"path",child.getPathname(),"type","Folder"));
+        for(DomainFile child:f.getFiles())entries.add(describe(child));
+        entries.sort(Comparator.comparing(row->row.get("path").toString()));
+        int offset=p.get("offset").getAsInt(),limit=p.get("limit").getAsInt();
+        result.put("path",selected);result.put("total",entries.size());result.put("offset",offset);result.put("limit",limit);
+        result.put("items",entries.subList(Math.min(offset,entries.size()),Math.min(entries.size(),offset+limit)));
+      }else if(op.equals("create_folder")){
+        String selected=path(p,"path");DomainFolder f=folder(data,parent(selected)).createFolder(name(selected));
+        if(data.getFolder(selected)==null)throw new IllegalStateException();result.put("path",f.getPathname());result.put("state","created");
+      }else if(op.equals("move_file")||op.equals("move_folder")){
+        String source=path(p,"path"),destination=path(p,"destination");DomainFolder to=folder(data,destination);
+        if(op.equals("move_file")){DomainFile f=file(data,source);String expected=destination.equals("/")?"/"+f.getName():destination+"/"+f.getName();
+          f=f.moveTo(to);if(data.getFile(source)!=null||data.getFile(expected)==null)throw new IllegalStateException();result.put("path",f.getPathname());}
+        else{if(source.equals("/"))throw new IllegalArgumentException();DomainFolder f=folder(data,source);if(f.isSameOrAncestor(to))throw new IllegalArgumentException();
+          String expected=destination.equals("/")?"/"+f.getName():destination+"/"+f.getName();f=f.moveTo(to);
+          if(data.getFolder(source)!=null||data.getFolder(expected)==null)throw new IllegalStateException();result.put("path",f.getPathname());}
+        result.put("state","moved");
+      }else if(op.equals("delete_file")){
+        String selected=path(p,"path");file(data,selected).delete();if(data.getFile(selected)!=null)throw new IllegalStateException();result.put("path",selected);result.put("state","deleted");
+      }else if(op.equals("import")){
+        String selected=path(p,"path");DomainFile imported=folder(data,parent(selected)).createFile(name(selected),Path.of(string(p,"input")).toFile(),TaskMonitor.DUMMY);
+        if(!imported.getPathname().equals(selected)||data.getFile(selected)==null)throw new IllegalStateException();result.put("file",describe(imported));result.put("state","imported");
+      }else if(op.equals("archive")){
+        Path output=Path.of(string(p,"output"));if(Files.exists(output))throw new IllegalArgumentException("Output exists");
+        ArchiveBridge.archive(project.getProject(),output.toFile(),TaskMonitor.DUMMY);
+        if(!Files.isRegularFile(output)||Files.size(output)==0)throw new IllegalStateException();result.put("state","archived");result.put("size",Files.size(output));
+      }else if(op.equals("delete")){project.setDeleteOnClose(true);project.close();project=null;
+        if(Files.exists(root.resolve("project.gpr"))||Files.exists(root.resolve("project.rep")))throw new IllegalStateException();result.put("state","deleted");}
+      else throw new IllegalArgumentException("Unknown project operation");
+      if(project!=null){project.close();project=null;}
+      Path journal=requestPath.getParent().resolve("result.json"),temporary=requestPath.getParent().resolve("result.new");
+      String hash=HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(requestJson.getBytes(java.nio.charset.StandardCharsets.UTF_8)));
+      Files.writeString(temporary,new Gson().toJson(Map.of("schema",1,"request",string(p,"request_id"),"hash",hash,"result",result)),StandardOpenOption.CREATE_NEW);
+      try(FileChannel channel=FileChannel.open(temporary,StandardOpenOption.WRITE)){channel.force(true);}
+      Files.move(temporary,journal,StandardCopyOption.ATOMIC_MOVE);
+      if(!System.getProperty("os.name").toLowerCase().contains("win"))try(FileChannel channel=FileChannel.open(requestPath.getParent(),StandardOpenOption.READ)){channel.force(true);}
+      out.println(new Gson().toJson(result));System.exit(0);
+    }catch(Throwable failure){if(project!=null)project.close();failure.printStackTrace(System.err);out.println("{\"error\":\"project_operation_failed\"}");System.exit(1);}
+  }
+}

package/references/native/InsightPublicationRecovery.java

@@ -0,0 +1,63 @@
+package db;
+
+import com.google.gson.*;
+import com.xebyte.headless.GhidraServerManager;
+import db.buffers.InsightBlockTransfer;
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import ghidra.framework.data.OpenMode;
+import ghidra.framework.store.db.PackedDatabase;
+import ghidra.program.database.ProgramDB;
+import ghidra.util.task.TaskMonitor;
+import java.nio.file.*;
+import java.util.*;
+
+/** Verify an immutable exact version; release only the receipt-identified owned checkout. */
+class InsightPublicationRecovery {
+  public static void main(String[] args) {
+    var output=System.out;System.setOut(System.err);
+    try {
+      if(args.length!=7)throw new IllegalArgumentException();
+      String repo=args[0],path=args[1],marker=args[4],sha=args[6];int expected=Integer.parseInt(args[3]);
+      if(!path.startsWith("/")||path.indexOf('/',1)>=0||!marker.matches("insight merge q_[a-f0-9-]{36}"))throw new IllegalArgumentException();
+      Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+      var reader=new GhidraServerManager();reader.connect();var repository=reader.server().getRepository(repo);repository.connect();
+      var user=repository.getUser();if(user==null||!user.isReadOnly()||!user.getName().equals(System.getenv("GHIDRA_SERVER_USER")))throw new SecurityException();
+      String folder="/",name=path.substring(1);
+      var history=repository.getVersions(folder,name);var matches=Arrays.stream(history).filter(item->marker.equals(item.getComment())).toList();
+      if(matches.size()!=1||matches.getFirst().getVersion()!=expected+1){output.println("{\"state\":\"unknown\"}");System.exit(0);}
+      int actual=matches.getFirst().getVersion();
+      DBHandle snapshot=PackedDatabase.getPackedDatabase(Path.of(args[2]).toFile(),true,TaskMonitor.DUMMY).open(TaskMonitor.DUMMY);
+      DBHandle observed=new DBHandle(repository.openDatabase(folder,name,actual,-1));
+      try {
+        if(snapshot.getDatabaseId()!=observed.getDatabaseId()||!InsightBlockTransfer.fingerprint(snapshot.getBufferMgr().getSourceFile()).equals(
+            InsightBlockTransfer.fingerprint(observed.getBufferMgr().getSourceFile())))throw new IllegalStateException("Exact published buffers differ");
+        Object consumer=new Object();ProgramDB program=new ProgramDB(observed,OpenMode.IMMUTABLE,TaskMonitor.DUMMY,consumer);
+        try{if(!sha.equals(program.getExecutableSHA256()))throw new SecurityException("Published source identity changed");}
+        finally{program.release(consumer);}
+      }finally{snapshot.close();observed.close();}
+      repository.disconnect();reader.server().disconnect();
+      JsonObject intent=JsonParser.parseString(Files.readString(Path.of(args[5]))).getAsJsonObject();
+      if(!repo.equals(intent.get("repository").getAsString())||!path.equals(intent.get("path").getAsString())||
+          !marker.equals(intent.get("marker").getAsString())||intent.get("baseline").getAsInt()!=expected)throw new SecurityException();
+      long checkout=intent.get("checkoutId").getAsLong();
+      var writer=new GhidraServerManager(System.getenv("GHIDRA_SERVER_HOST"),Integer.parseInt(System.getenv("GHIDRA_SERVER_PORT")),
+        System.getenv("INSIGHT_PUBLISHER_USER"),System.getenv("INSIGHT_PUBLISHER_PASSWORD"));
+      writer.connect();var owned=writer.server().getRepository(repo);owned.connect();
+      var authority=owned.getUser();if(authority==null||!authority.hasWritePermission()||!authority.getName().equals(System.getenv("INSIGHT_PUBLISHER_USER")))throw new SecurityException();
+      var held=Arrays.stream(owned.getCheckouts(folder,name)).filter(item->item.getCheckoutId()==checkout).toList();
+      if(held.size()>1)throw new IllegalStateException();
+      if(!held.isEmpty()) {
+        var item=held.getFirst();
+        if(!authority.getName().equals(item.getUser())||item.getCheckoutVersion()!=expected||owned.isCheckinActive(folder,name))
+          throw new IllegalStateException("Owned checkout cannot be safely released yet");
+        owned.terminateCheckout(folder,name,checkout,false);
+      }
+      if(Arrays.stream(owned.getCheckouts(folder,name)).anyMatch(item->item.getCheckoutId()==checkout))throw new IllegalStateException();
+      owned.disconnect();writer.server().disconnect();
+      output.println(new Gson().toJson(Map.of("state","verified","version",actual,"snapshotBuffersVerified",true,"ownedCheckoutReleased",true)));
+      System.exit(0);
+    }catch(Throwable failure){failure.printStackTrace(System.err);output.println("{\"state\":\"unknown\"}");System.exit(0);}
+  }
+}

package/references/native/InsightPythonWheels.java

@@ -0,0 +1,31 @@
+import java.nio.file.*;
+import java.util.zip.*;
+import java.util.*;
+
+/** Extract only the verified SDK's pure Python wheels into a fresh owned directory. */
+class InsightPythonWheels {
+  public static void main(String[] args)throws Exception{
+    if(args.length!=4)throw new IllegalArgumentException();Path root=Path.of(args[0]).toRealPath();int count=0;long total=0;
+    for(int i=1;i<args.length;i++)try(ZipFile zip=new ZipFile(args[i])){
+      var entries=zip.entries();while(entries.hasMoreElements()){
+        ZipEntry entry=entries.nextElement();String name=entry.getName();Path relative=Path.of(name),output=root.resolve(relative).normalize();
+        if(++count>10000||relative.isAbsolute()||name.contains("\\")||Arrays.stream(name.split("/")).anyMatch(x->x.equals(".."))||!output.startsWith(root))throw new IllegalArgumentException();
+        if(entry.isDirectory()){Files.createDirectories(output);continue;}
+        if(entry.getSize()<0||entry.getSize()>16777216||(total+=entry.getSize())>67108864)throw new IllegalArgumentException();
+        Files.createDirectories(output.getParent());try(var in=zip.getInputStream(entry);var out=Files.newOutputStream(output,StandardOpenOption.CREATE_NEW)){
+          byte[] buffer=new byte[65536];long actual=0;int length;
+          while((length=in.read(buffer))!=-1){actual+=length;if(actual>entry.getSize())throw new IllegalArgumentException();out.write(buffer,0,length);}
+          if(actual!=entry.getSize())throw new IllegalArgumentException();
+        }
+      }
+    }
+    // Ghidra 12.1.2's LLDB adapter calls a nonexistent SBProcess.write_memory method.
+    // Adapt only the newly extracted owned copy; refuse a different upstream implementation.
+    Path methods=root.resolve("ghidralldb/methods.py");String source=Files.readString(methods);
+    String original="    proc.write_memory(offset, data)";
+    if(source.indexOf(original)<0||source.indexOf(original)!=source.lastIndexOf(original))throw new IllegalArgumentException("Unexpected pinned LLDB memory writer");
+    String replacement="    error = lldb.SBError()\n    written = proc.WriteMemory(offset, data, error)\n    if error.Fail() or written != len(data):\n        raise RuntimeError(\"LLDB memory write failed: \" + error.GetCString())";
+    Files.writeString(methods,source.replace(original,replacement),StandardOpenOption.TRUNCATE_EXISTING);
+    System.out.println("{\"state\":\"prepared\",\"lldb_memory_adapter\":\"insight-sbprocess-v1\"}");
+  }
+}