@hraness/ghostget 0.17.6 → 0.18.2

package/src/read-client.ts

@@ -1,4 +1,5 @@
 import { canonicalJson, sha256 } from "./canonical-json";
+import { assertOperationPermission, withOperationPermission } from "./operation-permission";
 import { loadAuthSnapshotIfPresent } from "./auth";
 import {
   createPortableProviderPluginCatalog,
@@ -239,8 +240,9 @@ export function readCachedPreparedCapability(
   options: ReadCapabilityOptions & { readonly registry: ProviderPluginRegistry },
 ): ReadProjectionCacheResult {
   const environment = options.environment ?? process.env;
+  assertOperationPermission(invocation, { environment, registry: options.registry });
   validateReadOptions(options);
-  return withInvocationAuthorityAdmission(
+  const result = withInvocationAuthorityAdmission(
     invocation,
     environment,
     () => {
@@ -265,6 +267,8 @@ export function readCachedPreparedCapability(
       return cached;
     },
   );
+  assertOperationPermission(invocation, { environment, registry: options.registry });
+  return result;
 }
 
 export function readCachedCapability(
@@ -279,7 +283,7 @@ export function readCachedCapability(
   );
 }
 
-export async function revalidatePreparedCapability(
+async function revalidatePreparedCapabilityCore(
   invocation: PreparedInvocation,
   options: PreparedReadOptions,
   cachedBeforeOverride?: ReadProjectionCacheResult | null,
@@ -467,6 +471,12 @@ export async function revalidatePreparedCapability(
   }
 }
 
+export async function revalidatePreparedCapability(invocation: PreparedInvocation, options: PreparedReadOptions, cachedBeforeOverride?: ReadProjectionCacheResult | null): Promise<RevalidatedCapability> {
+  const environment = options.environment ?? process.env;
+  return withOperationPermission(invocation, { environment, registry: options.registry, ...(options.signal === undefined ? {} : { signal: options.signal }) },
+    () => revalidatePreparedCapabilityCore(invocation, options, cachedBeforeOverride));
+}
+
 export async function revalidateCapability(
   request: CapabilityReadRequest,
   options: RevalidateCapabilityOptions = {},

package/src/runtime.ts

@@ -1,4 +1,6 @@
 import * as Effect from "effect/Effect";
+import { assertOperationPreparationPermission, checkOperationPermission, withOperationPermission, withUnmanagedOperationPermission, readOperationPolicy } from "./operation-permission";
+import type { ApprovalTarget } from "./control/protocol";
 import { ConfirmedWritePlatform, makeConfirmedWritePlatform } from "./confirmed-write-platform";
 import { confirmedWriteProgram } from "./confirmed-write-program";
 import { runConfirmedWrite } from "./confirmed-write-runtime";
@@ -186,6 +188,7 @@ type InvocationPlanCommon = {
     readonly id: string;
     readonly hash: string;
     readonly kind: GhostgetAuth["kind"];
+    readonly incarnationHash?: string;
   };
   readonly duplicateRisk?: InvocationDuplicateRiskV1;
   readonly messagingComposite?: MessagingCompositeInvocationPlanV1;
@@ -1231,6 +1234,7 @@ export function prepareInvocation(
   authId?: string,
   environment: Readonly<Record<string, string | undefined>> = process.env,
   registry: ProviderPluginRegistry = providerPluginRegistry,
+  permissionMode: "enforce" | "inspect" = "enforce",
 ): PreparedInvocation {
   const manifestResult = loadInstalledManifestWithRegistry(adapterId, environment, registry);
   if (!manifestResult.ok) throw new Error(`adapter ${adapterId} is invalid: ${manifestResult.issues.join("; ")}`);
@@ -1257,7 +1261,7 @@ export function prepareInvocation(
       );
     }
     const authority = authenticationPolicy.authority;
-    return revalidatePreparedInvocation({
+    const invocation = revalidatePreparedInvocation({
       manifest: manifestResult.value,
       operationId,
       input: platformInput.value,
@@ -1265,6 +1269,8 @@ export function prepareInvocation(
       readProjectionAuthIdentityHash:
         publicWebSessionAuthorityIdentityHash(authority),
     }, registry).invocation;
+    if (permissionMode === "enforce") assertOperationPreparationPermission(invocation, { environment, registry });
+    return invocation;
   }
   const selectedAuthId = authId ?? adapterId;
   const preparedAuth = withSettledReadProjectionAuthAdmission(
@@ -1282,7 +1288,7 @@ export function prepareInvocation(
       });
     },
   );
-  return revalidatePreparedInvocation({
+  const invocation = revalidatePreparedInvocation({
     manifest: manifestResult.value,
     operationId,
     input: platformInput.value,
@@ -1290,6 +1296,8 @@ export function prepareInvocation(
     readProjectionAuthIdentityHash:
       preparedAuth.readProjectionAuthIdentityHash,
   }, registry).invocation;
+  if (permissionMode === "enforce") assertOperationPreparationPermission(invocation, { environment, registry });
+  return invocation;
 }
 
 /**
@@ -1448,6 +1456,7 @@ export function createInvocationPlan(
       id: planAuth.id,
       hash: authHash(planAuth),
       kind: planAuth.kind,
+      ...(invocation.readProjectionAuthIdentityHash === undefined ? {} : { incarnationHash: invocation.readProjectionAuthIdentityHash }),
     },
   };
   const portablePluginContract = pluginResolution?.portableIdentity ?? null;
@@ -1678,6 +1687,12 @@ function planRunJournalContract(plan: InvocationPlan): RunJournal["contract"] {
     : { transport: contract.transport, hash: contract.hash };
 }
 
+/** Recovery v1 records the durable account selection. The full lifetime binding
+ * remains in the successor scope hash and is revalidated before confirmation. */
+function planRecoveryAuth(plan: InvocationPlan): RunJournal["auth"] {
+  return { id: plan.auth.id, hash: plan.auth.hash, kind: plan.auth.kind };
+}
+
 function planFileInputs(input: OperationInput): readonly FileInputValue[] {
   const files: FileInputValue[] = [];
   for (const value of Object.values(input)) {
@@ -1753,7 +1768,7 @@ function resolveInvocationDuplicateRisk(
     || journal.operation !== plan.operation
     || journal.risk !== plan.risk
     || journal.inputHash !== plan.inputHash
-    || canonicalJson(journal.auth) !== canonicalJson(plan.auth)
+    || canonicalJson(journal.auth) !== canonicalJson(planRecoveryAuth(plan))
     || canonicalJson(journal.contract)
       !== canonicalJson(planRunJournalContract(plan))
   ) {
@@ -1786,7 +1801,7 @@ function resolveInvocationDuplicateRisk(
     || capsule.risk !== plan.risk
     || capsule.inputHash !== plan.inputHash
     || canonicalJson(capsule.input) !== canonicalJson(plan.input)
-    || canonicalJson(capsule.auth) !== canonicalJson(plan.auth)
+    || canonicalJson(capsule.auth) !== canonicalJson(planRecoveryAuth(plan))
     || canonicalJson(capsule.contract) !== canonicalJson(planRecoveryContract(plan))
   ) {
     throw new Error(
@@ -2433,7 +2448,8 @@ function parseStoredPlan(value: unknown): StoredPlan {
   ) throw new Error("stored plan adapter is malformed");
   const auth = raw.auth;
   if (
-    !hasExactKeys(auth, ["id", "hash", "kind"])
+    !hasExactKeys(auth, ["id", "hash", "kind", ...(Object.hasOwn(auth, "incarnationHash") ? ["incarnationHash"] : [])])
+    || (Object.hasOwn(auth, "incarnationHash") && (typeof auth.incarnationHash !== "string" || !/^[a-f0-9]{64}$/u.test(auth.incarnationHash)))
     || typeof auth.id !== "string"
     || !/^[a-z][a-z0-9-]{0,47}$/u.test(auth.id)
     || typeof auth.hash !== "string"
@@ -2550,7 +2566,7 @@ function parseStoredPlan(value: unknown): StoredPlan {
     input,
     inputHash,
     dispatches,
-    auth: { id: auth.id, hash: auth.hash, kind: auth.kind },
+    auth: { id: auth.id, hash: auth.hash, kind: auth.kind, ...(typeof auth.incarnationHash === "string" ? { incarnationHash: auth.incarnationHash } : {}) },
     ...(Object.hasOwn(raw, "duplicateRisk")
       ? { duplicateRisk: parseInvocationDuplicateRisk(raw.duplicateRisk) }
       : {}),
@@ -2977,14 +2993,41 @@ function validateFreshPlan(
   } else if (auth.kind === "oauth-token-file") {
     throw new Error("browser authentication changed after preview; preview the action again");
   }
+  const incarnation = withSettledReadProjectionAuthAdmission(auth.id, environment, () => {
+    const current = loadAuth(auth.id, environment);
+    if (authHash(current) !== authHash(auth)) throw new Error("authentication changed during confirmation preparation");
+    return projectionAuthIdentityHash(auth.id, authHash(auth), environment);
+  });
+  if ((plan.auth.incarnationHash !== undefined && plan.auth.incarnationHash !== incarnation)
+    || (plan.auth.incarnationHash === undefined && readOperationPolicy(environment).managed)) {
+    throw new Error("authentication lifetime changed or predates managed permissions; preview the action again");
+  }
   return revalidatePreparedInvocation({
     manifest,
     operationId: plan.operation,
     input: platformInput.value,
     auth,
+    readProjectionAuthIdentityHash: incarnation,
   }, registry).invocation;
 }
 
+/** Trusted control-plane inspection. This only prepares; execution gates remain mandatory. */
+export function prepareOperationApprovalInvocation(
+  target: Extract<ApprovalTarget, { readonly kind: "provider" }>,
+  options: { readonly environment: Readonly<Record<string, string | undefined>>; readonly registry: ProviderPluginRegistry },
+): { readonly invocation: PreparedInvocation; readonly stored: StoredPlan | null } {
+  if (target.planDigest === null) return {
+    invocation: prepareInvocation(target.adapterId, target.operationId, target.input, target.authId ?? undefined, options.environment, options.registry, "inspect"), stored: null,
+  };
+  const stored = loadInvocationPlan(target.planDigest, options.environment);
+  if (stored.plan.adapter.id !== target.adapterId || stored.plan.operation !== target.operationId || stored.plan.auth.id !== target.authId) {
+    throw new Error("approval target does not match its exact saved plan");
+  }
+  const invocation = validateFreshPlan(stored, options.environment, new Date(), options.registry,
+    (id, environment = options.environment) => loadInstalledManifestWithRegistry(id, environment, options.registry));
+  return { invocation, stored };
+}
+
 
 
 
@@ -4381,6 +4424,7 @@ async function runPreparedReadCore(invocation: PreparedInvocation, planDigest: s
 
     },
     execute: async () => {
+      await checkOperationPermission(invocation, { environment: options.environment, registry, ...(options.signal === undefined ? {} : { signal: options.signal }) });
       if (options.preflightFailure !== undefined) throw options.preflightFailure;
     return providerOperation
       ? await (options.executeProvider ?? executeProviderOperation)(
@@ -4524,7 +4568,7 @@ async function runPreparedReadCore(invocation: PreparedInvocation, planDigest: s
 
 
 
-async function runPrepared(
+async function runPreparedCore(
   invocation: PreparedInvocation,
   planDigest: string | null,
   options: RunPreparedOptions,
@@ -4593,6 +4637,12 @@ async function runPrepared(
   );
 }
 
+async function runPrepared(invocation: PreparedInvocation, planDigest: string | null, options: RunPreparedOptions): Promise<InvocationResult> {
+  if (!readOperationPolicy(options.environment).managed) return withUnmanagedOperationPermission(options.environment, () => runPreparedCore(invocation, planDigest, options));
+  return withOperationPermission(invocation, { environment: options.environment, registry: options.registry ?? providerPluginRegistry,
+    ...(options.signal === undefined ? {} : { signal: options.signal }) }, () => runPreparedCore(invocation, planDigest, options));
+}
+
 export async function executeReadInvocation(
   invocation: PreparedInvocation,
   options: {
@@ -4628,7 +4678,7 @@ export async function executeReadInvocation(
   });
 }
 
-export async function confirmInvocation(
+async function confirmInvocationCore(
   digest: string,
   options: {
     readonly headed: boolean;
@@ -4681,6 +4731,17 @@ export async function confirmInvocation(
   }, options))));
 }
 
+export async function confirmInvocation(digest: string, options: Parameters<typeof confirmInvocationCore>[1]): Promise<InvocationResult> {
+  const environment = options.environment ?? process.env;
+  if (!readOperationPolicy(environment).managed) return withUnmanagedOperationPermission(environment, () => confirmInvocationCore(digest, options));
+  const registry = options.registry ?? providerPluginRegistry;
+  const stored = loadInvocationPlan(digest, environment);
+  const invocation = validateFreshPlan(stored, environment, options.now ?? new Date(), registry,
+    options.loadManifest ?? ((id, selected = environment) => loadInstalledManifestWithRegistry(id, selected, registry)));
+  return withOperationPermission(invocation, { environment, registry, plan: stored, ...(options.signal === undefined ? {} : { signal: options.signal }) },
+    () => confirmInvocationCore(digest, options));
+}
+
 export type MessagingConfirmationResult = {
   readonly run: MessagingRunV1;
   readonly receipt: MessagingRunReceipt;
@@ -4728,7 +4789,7 @@ function terminalizeMessagingRecovery(
 }
 
 /** Confirm one composite messaging preview under one durable ownership claim. */
-export async function confirmMessagingInvocation(
+async function confirmMessagingInvocationCore(
   digest: string,
   options: {
     readonly environment?: Readonly<Record<string, string | undefined>>;
@@ -4857,6 +4918,17 @@ export async function confirmMessagingInvocation(
   }
 }
 
+export async function confirmMessagingInvocation(digest: string, options: NonNullable<Parameters<typeof confirmMessagingInvocationCore>[1]> = {}): Promise<MessagingConfirmationResult> {
+  const environment = options.environment ?? process.env;
+  if (!readOperationPolicy(environment).managed) return withUnmanagedOperationPermission(environment, () => confirmMessagingInvocationCore(digest, options));
+  const registry = options.registry ?? providerPluginRegistry;
+  const stored = loadInvocationPlan(digest, environment);
+  const invocation = validateFreshPlan(stored, environment, options.now ?? new Date(), registry,
+    options.loadManifest ?? ((id, selected = environment) => loadInstalledManifestWithRegistry(id, selected, registry)));
+  return withOperationPermission(invocation, { environment, registry, plan: stored, ...(options.signal === undefined ? {} : { signal: options.signal }) },
+    () => confirmMessagingInvocationCore(digest, options));
+}
+
 export function readRunReceipt(
   runId: string,
   environment: Readonly<Record<string, string | undefined>> = process.env,

package/src/state-helper.ts

@@ -41,11 +41,13 @@ const stateDirectories = new Set([
   "auth",
   "browser-snapshots",
   "captures",
+  "control",
   "derivations",
   "idempotency",
   "linked-device-stores",
   "messaging",
   "omni-read-projections",
+  "operation-permissions",
   "plan-assets",
   "plans",
   "provider-plugin-state",

package/src/storage.ts

@@ -101,11 +101,13 @@ const stateDirectoryNames = [
   "auth",
   "browser-snapshots",
   "captures",
+  "control",
   "derivations",
   "idempotency",
   "linked-device-stores",
   "messaging",
   "omni-read-projections",
+  "operation-permissions",
   "plan-assets",
   "plans",
   "provider-plugin-state",
@@ -1158,7 +1160,7 @@ function validateStateRoot(root: string): StateRootRecord {
   return { claimed, creationAnchor: null, identity: { device: stats.dev.toString(), inode: stats.ino.toString() } };
 }
 
-export function ghostgetStateHome(environment: Readonly<Record<string, string | undefined>> = process.env): string {
+function selectStateHome(environment: Readonly<Record<string, string | undefined>>): string {
   const configuredRoots = [
     ["GHOSTGET_STATE_HOME", environment.GHOSTGET_STATE_HOME],
     ["WRENCH_STATE_HOME", environment.WRENCH_STATE_HOME],
@@ -1215,6 +1217,74 @@ export function ghostgetStateHome(environment: Readonly<Record<string, string |
   if (forbiddenRoots.has(root) || isWithinPath(ghostgetSourcePackageRoot, root)) {
     throw new Error(`GHOSTGET_STATE_HOME must be a dedicated child directory, not a filesystem, home, temporary, repository, or shared data root: ${root}`);
   }
+  return root;
+}
+
+/**
+ * Inspect only whether an optional policy may exist, without adopting a state
+ * root. CLI validation and local file inputs must not claim or register state.
+ * A present file still requires the ordinary inode-bound private state reader.
+ */
+export function privateStateFilesMayExist(
+  collection: typeof stateDirectoryNames[number],
+  fileNames: readonly string[],
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  if (!stateDirectoryNames.includes(collection) || fileNames.length < 1 || fileNames.length > 8
+    || fileNames.some(name => !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u.test(name))) {
+    throw new Error("optional private state file selection is invalid");
+  }
+  const root = selectStateHome(environment);
+  const inspect = (path: string): BigIntStats | null => {
+    try { return lstatSync(path, { bigint: true }); }
+    catch (error) { if (hasCode(error, "ENOENT")) return null; throw error; }
+  };
+  const inspectDirectory = (path: string): BigIntStats | null => {
+    const stats = inspect(path);
+    if (stats !== null && (!stats.isDirectory() || stats.isSymbolicLink()
+      || !ownedByCurrentUser(stats) || (stats.mode & 0o777n) !== 0o700n)) {
+      throw new Error("optional private state directory is unsafe");
+    }
+    return stats;
+  };
+  const assertUnchanged = (path: string, before: BigIntStats | null): void => {
+    const after = inspect(path);
+    if (before === null ? after !== null : after === null
+      || before.dev !== after.dev || before.ino !== after.ino
+      || before.mode !== after.mode || before.uid !== after.uid
+      || before.ctimeNs !== after.ctimeNs || before.mtimeNs !== after.mtimeNs) {
+      throw new Error("optional private state changed during inspection");
+    }
+  };
+  if (knownStateRoots.has(root)) assertStateRootIdentity(root);
+  const rootBefore = inspectDirectory(root);
+  // A missing root is observed from its existing, owned creation anchor; no
+  // directory, mode, marker, or process-local state registration is changed.
+  const anchor = rootBefore === null ? findCreationAnchor(root).path : null;
+  const anchorBefore = anchor === null ? null : inspect(anchor);
+  const markerPath = join(root, stateMarkerName);
+  const markerBefore = inspect(markerPath);
+  if (markerBefore !== null) readStateMarker(markerPath);
+  else if (rootBefore !== null && !hasGhostgetPathIdentity(root)) {
+    throw new Error("optional private state root does not identify dedicated Ghostget state");
+  }
+  const directory = join(root, collection);
+  const directoryBefore = inspectDirectory(directory);
+  let present = false;
+  for (const name of fileNames) {
+    if (inspect(join(directory, name)) !== null) present = true;
+  }
+  if (selectStateHome(environment) !== root) throw new Error("optional private state root selection changed");
+  assertUnchanged(directory, directoryBefore);
+  assertUnchanged(markerPath, markerBefore);
+  assertUnchanged(root, rootBefore);
+  if (anchor !== null) assertUnchanged(anchor, anchorBefore);
+  if (knownStateRoots.has(root)) assertStateRootIdentity(root);
+  return present;
+}
+
+export function ghostgetStateHome(environment: Readonly<Record<string, string | undefined>> = process.env): string {
+  const root = selectStateHome(environment);
   const inspected = validateStateRoot(root);
   const remembered = knownStateRoots.get(root);
   if (remembered !== undefined) {

package/src/usage.ts

@@ -30,7 +30,14 @@ export const ghostgetUsage = `Usage:
   ghostget transcriber setup --engine whisper-cpp --model <file> [media-options]
   ghostget doctor [--json]                         Check capture, media, auth, and action dependencies
   ghostget capabilities [adapter] [--json]         List installed semantic capabilities
-  ghostget imessage transport install --binary <absolute-reviewed-imsg-file> [--json]
+  ghostget web request <https-url> [--method GET|HEAD]
+                                                 Retrieve public text through native web rules and approvals
+  ghostget interface list                          List user and imported OpenAPI drafts
+  ghostget interface export [adapter]              Export installed semantic interfaces as OpenAPI
+  ghostget interface import <openapi.json> [--expected-digest <sha256>]
+                                                 Save an inert draft; review and activate it in the native app
+  ghostget whatsapp automation install [--binary <absolute-reviewed-wacli-file>] [--json]
+  ghostget imessage transport install [--binary <absolute-reviewed-imsg-file>] [--json]
                                                  Install only the current reviewed iMessage transport bytes
   ghostget plugin list [--json]                    List trusted source and installed portable plugins
   ghostget plugin show <id> [--json]               Inspect one source or portable plugin
@@ -94,6 +101,7 @@ export const ghostgetUsage = `Usage:
                   --output <new-absolute-directory> [--json]
                   # local wacli.db bundle only; no send, pairing, or cloud sync
 
+  ghostget messaging automation serve --stdio
   ghostget messaging routes --input <-|@absolute-private-file>
                           --private-output <absolute-mode-0600-file> [--json]
   ghostget messaging resolve --input <-|@absolute-private-file>

package/src/version.ts

@@ -1,2 +1,2 @@
 /** Canonical immutable Ghostget package release identity. */
-export const GHOSTGET_VERSION = "0.17.6" as const;
+export const GHOSTGET_VERSION = "0.18.2" as const;

package/src/web-session-contract-definitions.ts

@@ -577,7 +577,7 @@ const linkedin = {
     "contacts.read",
     LINKEDIN_WEB_OPERATIONS["contacts.read"].risk,
     LINKEDIN_WEB_OPERATIONS["contacts.read"].state,
-    "reviewed contained-Chrome 1st-degree Contact-info read: bind the signed-in viewer, require a 1st-degree relationship on the requested vanity from classic Profile embeds or Como rehydration, then project page-embedded Contact-info fields or GET voyagerIdentityDashProfileContactInfo and project email plus any shown profile link, connected-since date, phones, websites, or birthday",
+    "reviewed contained-Chrome 1st-degree Contact-info read: bind the signed-in viewer, require 1st-degree from Profile embeds or Como, project embedded Contact-info fields while skipping non-bounded SDUI labels, or click the unique Contact info control on the opened profile and project that modal; keep synthetic navigation POST and navigation GETs rejected, treat an HTML-200 shell that omits Email as omitted fields, and do not invent Email",
     LINKEDIN_WEB_OPERATIONS["contacts.read"].contractVersion,
   ),
   "feeds.read": contract(

package/tsconfig.json

@@ -29,6 +29,9 @@
       ],
       "@hraness/ghostget/messaging": [
         "./src/messaging.ts"
+      ],
+      "@hraness/ghostget/messaging-automation": [
+        "./src/messaging-automation-types.ts"
       ]
     },
     "verbatimModuleSyntax": true,