@hraness/ghostget 0.17.6 → 0.18.2

package/src/auth.ts

@@ -90,6 +90,8 @@ export type GhostgetAuth =
       readonly scopes: readonly string[];
       /** The credential lifecycle and token file are owned by Ghostget. */
       readonly managed?: true;
+      /** An immutable local token copy owned by Ghostget; no renewal or vault link. */
+      readonly ownedImport?: true;
       readonly subject?: string;
     }
   | {
@@ -119,6 +121,7 @@ export type AuthInput =
       readonly tokenFile: string;
       readonly scopes: readonly string[];
       readonly managed?: true;
+      readonly ownedImport?: true;
       readonly subject?: string;
     }
   | {
@@ -268,6 +271,9 @@ export function createAuth(id: string, input: AuthInput): GhostgetAuth {
       throw new Error("OAuth token-file auth has an invalid provider");
     }
     if (!isSafeOAuthTokenPath(input.tokenFile)) throw new Error("OAuth token-file auth has an invalid path");
+    if (input.ownedImport === true && (input.managed === true || input.oauthProvider !== "x" || subject === undefined || !/^[0-9]{1,19}$/u.test(subject))) {
+      throw new Error("owned token imports require an exact X subject and cannot be renewable");
+    }
     return {
       schemaVersion: 1,
       id,
@@ -276,6 +282,7 @@ export function createAuth(id: string, input: AuthInput): GhostgetAuth {
       path: resolve(input.tokenFile),
       scopes: normalizeOAuthScopes(input.scopes),
       ...(input.managed === true ? { managed: true as const } : {}),
+      ...(input.ownedImport === true ? { ownedImport: true as const } : {}),
       ...(subject === undefined ? {} : { subject }),
     };
   }
@@ -399,6 +406,7 @@ export function saveAuth(
           `auth locator ${auth.id} changed concurrently before replacement`,
         );
       }
+      const priorCredential = replacementCredentialSnapshot(current.auth, auth, environment);
       rotateReadProjectionAuthIncarnation(auth.id, environment);
       removePrivateAuthState(auth.id, environment);
       if (!writePrivateJsonIfUnchanged(
@@ -410,6 +418,7 @@ export function saveAuth(
           `auth locator ${auth.id} changed concurrently before replacement`,
         );
       }
+      removeReplacedCredential(priorCredential, environment);
       return path;
     }),
   );
