@hraness/ghostget 0.17.5 → 0.18.0

package/src/provider-plugin.ts

@@ -25,6 +25,7 @@ import {
   sep,
 } from "node:path";
 import { fileURLToPath } from "node:url";
+import { scanProviderPluginValueImports } from "./provider-plugin-import-analysis";
 
 import type { GhostgetAuth } from "./auth";
 import type { MessageLikeMeSourceConversationCoordinateBindingV1 } from "./message-like-me-agentic-messaging";
@@ -1339,10 +1340,6 @@ const MAX_PROVIDER_PLUGIN_EVALUATION_PACKAGE_DEPTH = 32;
 const MAX_PROVIDER_PLUGIN_EVALUATION_PACKAGE_PATH_BYTES = 1_024;
 const MAX_PROVIDER_PLUGIN_EVALUATION_PACKAGE_BYTES = 128 * 1024 * 1024;
 const MAX_PROVIDER_PLUGIN_EVALUATION_PACKAGE_CACHE_ENTRIES = 256;
-const providerPluginEvaluationImportScanners = Object.freeze({
-  js: new Bun.Transpiler({ loader: "js" }),
-  ts: new Bun.Transpiler({ loader: "ts" }),
-});
 const providerPluginEvaluationModuleExtensions = new Set([
   ".cjs",
   ".cts",
@@ -2194,11 +2191,10 @@ function providerPluginEvaluationValueImports(
       `provider plugin evaluation module ${path} must be valid UTF-8`,
     );
   }
-  const scanner =
+  const loader =
     extension === ".ts" || extension === ".mts" || extension === ".cts"
-      ? providerPluginEvaluationImportScanners.ts
-      : providerPluginEvaluationImportScanners.js;
-  const imports = Object.freeze([...scanner.scanImports(source)]);
+      ? "ts" : "js";
+  const imports = scanProviderPluginValueImports(source, loader);
   if (imports.length > MAX_PROVIDER_PLUGIN_EVALUATION_IMPORTS_PER_MODULE) {
     throw new Error(
       `provider plugin evaluation module ${path} has too many static imports`,

package/src/providers/linkedin-web-contact.ts

@@ -42,7 +42,28 @@ const MAX_CODE_TAGS = 256;
 const MAX_COMO_ASSIGNMENTS = 8;
 const MAX_COMO_DECODED_ROOTS = 256;
 const MAX_WALK_NODES = 500_000;
+const MAX_WALK_DEPTH = 128;
 const RSC_FLIGHT_ROW = /(?:^|\n)(\d+):/u;
+const PROFILE_ID = /^[A-Za-z0-9_-]{1,256}$/u;
+const DISTANCE_IN_TEXT =
+  /(?:^|["'\\{,])(?:networkDistance|memberDistance|distance)"?\s*:\s*"?(DISTANCE_[A-Z0-9]+|OUT_OF_NETWORK|SELF|[0-9]+)"?/gu;
+const PROFILE_URN_IN_TEXT = /urn:li:fsd_profile:[A-Za-z0-9_-]{1,256}/gu;
+const VIEWEE_PROFILE_ID_IN_TEXT = /vieweeProfileId"\s*:\s*"([A-Za-z0-9_-]{1,256})"/gu;
+const VANITY_IN_TEXT =
+  /(?:vanityName|publicIdentifier)"\s*:\s*"([A-Za-z0-9][A-Za-z0-9_-]{1,99})"/gu;
+const KEYED_IDENTITY_KEYS = new Set([
+  "distance",
+  "entityUrn",
+  "isSelfView",
+  "memberDistance",
+  "networkDistance",
+  "objectUrn",
+  "profileUrn",
+  "publicIdentifier",
+  "vanityName",
+  "vieweeMemberUrn",
+  "vieweeProfileId",
+]);
 const MAX_PHONES = 8;
 const MAX_WEBSITES = 8;
 const CONTACT_TYPE_SUFFIX = "ProfileContactInfo";
@@ -315,6 +336,99 @@ function looksLikeRscFlight(value: string): boolean {
   return RSC_FLIGHT_ROW.test(value);
 }
 
+function extractJsonString(source: string, start: number): string | undefined {
+  if (source[start] !== "\"") return undefined;
+  let escaped = false;
+  const limit = Math.min(source.length, start + MAX_HTML_BYTES);
+  for (let index = start + 1; index < limit; index += 1) {
+    const character = source[index];
+    if (character === undefined) break;
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (character === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (character === "\"") return source.slice(start, index + 1);
+  }
+  return undefined;
+}
+
+function breadcrumbRecordFromText(value: string): JsonRecord | null {
+  if (value.length < 8 || value.length > 1024 * 1024) return null;
+  const distances = [...value.matchAll(DISTANCE_IN_TEXT)]
+    .map((match) => match[1])
+    .filter((item): item is string => item !== undefined);
+  const urns = [...value.matchAll(PROFILE_URN_IN_TEXT)];
+  const vieweeIds = [...value.matchAll(VIEWEE_PROFILE_ID_IN_TEXT)]
+    .map((match) => match[1])
+    .filter((item): item is string => item !== undefined);
+  const vanities = [...value.matchAll(VANITY_IN_TEXT)]
+    .map((match) => match[1])
+    .filter((item): item is string => item !== undefined);
+  if (
+    distances.length === 0
+    && urns.length === 0
+    && vieweeIds.length === 0
+    && vanities.length === 0
+  ) return null;
+  const record: Record<string, unknown> = {};
+  if (distances.length === 1) {
+    const raw = distances[0]!;
+    record.networkDistance = /^[0-9]+$/u.test(raw) ? Number(raw) : raw;
+  } else if (distances.length > 1) {
+    const unique = [...new Set(distances)];
+    if (unique.length === 1) {
+      const raw = unique[0]!;
+      record.networkDistance = /^[0-9]+$/u.test(raw) ? Number(raw) : raw;
+    }
+  }
+  if (urns.length === 1) record.profileUrn = urns[0]![0];
+  if (vieweeIds.length === 1) record.vieweeProfileId = vieweeIds[0];
+  if (vanities.length === 1) record.vanityName = vanities[0];
+  return Object.keys(record).length > 0 ? Object.freeze(record) : null;
+}
+
+function stringLooksLikeBootstrap(value: string): boolean {
+  return value.includes("networkDistance")
+    || value.includes("memberDistance")
+    || value.includes("vieweeProfileId")
+    || value.includes("vieweeMemberUrn")
+    || value.includes("vanityName")
+    || value.includes("publicIdentifier")
+    || /"distance"\s*:/u.test(value);
+}
+
+function decodeStringBootstrap(value: string): unknown[] {
+  const trimmed = value.trim();
+  if (trimmed.length < 8 || trimmed.length > 1024 * 1024) return [];
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return [JSON.parse(trimmed) as unknown];
+    } catch {
+      // Fall through to breadcrumb extraction from partial RSC string rows.
+    }
+  }
+  if (!stringLooksLikeBootstrap(trimmed)) return [];
+  const breadcrumb = breadcrumbRecordFromText(trimmed);
+  return breadcrumb === null ? [] : [breadcrumb];
+}
+
+function recordFromKeyedArray(value: readonly unknown[]): JsonRecord | null {
+  if (value.length < 2 || value.length % 2 !== 0 || value.length > 64) return null;
+  const record: Record<string, unknown> = {};
+  let recognized = 0;
+  for (let index = 0; index < value.length; index += 2) {
+    const key = value[index];
+    if (typeof key !== "string" || key.length < 1 || key.length > 128) return null;
+    record[key] = value[index + 1];
+    if (KEYED_IDENTITY_KEYS.has(key)) recognized += 1;
+  }
+  return recognized > 0 ? Object.freeze(record) : null;
+}
+
 function decodeRscFlightRecords(text: string): unknown[] {
   const records: unknown[] = [];
   let index = 0;
@@ -334,7 +448,28 @@ function decodeRscFlightRecords(text: string): unknown[] {
       index += json.length;
       continue;
     }
-    const nextRow = text.slice(index).search(/\n\d+:/u);
+    if (first === "\"") {
+      const json = extractJsonString(text, index);
+      if (json === undefined) {
+        index += 1;
+        continue;
+      }
+      try {
+        const decoded = JSON.parse(json) as unknown;
+        if (typeof decoded === "string") records.push(...decodeStringBootstrap(decoded));
+        else records.push(decoded);
+      } catch {
+        const breadcrumb = breadcrumbRecordFromText(json);
+        if (breadcrumb !== null) records.push(breadcrumb);
+      }
+      index += json.length;
+      continue;
+    }
+    const remainder = text.slice(index);
+    const nextRow = remainder.search(/\n\d+:/u);
+    const rowText = nextRow === -1 ? remainder : remainder.slice(0, nextRow);
+    const breadcrumb = breadcrumbRecordFromText(rowText);
+    if (breadcrumb !== null) records.push(breadcrumb);
     index = nextRow === -1 ? text.length : index + nextRow + 1;
   }
   return records;
@@ -433,13 +568,21 @@ function embeddedRecords(html: unknown): readonly JsonRecord[] {
   while (stack.length > 0) {
     const next = stack.pop()!;
     nodes += 1;
-    if (nodes > MAX_WALK_NODES || next.depth > 32) {
+    if (nodes > MAX_WALK_NODES || next.depth > MAX_WALK_DEPTH) {
       throw new Error("LinkedIn contact-info bootstrap exceeded its traversal bound");
     }
+    if (typeof next.value === "string") {
+      for (const value of decodeStringBootstrap(next.value)) {
+        stack.push({ value, depth: next.depth + 1 });
+      }
+      continue;
+    }
     if (Array.isArray(next.value)) {
       if (next.value.length > 20_000) {
         throw new Error("LinkedIn contact-info bootstrap array exceeded its reviewed bound");
       }
+      const keyed = recordFromKeyedArray(next.value);
+      if (keyed !== null) records.push(keyed);
       for (const value of next.value) stack.push({ value, depth: next.depth + 1 });
       continue;
     }
@@ -505,17 +648,33 @@ function vanityFromRecord(record: JsonRecord): string | null {
     ?? vanityFromHref(record.navigationUrl);
 }
 
-function profileUrnFromRecord(record: JsonRecord): string | null {
-  for (const key of ["entityUrn", "objectUrn", "profileUrn", "vieweeMemberUrn"] as const) {
-    const value = record[key];
-    if (typeof value !== "string") continue;
+function profileUrnFromIdentity(value: unknown): string | null {
+  if (typeof value !== "string" || value.length < 1 || value.length > 512) return null;
+  if (value.startsWith("urn:li:fsd_profile:")) {
     try {
       return profileUrn(value);
     } catch {
-      continue;
+      return null;
     }
   }
-  return null;
+  if (!PROFILE_ID.test(value)) return null;
+  try {
+    return profileUrn(`urn:li:fsd_profile:${value}`);
+  } catch {
+    return null;
+  }
+}
+
+function profileUrnFromRecord(record: JsonRecord): string | null {
+  for (const key of ["entityUrn", "objectUrn", "profileUrn", "vieweeMemberUrn"] as const) {
+    const urn = profileUrnFromIdentity(record[key]);
+    if (urn !== null) return urn;
+  }
+  return profileUrnFromIdentity(record.vieweeProfileId);
+}
+
+function recordIsSelfView(record: JsonRecord): boolean {
+  return record.isSelfView === true;
 }
 
 function selfProfileError(): Error {
@@ -524,6 +683,68 @@ function selfProfileError(): Error {
   );
 }
 
+function omittedDistanceError(): Error {
+  return new Error(
+    "LinkedIn contact-info profile page omitted or contradicted its relationship distance",
+  );
+}
+
+function uniqueDistances(values: readonly (string | number)[]): (string | number)[] {
+  const unique = [...new Set(values.map((value) => String(value)))];
+  return unique.map((value) => values.find((candidate) => String(candidate) === value)!);
+}
+
+function recordMatchesTarget(
+  record: JsonRecord,
+  slug: string,
+  urn: string,
+): boolean {
+  const vanity = vanityFromRecord(record);
+  const recordUrn = profileUrnFromRecord(record);
+  return vanity === slug || recordUrn === urn;
+}
+
+function recordContradictsTarget(
+  record: JsonRecord,
+  slug: string,
+  urn: string,
+): boolean {
+  const vanity = vanityFromRecord(record);
+  const recordUrn = profileUrnFromRecord(record);
+  return (vanity !== null && vanity !== slug) || (recordUrn !== null && recordUrn !== urn);
+}
+
+function relationshipDistance(
+  records: readonly JsonRecord[],
+  slug: string,
+  urn: string,
+  viewer: string,
+): string | number {
+  const bound = records
+    .filter((record) => recordMatchesTarget(record, slug, urn))
+    .map(distanceValue)
+    .filter((value): value is string | number => value !== null);
+  const boundOther = bound.filter((value) => !isSelfDistance(value));
+  const boundUnique = uniqueDistances(boundOther);
+  if (boundUnique.length === 1 && boundUnique[0] !== undefined) return boundUnique[0];
+  if (boundUnique.length > 1) throw omittedDistanceError();
+  if (bound.some(isSelfDistance) && urn === viewer) throw selfProfileError();
+
+  const breadcrumbs = records
+    .filter((record) => !recordContradictsTarget(record, slug, urn))
+    .map(distanceValue)
+    .filter((value): value is string | number => value !== null);
+  const breadcrumbOther = breadcrumbs.filter((value) => !isSelfDistance(value));
+  const breadcrumbUnique = uniqueDistances(breadcrumbOther);
+  if (breadcrumbUnique.length === 1 && breadcrumbUnique[0] !== undefined) {
+    return breadcrumbUnique[0];
+  }
+  if (breadcrumbs.some(isSelfDistance) && (urn === viewer || breadcrumbOther.length === 0)) {
+    throw selfProfileError();
+  }
+  throw omittedDistanceError();
+}
+
 export function projectLinkedInProfileContactBinding(input: {
   readonly profileHtml: unknown;
   readonly profileUrl: unknown;
@@ -536,6 +757,7 @@ export function projectLinkedInProfileContactBinding(input: {
   if (vanityRecords.length < 1) {
     throw new Error("LinkedIn contact-info profile page did not bind the requested vanity");
   }
+  if (vanityRecords.some(recordIsSelfView)) throw selfProfileError();
   const urns = new Set<string>();
   for (const record of vanityRecords) {
     const urn = profileUrnFromRecord(record);
@@ -547,7 +769,11 @@ export function projectLinkedInProfileContactBinding(input: {
     for (const record of records) {
       const urn = profileUrnFromRecord(record);
       const distance = distanceValue(record);
-      if (urn === viewer || (distance !== null && isSelfDistance(distance))) {
+      if (
+        recordIsSelfView(record)
+        || urn === viewer
+        || (distance !== null && isSelfDistance(distance))
+      ) {
         sawSelf = true;
       }
       if (urn === null || urn === viewer || distance === null) continue;
@@ -567,17 +793,7 @@ export function projectLinkedInProfileContactBinding(input: {
   }
   const urn = urns.values().next().value!;
   if (urn === viewer) throw selfProfileError();
-  const related = records.filter((record) =>
-    vanityFromRecord(record) === target.slug || profileUrnFromRecord(record) === urn
-  );
-  const distances = related
-    .map(distanceValue)
-    .filter((value): value is string | number => value !== null);
-  const unique = [...new Set(distances.map((value) => String(value)))];
-  if (unique.length !== 1 || distances[0] === undefined) {
-    throw new Error("LinkedIn contact-info profile page omitted or contradicted its relationship distance");
-  }
-  const distance = distances[0];
+  const distance = relationshipDistance(records, target.slug, urn, viewer);
   if (isSelfDistance(distance)) throw selfProfileError();
   if (!isFirstDegree(distance)) {
     throw new Error(
@@ -826,7 +1042,7 @@ function collectRecords(value: unknown): readonly JsonRecord[] {
   while (stack.length > 0) {
     const next = stack.pop()!;
     nodes += 1;
-    if (nodes > MAX_WALK_NODES || next.depth > 32) {
+    if (nodes > MAX_WALK_NODES || next.depth > MAX_WALK_DEPTH) {
       throw new Error("LinkedIn contact-info payload exceeded its traversal bound");
     }
     if (Array.isArray(next.value)) {

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",