@@ -635,6 +644,7 @@ export function parseAuth(value: unknown): GhostgetAuth {
   if (record.kind === "oauth-token-file") {
     const expected = ["schemaVersion", "id", "kind", "provider", "path", "scopes"];
     if (record.managed !== undefined) expected.push("managed");
+    if (record.ownedImport !== undefined) expected.push("ownedImport");
     if (record.subject !== undefined) expected.push("subject");
     if (!exactKeys(record, expected)) throw new Error("auth record has unsupported fields");
     if (!isProviderPluginSurfaceId(record.provider)) {
@@ -646,6 +656,9 @@ export function parseAuth(value: unknown): GhostgetAuth {
     if (record.managed !== undefined && record.managed !== true) {
       throw new Error("auth record has an invalid managed OAuth lifecycle marker");
     }
+    if (record.ownedImport !== undefined && (record.ownedImport !== true || record.managed !== undefined || record.provider !== "x" || typeof record.subject !== "string" || !/^[0-9]{1,19}$/u.test(record.subject))) {
+      throw new Error("auth record has an invalid owned token import marker");
+    }
     const rawScopes = record.scopes;
     if (!Array.isArray(rawScopes) || !rawScopes.every((scope) => typeof scope === "string")) {
       throw new Error("auth record has invalid OAuth scopes");
@@ -666,6 +679,7 @@ export function parseAuth(value: unknown): GhostgetAuth {
       path: record.path,
       scopes,
       ...(record.managed === true ? { managed: true as const } : {}),
+      ...(record.ownedImport === true ? { ownedImport: true as const } : {}),
       ...(subject === undefined ? {} : { subject }),
     };
   }
@@ -967,6 +981,7 @@ export function replaceAuthIfUnchanged(
         observed === null
         || observed.contentSha256 !== current.contentSha256
       ) return Object.freeze({ replaced: false as const });
+      const priorCredential = replacementCredentialSnapshot(current.auth, replacement.auth, environment);
       rotateReadProjectionAuthIncarnation(current.auth.id, environment);
       removePrivateAuthState(current.auth.id, environment);
       const replaced = writePrivateJsonIfUnchanged(
@@ -975,6 +990,7 @@ export function replaceAuthIfUnchanged(
         { expectedCurrentContentSha256: current.contentSha256 },
       );
       if (!replaced) return Object.freeze({ replaced: false as const });
+      removeReplacedCredential(priorCredential, environment);
       return Object.freeze({ replaced: true as const, snapshot: replacement });
     });
   const linkedMutation = current.auth.kind === "linked-device-store"
@@ -1041,7 +1057,7 @@ function managedOAuthCredentialSnapshot(
   auth: GhostgetAuth,
   environment: Readonly<Record<string, string | undefined>>,
 ): Readonly<{ path: string; contentSha256: string }> | null {
-  if (auth.kind !== "oauth-token-file" || auth.managed !== true) return null;
+  if (auth.kind !== "oauth-token-file" || (auth.managed !== true && auth.ownedImport !== true)) return null;
   const expectedDirectory = join(ghostgetStateHome(environment), "auth", "oauth-tokens");
   if (
     dirname(auth.path) !== expectedDirectory
@@ -1061,6 +1077,24 @@ function managedOAuthCredentialSnapshot(
       });
 }
 
+function replacementCredentialSnapshot(
+  previous: GhostgetAuth,
+  replacement: GhostgetAuth,
+  environment: Readonly<Record<string, string | undefined>>,
+): Readonly<{ path: string; contentSha256: string }> | null {
+  if (previous.kind === "oauth-token-file" && replacement.kind === "oauth-token-file" && previous.path === replacement.path) return null;
+  return managedOAuthCredentialSnapshot(previous, environment);
+}
+
+function removeReplacedCredential(
+  credential: Readonly<{ path: string; contentSha256: string }> | null,
+  environment: Readonly<Record<string, string | undefined>>,
+): void {
+  if (credential !== null && !removePrivateStateFileIfUnchanged(credential.path, { expectedCurrentContentSha256: credential.contentSha256 }, environment)) {
+    throw new Error("the account was replaced but its prior owned credential changed before cleanup");
+  }
+}
+
 export function removeAuth(id: string, environment: Readonly<Record<string, string | undefined>> = process.env): boolean {
   const path = authPath(id, environment);
   let current: AuthSnapshot | null;

package/src/beeper-client-types.ts

@@ -96,7 +96,7 @@ export type BeeperContactInteractionExportReceipt = Readonly<{
   implementation: Readonly<{
     producer: Readonly<{
       package: "@hraness/ghostget";
-      version: "0.17.6";
+      version: "0.18.2";
     }>;
     officialCli: Readonly<{
       implementation: "github.com/beeper/cli";

package/src/cli.ts

@@ -181,6 +181,24 @@ export async function runGhostgetCliProcess(
     stdout: output.stdout,
     stderr: output.stderr ?? defaultOutput.stderr,
   };
+  try {
+    const { assertGatewayCommandAllowed } = await import("./control/web-policy");
+    assertGatewayCommandAllowed(rawArguments, process.env);
+    if (rawArguments[0] === "web") {
+      const { runWebCommand } = await import("./control/cli");
+      process.exitCode = await runWebCommand(rawArguments, process.env, resolvedOutput);
+      return;
+    }
+    if (rawArguments[0] === "interface") {
+      const { runInterfaceCommand } = await import("./control/interface-cli");
+      process.exitCode = runInterfaceCommand(rawArguments, process.env, resolvedOutput);
+      return;
+    }
+  } catch {
+    resolvedOutput.stderr("Ghostget gateway-only policy blocks this command, or its policy state is unavailable. Review the native app.\n");
+    process.exitCode = 1;
+    return;
+  }
   if (isPublicGhostgetCommand(rawArguments)) {
     const knowledge = await loadKnowledgeCli();
     process.exitCode = await knowledge.main(rawArguments, resolvedOutput);

package/src/confirmed-write-platform.ts

@@ -7,6 +7,7 @@ import { ConfirmedWriteFailure, confirmedWriteAttempt, type ConfirmedWritePhase
 import { redactSensitiveText } from "@hraness/kb/clip/persist";
 
 import { executeBrowserRecipe, PreservedBrowserArtifactsError, type BrowserDispatchEvent } from "./browser";
+import { assertOperationPermission, checkOperationPermission, readOperationPolicy } from "./operation-permission";
 import { canonicalJson, DOM_ACTION_TRANSPORT_DISABLED_MESSAGE, expandBrowserRecipe, isLocalCliOperation, isProviderOperation, isReviewedTemplateOperation, isWebSessionOperation, manifestHash, sha256, type FileInputValue, type InputValue, type GhostgetManifest } from "./model";
 
 import { localCliContractIdentity } from "./local-cli-contracts";
@@ -154,6 +155,13 @@ export function makeConfirmedWritePlatform(kernel: ConfirmedWriteKernel, origina
     const registry = options.registry ?? providerPluginRegistry;
     const invocation = checked.invocation;
     const operation = checked.operation;
+    const dispatchPermissionCheck = (): void | Promise<void> => {
+      const permissionOptions = { environment: options.environment, registry, ...(options.signal === undefined ? {} : { signal: options.signal }) };
+      // Legacy native execution persists its dispatch prefix before returning a
+      // Promise. Managed admission may need an asynchronous lease recheck.
+      if (readOperationPolicy(options.environment).managed) return checkOperationPermission(invocation, permissionOptions);
+      assertOperationPermission(invocation, permissionOptions);
+    };
     if (operation.risk === "R4") throw new Error("R4 capabilities are blocked by wrench");
     if (operation.risk !== "R2" && operation.risk !== "R3") throw new Error("only R2 and R3 plans use confirmation");
     const risk = operation.risk;
@@ -340,7 +348,7 @@ export function makeConfirmedWritePlatform(kernel: ConfirmedWriteKernel, origina
       error: "execution was prepared but no durable final outcome was recorded",
     });
     let duplicateSourceClaimed = false;
-    const persistDispatchProgress = (
+    const persistDispatchProgress = async (
       event:
         | BrowserDispatchEvent
         | ProviderDispatchEvent
@@ -349,6 +357,10 @@ export function makeConfirmedWritePlatform(kernel: ConfirmedWriteKernel, origina
         | ReviewedTemplateDispatchEvent,
       phase: "starting" | "verified",
     ): Promise<void> => {
+      if (phase === "starting") {
+        const permission = dispatchPermissionCheck();
+        if (permission !== undefined) await permission;
+      }
       const expectedDispatch = plannedDispatches[event.index - 1];
       const prior = durableReceipt.dispatch;
       const expectedPrior = phase === "starting"
@@ -612,6 +624,8 @@ export function makeConfirmedWritePlatform(kernel: ConfirmedWriteKernel, origina
       }, options.environment)),
       outputLimit: attempt("dispatch", () => executionOutputLimit(operation)),
       dispatch: native("dispatch", async () => {
+        const permission = dispatchPermissionCheck();
+        if (permission !== undefined) await permission;
         if (options.preflightFailure !== undefined) {
           throw options.preflightFailure;
         }
@@ -1015,6 +1029,7 @@ export function makeConfirmedWritePlatform(kernel: ConfirmedWriteKernel, origina
     admission: (invocation: PreparedInvocation, options: RunPreparedOptions) => attempt("admission", () => {
       const registry = options.registry ?? providerPluginRegistry;
       const checked = revalidatePreparedInvocation(invocation, registry);
+      assertOperationPermission(checked.invocation, { environment: options.environment, registry });
       const portableIdentity = checked.invocation.portablePluginContract ?? null;
       const runId = options.runId ?? crypto.randomUUID();
       const pluginResolution = resolveCodeOwnedPluginOperation(checked.operation, registry);

package/src/control/account-revision.ts

@@ -0,0 +1,16 @@
+import { loadAuthSnapshotIfPresent, type AuthSnapshot } from "../auth";
+import { canonicalJson, sha256 } from "../canonical-json";
+import { projectionAuthIdentityHash, withSettledReadProjectionAuthAdmission } from "../read-projections";
+
+/** An account editor revision binds both metadata and the exact account lifetime. */
+export function connectionAccountRevision(snapshot: AuthSnapshot, environment: Readonly<Record<string, string | undefined>> = process.env): string {
+  return withSettledReadProjectionAuthAdmission(snapshot.auth.id, environment, () => {
+    const current = loadAuthSnapshotIfPresent(snapshot.auth.id, environment);
+    if (current === null || current.contentSha256 !== snapshot.contentSha256) throw new Error("Account changed while its revision was being inspected.");
+    return sha256(canonicalJson({
+      schemaVersion: 1,
+      metadata: snapshot.contentSha256,
+      incarnation: projectionAuthIdentityHash(snapshot.auth.id, sha256(canonicalJson(snapshot.auth)), environment),
+    }));
+  });
+}

package/src/control/activity.ts

@@ -0,0 +1,104 @@
+import { Database, constants as sqlite } from "bun:sqlite";
+import { closeSync, constants, fstatSync, lstatSync, openSync } from "node:fs";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { join } from "node:path";
+import { ensurePrivateStateDirectory, ghostgetStateHome, snapshotPrivateStateDirectory } from "../storage";
+import { canonicalJson, sha256 } from "../canonical-json";
+import type { ActivityPage, ActivityQuery, ActivityRow } from "./protocol";
+import { ControlError, parseActivityQuery } from "./validation";
+import type { ControlEnvironment } from "./web-policy";
+
+type StoredRow={seq:number;id:string;started_at:string;finished_at:string|null;duration_ms:number|null;method:"GET"|"HEAD";origin:string|null;rule_id:string|null;endpoint:string|null;decision:ActivityRow["decision"];outcome:ActivityRow["outcome"];http_status:number|null;response_bytes:number;error_code:string|null};
+const projection=(r:StoredRow):ActivityRow=>({id:r.id,sequence:r.seq,startedAt:r.started_at,finishedAt:r.finished_at,durationMs:r.duration_ms,method:r.method,origin:r.origin,ruleId:r.rule_id,endpoint:r.endpoint,decision:r.decision,outcome:r.outcome,httpStatus:r.http_status,responseBytes:r.response_bytes,errorCode:r.error_code});
+const COLUMNS="seq,id,started_at,finished_at,duration_ms,method,origin,rule_id,endpoint,decision,outcome,http_status,response_bytes,error_code";
+
+/** One native helper owns this store. It contains metadata only and grants no authority. */
+export class ActivityStore {
+  private readonly db:Database;
+  private readonly cursorKey=randomBytes(32);
+  private readonly directory:string;
+  private readonly identity:ReturnType<typeof ensurePrivateStateDirectory>;
+  private readonly fileIdentity:{dev:number;ino:number};
+  private closed=false;
+  private readonly startedMonotonic=new Map<string,number>();
+  constructor(private readonly environment:ControlEnvironment=process.env, private readonly now:()=>number=Date.now,private readonly monotonic:()=>number=()=>performance.now()) {
+    this.directory=join(ghostgetStateHome(environment),"control","activity");
+    this.identity=ensurePrivateStateDirectory(this.directory,environment);
+    const path=join(this.directory,"requests.sqlite");
+    const fd=openSync(path,constants.O_CREAT|constants.O_RDWR|constants.O_NOFOLLOW,0o600);
+    try { const stat=fstatSync(fd); if(!stat.isFile() || stat.uid!==process.getuid?.() || (stat.mode&0o777)!==0o600 || stat.nlink!==1) throw new Error("unsafe activity file"); this.fileIdentity={dev:stat.dev,ino:stat.ino}; } finally {closeSync(fd);}
+    this.checkFiles();
+    this.db=new Database(path,sqlite.SQLITE_OPEN_READWRITE|sqlite.SQLITE_OPEN_NOFOLLOW);
+    try {
+      this.db.exec("PRAGMA busy_timeout=250; PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL; PRAGMA secure_delete=ON; PRAGMA max_page_count=32768; PRAGMA trusted_schema=OFF;");
+      const version=this.db.query<{user_version:number},[]>("PRAGMA user_version").get()?.user_version;
+      if(version!==0&&version!==1) throw new Error("unsupported activity schema");
+      this.db.exec("CREATE TABLE IF NOT EXISTS requests (seq INTEGER PRIMARY KEY AUTOINCREMENT,id TEXT NOT NULL UNIQUE,started_at TEXT NOT NULL,finished_at TEXT,duration_ms INTEGER,method TEXT NOT NULL CHECK(method IN ('GET','HEAD')),origin TEXT,rule_id TEXT,endpoint TEXT,decision TEXT NOT NULL CHECK(decision IN ('allow','deny','ask')),outcome TEXT NOT NULL CHECK(outcome IN ('started','succeeded','denied','failed','cancelled','interrupted')),http_status INTEGER,response_bytes INTEGER NOT NULL DEFAULT 0,error_code TEXT); CREATE INDEX IF NOT EXISTS requests_method ON requests(method,seq); CREATE INDEX IF NOT EXISTS requests_outcome ON requests(outcome,seq); CREATE INDEX IF NOT EXISTS requests_origin ON requests(origin,seq); CREATE INDEX IF NOT EXISTS requests_time ON requests(started_at,seq); PRAGMA user_version=1;");
+      this.db.query("UPDATE requests SET outcome='interrupted',finished_at=?,error_code='PROCESS_INTERRUPTED' WHERE outcome='started'").run(new Date(now()).toISOString());
+      this.prune(); this.checkFiles();
+    } catch { this.db.close(); throw new ControlError("ACTIVITY_UNAVAILABLE","Local request history could not be opened safely."); }
+  }
+  private checkFiles():void {
+    snapshotPrivateStateDirectory(this.directory,this.environment,this.identity);
+    for(const name of ["requests.sqlite","requests.sqlite-journal","requests.sqlite-wal","requests.sqlite-shm"]) {
+      let stat:ReturnType<typeof lstatSync>; try {stat=lstatSync(join(this.directory,name));} catch(error) {if((error as NodeJS.ErrnoException).code==="ENOENT"&&name!=="requests.sqlite") continue; throw error;}
+      if(!stat.isFile()||stat.uid!==process.getuid?.()||(stat.mode&0o777)!==0o600||stat.nlink!==1||name.endsWith("-wal")||name.endsWith("-shm")) throw new ControlError("ACTIVITY_UNSAFE","Local request history has unsafe filesystem state.");
+      if(name==="requests.sqlite"&&(stat.dev!==this.fileIdentity.dev||stat.ino!==this.fileIdentity.ino)) throw new ControlError("ACTIVITY_REPLACED","Local request history changed. Restart Ghostget.");
+    }
+  }
+  private ready():void { if(this.closed) throw new ControlError("ACTIVITY_CLOSED","Local request history is closed."); this.checkFiles(); }
+  private prune():void {
+    // Audit retention never authorizes retries; provider dispatch journals are separate.
+    this.db.query("DELETE FROM requests WHERE outcome != 'started' AND (started_at < ? OR seq < COALESCE((SELECT seq FROM requests WHERE outcome != 'started' ORDER BY seq DESC LIMIT 1 OFFSET 9999),0))").run(new Date(this.now()-30*86400_000).toISOString());
+  }
+  start(row:Pick<ActivityRow,"id"|"method"|"origin"|"ruleId"|"endpoint"|"decision">):void {
+    this.ready();
+    this.db.transaction(()=>{
+      this.prune();
+      const count=this.db.query<{n:number},[]>("SELECT COUNT(*) AS n FROM requests").get()!.n;
+      if(count>=10_128) throw new ControlError("ACTIVITY_FULL","Request history is at capacity. Wait for active requests to finish.");
+      this.db.query("INSERT INTO requests(id,started_at,method,origin,rule_id,endpoint,decision,outcome) VALUES(?,?,?,?,?,?,?,'started')").run(row.id,new Date(this.now()).toISOString(),row.method,row.origin,row.ruleId,row.endpoint,row.decision);
+    }).immediate();
+    this.startedMonotonic.set(row.id,this.monotonic());
+    this.checkFiles();
+  }
+  finish(id:string,result:Pick<ActivityRow,"outcome"|"httpStatus"|"responseBytes"|"errorCode">):void {
+    this.ready();
+    if(result.outcome==="started") throw new Error("activity finish must be terminal");
+    const started=this.startedMonotonic.get(id);
+    const duration=started===undefined?null:Math.max(0,Math.round(this.monotonic()-started));
+    const r=this.db.query("UPDATE requests SET outcome=?,finished_at=?,duration_ms=?,http_status=?,response_bytes=?,error_code=? WHERE id=? AND outcome='started'").run(result.outcome,new Date(this.now()).toISOString(),duration,result.httpStatus,result.responseBytes,result.errorCode,id);
+    if(r.changes!==1) throw new ControlError("ACTIVITY_CONFLICT","Request history could not record this result.");
+    this.startedMonotonic.delete(id);
+    this.prune();
+    this.checkFiles();
+  }
+  query(raw:ActivityQuery):ActivityPage {
+    this.ready(); const q=parseActivityQuery(raw); const fingerprint=sha256(canonicalJson({...q,cursor:null}));
+    const maximum=this.db.query<{n:number},[]>("SELECT COALESCE(MAX(seq),0) AS n FROM requests").get()!.n;
+    let upper=maximum; let after:number|null=null;
+    if(q.cursor!==null) {
+      try {
+        const parts=q.cursor.split("."); if(parts.length!==2) throw new Error();
+        const payload=parts[0]!; const mac=Buffer.from(parts[1]!,"hex"); const expected=createHmac("sha256",this.cursorKey).update(payload).digest();
+        if(mac.length!==expected.length||!timingSafeEqual(mac,expected)) throw new Error();
+        const v=JSON.parse(Buffer.from(payload,"base64url").toString("utf8")) as {f?:unknown;u?:unknown;a?:unknown};
+        if(v.f!==fingerprint||!Number.isSafeInteger(v.u)||!Number.isSafeInteger(v.a)||typeof v.u!=="number"||typeof v.a!=="number"||v.u<0||v.a<1||v.a>v.u||v.u>maximum) throw new Error();
+        upper=v.u; after=v.a;
+      } catch {throw new ControlError("STALE_CURSOR","The activity view expired. Refresh to continue.");}
+    }
+    const where=["seq <= ?"]; const args:(number|string)[]=[upper];
+    if(q.method!=="all"){where.push("method = ?");args.push(q.method);}
+    if(q.outcome!=="all"){where.push("outcome = ?");args.push(q.outcome);}
+    if(q.origin!==null){where.push("origin = ?");args.push(q.origin);}
+    if(q.since!==null){where.push("started_at >= ?");args.push(q.since);}
+    if(q.search.trim()) {where.push("(COALESCE(origin,'') || ' ' || COALESCE(rule_id,'') || ' ' || COALESCE(endpoint,'') || ' ' || method || ' ' || outcome || ' ' || COALESCE(error_code,'')) LIKE ? ESCAPE '\\'"); args.push(`%${q.search.trim().replace(/[\\%_]/gu,"\\$&")}%`);}
+    const matchingCount=this.db.query<{n:number},(number|string)[]>(`SELECT COUNT(*) AS n FROM requests WHERE ${where.join(" AND ")}`).get(...args)!.n;
+    if(after!==null){where.push(`seq ${q.order==="newest"?"<":">"} ?`);args.push(after);}
+    const rows=this.db.query<StoredRow,(number|string)[]>(`SELECT ${COLUMNS} FROM requests WHERE ${where.join(" AND ")} ORDER BY seq ${q.order==="newest"?"DESC":"ASC"} LIMIT ?`).all(...args,q.limit+1);
+    const more=rows.length>q.limit; const selected=rows.slice(0,q.limit); let nextCursor:string|null=null;
+    if(more){const payload=Buffer.from(JSON.stringify({f:fingerprint,u:upper,a:selected.at(-1)!.seq})).toString("base64url");nextCursor=`${payload}.${createHmac("sha256",this.cursorKey).update(payload).digest("hex")}`;}
+    return {rows:selected.map(projection),nextCursor,snapshotSequence:upper,matchingCount,newerCount:this.db.query<{n:number},[number]>("SELECT COUNT(*) AS n FROM requests WHERE seq > ?").get(upper)!.n};
+  }
+  close():void {if(this.closed)return;this.closed=true;this.db.close();}
+}

package/src/control/approval-broker.ts

@@ -0,0 +1,59 @@
+import type { AgentApprovalResponse, ApprovalTarget, ApprovalView, CheckedApproval } from "./protocol";
+import { ControlError } from "./validation";
+
+type Entry={readonly id:string;readonly target:ApprovalTarget;readonly checked:CheckedApproval;readonly viewBytes:number;expiresAt:number;expiresAtWall:number;status:AgentApprovalResponse["status"]};
+const MAX_APPROVAL_VIEW_BYTES=512*1024;
+function view(id:string,checked:CheckedApproval,expiresAtWall:number):ApprovalView{return {id,digest:checked.digest,kind:checked.kind,title:checked.title,account:checked.account,effect:checked.effect,preview:checked.preview,expiresAt:new Date(expiresAtWall).toISOString()};}
+/** Only the private native control channel receives a reference to decide(). */
+export class ApprovalBroker {
+  private readonly entries=new Map<string,Entry>();
+  private closed=false;
+  constructor(private readonly recompute:(target:ApprovalTarget)=>Promise<CheckedApproval>,private readonly now:()=>number=()=>performance.now(),private readonly recheck:(target:ApprovalTarget,checked:CheckedApproval)=>Promise<CheckedApproval>=target=>recompute(target),private readonly wallNow:()=>number=Date.now) {}
+  private sweep():void {for(const [id,e] of this.entries) if(this.now()>=e.expiresAt) this.entries.delete(id);}
+  async request(id:string,target:ApprovalTarget,expectedDigest:string):Promise<AgentApprovalResponse> {
+    if(this.closed)throw new ControlError("CONTROL_CLOSED","The control service is closing.");
+    this.sweep();
+    if(this.entries.has(id)) throw new ControlError("APPROVAL_REPLAY","An approval request identifier cannot be reused.");
+    if(this.entries.size>=128) throw new ControlError("APPROVAL_QUEUE_FULL","The approval queue is full.");
+    const checked=await this.recompute(target);
+    if(checked.digest!==expectedDigest || checked.decision!=="ask") return {protocol:"ghostget.approval/1",id,digest:expectedDigest,status:"invalid"};
+    // Recheck the bound after asynchronous preparation; concurrent requests cannot overfill it.
+    if(this.closed)throw new ControlError("CONTROL_CLOSED","The control service is closing.");
+    if(this.entries.size>=128 || this.entries.has(id)) throw new ControlError("APPROVAL_QUEUE_FULL","The approval queue is full.");
+    const now=this.now();const expiresAtWall=this.wallNow()+120_000;
+    const viewBytes=Buffer.byteLength(JSON.stringify(view(id,checked,expiresAtWall)))+1;
+    const retainedBytes=[...this.entries.values()].reduce((total,entry)=>total+entry.viewBytes,2);
+    if(retainedBytes+viewBytes>MAX_APPROVAL_VIEW_BYTES)throw new ControlError("APPROVAL_QUEUE_FULL","The approval queue has reached its preview-size limit. Finish an existing request before retrying.");
+    this.entries.set(id,{id,target,checked,viewBytes,expiresAt:now+120_000,expiresAtWall,status:"pending"});
+    return {protocol:"ghostget.approval/1",id,digest:expectedDigest,status:"pending"};
+  }
+  async check(id:string,digest:string):Promise<AgentApprovalResponse> {
+    this.sweep();const e=this.entries.get(id);
+    let status:AgentApprovalResponse["status"]="expired";
+    if(e!==undefined&&e.checked.digest===digest) {
+      if(e.status==="allowed"||e.status==="pending") {
+        const checked=e.status==="allowed" ? await this.recheck(e.target,e.checked) : await this.recompute(e.target);
+        if(this.closed||this.entries.get(id)!==e||this.now()>=e.expiresAt)return {protocol:"ghostget.approval/1",id,digest,status:"expired"};
+        if(checked.digest!==digest||checked.decision!=="ask") e.status="invalid";
+      }
+      status=e.status;
+    }
+    return {protocol:"ghostget.approval/1",id,digest,status};
+  }
+  async decide(id:string,digest:string,decision:"allow-once"|"deny"):Promise<void> {
+    this.sweep();const e=this.entries.get(id);
+    if(e===undefined||e.checked.digest!==digest||e.status!=="pending") throw new ControlError("APPROVAL_STALE","This request is no longer awaiting approval.");
+    if(decision==="deny") {e.status="denied";return;}
+    const checked=await this.recompute(e.target);
+    if(this.closed||this.entries.get(id)!==e||e.status!=="pending"||this.now()>=e.expiresAt||checked.digest!==digest||checked.decision!=="ask") throw new ControlError("APPROVAL_STALE","The request or its policy changed. The agent must request approval again.");
+    e.status="allowed";e.expiresAt=this.now()+600_000;e.expiresAtWall=this.wallNow()+600_000;
+  }
+  cancel(id:string,digest:string):AgentApprovalResponse {
+    const e=this.entries.get(id);if(e?.checked.digest===digest)this.entries.delete(id);
+    return {protocol:"ghostget.approval/1",id,digest,status:"cancelled"};
+  }
+  list():readonly ApprovalView[] {
+    this.sweep();return [...this.entries.values()].filter(e=>e.status==="pending").map(e=>view(e.id,e.checked,e.expiresAtWall));
+  }
+  close():void {this.closed=true;this.entries.clear();}
+}

package/src/control/approval-client.ts

@@ -0,0 +1,49 @@
+import { connect } from "node:net";
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { ghostgetStateHome, snapshotPrivateStateDirectory } from "../storage";
+import type { AgentApprovalResponse, ApprovalTarget } from "./protocol";
+import { ControlError, digest, identifier, keys, oneOf, record } from "./validation";
+import type { ControlEnvironment } from "./web-policy";
+
+export interface ApprovalLease {readonly id:string;readonly digest:string}
+export function controlSocketPath(environment:ControlEnvironment=process.env):string {return join(ghostgetStateHome(environment),"control","agent.sock");}
+export async function agentRequest(payload:unknown,options:{environment:ControlEnvironment;signal?:AbortSignal;timeoutMs?:number}):Promise<unknown> {
+  const path=controlSocketPath(options.environment);
+  const data=Buffer.from(`${JSON.stringify(payload)}\n`);if(data.length>262144) throw new ControlError("REQUEST_TOO_LARGE","The agent request is too large.");
+  try {
+    snapshotPrivateStateDirectory(join(ghostgetStateHome(options.environment),"control"),options.environment);
+    const stat=lstatSync(path);if(!stat.isSocket()||stat.uid!==process.getuid?.()||(stat.mode&0o777)!==0o600) throw new Error();
+  } catch {throw new ControlError("CONTROL_APP_REQUIRED","Open the Ghostget app to use the gateway or request human approval.");}
+  return await new Promise((resolve,reject)=>{
+    const socket=connect({path});let received=Buffer.alloc(0);let settled=false;
+    const finish=(error:unknown,value?:unknown)=>{if(settled)return;settled=true;clearTimeout(timer);options.signal?.removeEventListener("abort",abort);socket.destroy();if(error)reject(error);else resolve(value);};
+    const abort=()=>finish(new ControlError("REQUEST_CANCELLED","The request was cancelled."));
+    const timer=setTimeout(()=>finish(new ControlError("CONTROL_TIMEOUT","The app did not respond before the request deadline.")),options.timeoutMs??5000);
+    options.signal?.addEventListener("abort",abort,{once:true});if(options.signal?.aborted){abort();return;}
+    socket.once("connect",()=>socket.write(data));
+    socket.on("data",chunk=>{received=Buffer.concat([received,typeof chunk === "string" ? Buffer.from(chunk) : chunk]);if(received.length>4_194_304){finish(new ControlError("INVALID_RESPONSE","The app response exceeded its limit."));return;}const end=received.indexOf(10);if(end<0)return;try{if(received.subarray(end+1).length)throw new Error();finish(null,JSON.parse(received.subarray(0,end).toString("utf8")));}catch{finish(new ControlError("INVALID_RESPONSE","The app response was invalid."));}});
+    socket.once("error",()=>finish(new ControlError("CONTROL_DISCONNECTED","The Ghostget app disconnected.")));
+    socket.once("end",()=>finish(new ControlError("CONTROL_DISCONNECTED","The Ghostget app disconnected.")));
+  });
+}
+function response(value:unknown,lease:ApprovalLease):AgentApprovalResponse {
+  const v=record(value);keys(v,["protocol","status","id","digest"]);
+  if(v.protocol!=="ghostget.approval/1"||v.id!==lease.id||v.digest!==lease.digest) throw new ControlError("INVALID_RESPONSE","The approval response did not match this request.");
+  return {protocol:"ghostget.approval/1",id:identifier(v.id),digest:digest(v.digest),status:oneOf(v.status,["pending","allowed","denied","expired","cancelled","invalid"])};
+}
+export async function requestApproval(target:ApprovalTarget,expectedDigest:string,options:{environment:ControlEnvironment;signal?:AbortSignal}):Promise<ApprovalLease> {
+  const lease={id:randomUUID(),digest:expectedDigest};
+  try {
+    let current=response(await agentRequest({protocol:"ghostget.approval/1",action:"request",id:lease.id,target,expectedDigest},options),lease);
+    const deadline=Date.now()+120_000;
+    while(current.status==="pending"&&Date.now()<deadline){await new Promise<void>((resolve,reject)=>{const timer=setTimeout(()=>{options.signal?.removeEventListener("abort",abort);resolve();},400);const abort=()=>{clearTimeout(timer);reject(new ControlError("REQUEST_CANCELLED","The request was cancelled."));};if(options.signal?.aborted){abort();return;}options.signal?.addEventListener("abort",abort,{once:true});});current=response(await agentRequest({protocol:"ghostget.approval/1",action:"check",...lease},options),lease);}
+    if(current.status!=="allowed") throw new ControlError("APPROVAL_REQUIRED","This operation was not approved. Review it in Ghostget and retry explicitly.");
+    return lease;
+  } catch(error) {await releaseApproval(lease,options).catch(()=>undefined);throw error;}
+}
+export async function checkApproval(lease:ApprovalLease,options:{environment:ControlEnvironment;signal?:AbortSignal}):Promise<void> {
+  if(response(await agentRequest({protocol:"ghostget.approval/1",action:"check",...lease},options),lease).status!=="allowed") throw new ControlError("APPROVAL_EXPIRED","The exact approval is no longer valid.");
+}
+export async function releaseApproval(lease:ApprovalLease,options:{environment:ControlEnvironment}):Promise<void> {await agentRequest({protocol:"ghostget.approval/1",action:"cancel",...lease},options);}

package/src/control/bundled-interfaces.ts

@@ -0,0 +1,20 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { manifestHash, parseRuntimeManifest } from "../model";
+import type { ProviderPluginRegistry } from "../provider-plugin-registry";
+
+/** Display provenance comes from exact current bundled bytes, never absence of a receipt. */
+export function bundledInterfaceDigests(registry:ProviderPluginRegistry):ReadonlyMap<string,string> {
+  const directory=fileURLToPath(new URL("../assets/adapters/",import.meta.url));const result=new Map<string,string>();
+  for(const folder of readdirSync(directory,{withFileTypes:true})) {
+    if(!folder.isDirectory()||! /^[a-z0-9-]+$/u.test(folder.name))continue;
+    for(const filename of ["wrench-adapter.json","wrench-web-adapter.json"]) {
+      let text:string;try{text=readFileSync(join(directory,folder.name,filename),"utf8");}catch(error){if((error as NodeJS.ErrnoException).code==="ENOENT")continue;throw error;}
+      const parsed=parseRuntimeManifest(JSON.parse(text) as unknown,registry);
+      if(!parsed.ok)continue;
+      result.set(parsed.value.id,manifestHash(parsed.value));
+    }
+  }
+  return result;
+}

package/src/control/cli.ts

@@ -0,0 +1,20 @@
+import { agentRequest } from "./approval-client";
+import { ControlError, integer, keys, oneOf, record, string } from "./validation";
+import type { ControlEnvironment } from "./web-policy";
+
+export async function runWebCommand(args:readonly string[],environment:ControlEnvironment,output:{stdout:(text:string)=>unknown;stderr:(text:string)=>unknown},signal?:AbortSignal):Promise<number> {
+  try {
+    if(args.length===1||args[1]==="--help"){output.stdout("Usage: ghostget web request <https-url> [--method GET|HEAD]\nConfigure rules and approvals in the Ghostget native app. Responses are untrusted text.\n");return 0;}
+    if(args[1]!=="request"||(args.length!==3&&args.length!==5)||args.length===5&&args[3]!=="--method")throw new ControlError("INVALID_REQUEST","Use ghostget web request <https-url> [--method GET|HEAD].");
+    const method=args.length===5?oneOf(args[4],["GET","HEAD"] as const):"GET";
+    const v=record(await agentRequest({protocol:"ghostget.web/1",action:"request",method,url:string(args[2],8192)},{environment,...(signal===undefined?{}:{signal}),timeoutMs:185_000}));
+    if(v.ok===false){keys(v,["ok","code","message"]);throw new ControlError(string(v.code,64),string(v.message,1024));}
+    keys(v,["protocol","ok","id","status","contentType","bodyBase64","bytes","trusted"]);
+    if(v.protocol!=="ghostget.web/1"||v.ok!==true||v.trusted!==false)throw new Error("invalid gateway response");
+    const bytes=integer(v.bytes,0,2_000_000);const encoded=string(v.bodyBase64,2_666_668,0);const body=Buffer.from(encoded,"base64");if(body.length!==bytes||body.toString("base64")!==encoded)throw new Error("invalid body");
+    const text=new TextDecoder("utf-8",{fatal:true}).decode(body);
+    output.stdout(`${JSON.stringify({id:string(v.id,128),status:integer(v.status,200,599),contentType:string(v.contentType,128),bytes,trusted:false,body:text})}\n`);return 0;
+  } catch(error) {
+    const failure=error instanceof ControlError?{ok:false,code:error.code,message:error.message}:{ok:false,code:"WEB_REQUEST_FAILED",message:"The gateway response was unavailable or invalid."};output.stderr(`${JSON.stringify(failure)}\n`);return 1;
+  }
+}

package/src/control/connections.ts

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createAuth, loadAuthSnapshotIfPresent, removeAuth, replaceAuthIfUnchanged, saveAuth, type AuthSnapshot, type GhostgetAuth } from "../auth";
+import type { ProviderPluginRegistry } from "../provider-plugin-registry";
+import { withReadProjectionAuthAdmission } from "../read-projections";
+import { installManifest, loadInstalledManifestSnapshot } from "../storage";
+import { parseRuntimeManifest } from "../model";
+import { connectionAccountRevision } from "./account-revision";
+import type { ControlData, ControlRequest } from "./protocol";
+import { ControlError } from "./validation";
+import type { ControlEnvironment } from "./web-policy";
+
+const PROVIDERS=[{id:"x-web",surface:"x",title:"X · browser session",login:"https://x.com/i/flow/login"},{id:"linkedin-web",surface:"linkedin",title:"LinkedIn · browser session",login:"https://www.linkedin.com/login"},{id:"reddit-web",surface:"reddit",title:"Reddit · browser session",login:"https://www.reddit.com/login/"}] as const;
+type Begin=Extract<ControlRequest,{action:"connection.begin"}>;
+type Attempt={readonly id:string;readonly request:Begin;readonly current:AuthSnapshot|null;readonly expiresAt:number;readonly controller:AbortController;auth:GhostgetAuth;subject:string|null;verifying:boolean};
+export const connectionProviders=PROVIDERS.map(({id,title})=>({id,title}));
+export class Connections {
+  private readonly attempts=new Map<string,Attempt>();
+  constructor(private readonly environment:ControlEnvironment,private readonly registry:()=>ProviderPluginRegistry,private readonly open:(browser:"chrome"|"safari",profile:string|null,url:string)=>Promise<void>=openBrowser,private readonly now:()=>number=()=>performance.now()) {}
+  private sweep():void {for(const [id,a] of this.attempts)if(this.now()>=a.expiresAt){a.controller.abort();this.attempts.delete(id);}}
+  async begin(request:Begin):Promise<ControlData> {
+    this.sweep();if(this.attempts.size>=8)throw new ControlError("CONNECTION_LIMIT","Finish or cancel an existing connection first.");
+    const provider=PROVIDERS.find(item=>item.id===request.provider);if(provider===undefined)throw new ControlError("CONNECTION_UNSUPPORTED","Use the provider's agent instructions to connect this account.");
+    if(request.profile!==null && (request.browser!=="chrome" || !/^(?:Default|Profile [1-9][0-9]{0,2})$/u.test(request.profile)))throw new ControlError("PROFILE_UNSUPPORTED","Choose Default or a numbered Chrome profile.");
+    const current=loadAuthSnapshotIfPresent(request.id,this.environment);
+    if((current===null?null:connectionAccountRevision(current,this.environment))!==request.expectedRevision)throw new ControlError("ACCOUNT_CHANGED","The account changed. Refresh before reconnecting.");
+    const auth=createAuth(request.id,{source:request.browser,...(request.profile===null?{}:{profile:request.profile})});
+    const binding=this.registry().requireSessionRoute(provider.surface);
+    if(!binding.authKinds.includes(auth.kind)||binding.subject.probe===undefined)throw new ControlError("CONNECTION_UNSUPPORTED","This provider has no compatible sign-in verifier.");
+    const id=randomUUID();const attempt:Attempt={id,request,current,auth,subject:null,expiresAt:this.now()+600_000,controller:new AbortController(),verifying:false};
+    this.attempts.set(id,attempt);
+    try {await this.open(request.browser,request.profile,provider.login);}catch{this.attempts.delete(id);throw new ControlError("BROWSER_UNAVAILABLE","The selected browser could not be opened.");}
+    return {kind:"connection",attemptId:id,status:"awaiting-sign-in",subject:null};
+  }
+  async verify(id:string):Promise<ControlData> {
+    const attempt=this.get(id);if(attempt.verifying)throw new ControlError("CONNECTION_BUSY","Verification is already running.");
+    // A failed re-verification cannot leave an older successful proof available to commit.
+    attempt.subject=null;
+    const {subject:_previousSubject,...unverifiedAuth}=attempt.auth;attempt.auth=unverifiedAuth;
+    attempt.verifying=true;const timer=setTimeout(()=>attempt.controller.abort(),60_000);
+    try {
+      const provider=PROVIDERS.find(item=>item.id===attempt.request.provider)!;const binding=this.registry().requireSessionRoute(provider.surface);
+      const subject=await binding.subject.probe!(attempt.auth,{environment:this.environment,signal:attempt.controller.signal});
+      if(this.get(id)!==attempt||attempt.controller.signal.aborted||!binding.subject.matches(subject))throw new Error();
+      attempt.subject=subject;attempt.auth={...attempt.auth,subject};
+      return {kind:"connection",attemptId:id,status:"verified",subject};
+    } catch {this.cancel(id);throw new ControlError("SIGN_IN_UNVERIFIED","Sign-in could not be verified. Complete it in the selected browser and profile, then start a fresh connection.");}
+    finally {clearTimeout(timer);attempt.verifying=false;}
+  }
+  commit(id:string,subject:string):void {
+    const attempt=this.get(id);if(attempt.verifying||attempt.subject===null||attempt.subject!==subject||attempt.controller.signal.aborted)throw new ControlError("SIGN_IN_UNVERIFIED","Verify the exact account before connecting it.");
+    withReadProjectionAuthAdmission(attempt.request.id,this.environment,()=>{
+      const current=loadAuthSnapshotIfPresent(attempt.request.id,this.environment);
+      if((current===null?null:connectionAccountRevision(current,this.environment))!==attempt.request.expectedRevision)throw new ControlError("ACCOUNT_CHANGED","The account changed while sign-in was open. Start again.");
+      this.installBundledAdapter(attempt.request.provider);
+      if(attempt.current===null)saveAuth(attempt.auth,this.environment);
+      else if(!replaceAuthIfUnchanged(attempt.current,attempt.auth,this.environment).replaced)throw new ControlError("ACCOUNT_CHANGED","The account changed while sign-in was open. Start again.");
+    });
+    this.cancel(id);
+  }
+  disconnect(id:string,expectedRevision:string):void {
+    withReadProjectionAuthAdmission(id,this.environment,()=>{
+      const current=loadAuthSnapshotIfPresent(id,this.environment);if(current===null||connectionAccountRevision(current,this.environment)!==expectedRevision)throw new ControlError("ACCOUNT_CHANGED","The account changed. Refresh before disconnecting.");
+      removeAuth(id,this.environment);
+    });
+  }
+  cancel(id:string):void {const attempt=this.attempts.get(id);attempt?.controller.abort();this.attempts.delete(id);}
+  private get(id:string):Attempt {this.sweep();const attempt=this.attempts.get(id);if(attempt===undefined)throw new ControlError("CONNECTION_EXPIRED","This sign-in attempt expired. Start again.");return attempt;}
+  close():void {for(const id of this.attempts.keys())this.cancel(id);}
+  private installBundledAdapter(providerId:string):void {
+    const provider=PROVIDERS.find(item=>item.id===providerId)!;
+    const registry=this.registry();
+    if(registry.resolveOwnedManifest(provider.id)!==undefined)return;
+    const current=loadInstalledManifestSnapshot(provider.id,this.environment,registry);
+    if(current.availability==="present"&&current.result.ok)return;
+    if(current.availability!=="absent")throw new ControlError("ADAPTER_UNAVAILABLE","The existing adapter is invalid. Repair it before connecting; Ghostget will not overwrite it.");
+    const parsed=parseRuntimeManifest(JSON.parse(readFileSync(new URL(`../assets/adapters/${provider.surface}/wrench-web-adapter.json`,import.meta.url),"utf8")) as unknown,registry);
+    if(!parsed.ok||parsed.value.id!==provider.id)throw new ControlError("ADAPTER_UNAVAILABLE","The bundled provider interface is unavailable or invalid.");
+    installManifest(parsed.value,{force:false,environment:this.environment,registry});
+  }
+}
+async function openBrowser(browser:"chrome"|"safari",profile:string|null,url:string):Promise<void> {
+  if(process.platform!=="darwin")throw new Error("macOS required");
+  const args=browser==="safari"?["/usr/bin/open","-a","Safari",url]:profile===null?["/usr/bin/open","-a","Google Chrome",url]:["/usr/bin/open","-a","Google Chrome","--args",`--profile-directory=${profile}`,url];
+  const child=Bun.spawn(args,{stdin:"ignore",stdout:"ignore",stderr:"ignore",env:{PATH:"/usr/bin:/bin",HOME:process.env.HOME??""}});
+  const timer=setTimeout(()=>child.kill(),5000);try{if(await child.exited!==0)throw new Error("browser launch failed");}finally{clearTimeout(timer);}
+}