@hraness/ghostget 0.17.5 → 0.18.0

package/src/operation-permission-store.ts

@@ -0,0 +1,92 @@
+import { join } from "node:path";
+import { canonicalJson, sha256 } from "./canonical-json";
+import { createPrivateJsonIfAbsent, ensurePrivateStateDirectory, ghostgetStateHome, privateStateFilesMayExist, readPrivateStateFileIfPresent, writePrivateJsonIfUnchanged } from "./storage";
+import type { PermissionDecision } from "./control/protocol";
+
+export type PermissionEnvironment = Readonly<Record<string, string | undefined>>;
+export type OperationPolicyEntry = Readonly<{ digest: string; decision: PermissionDecision }>;
+export type OperationPolicy = Readonly<{ schemaVersion: 1; revision: number; entries: readonly OperationPolicyEntry[] }>;
+export type OperationPolicySnapshot = Readonly<{ managed: boolean; revision: number; entries: readonly OperationPolicyEntry[]; contentSha256: string | null }>;
+const MAX_POLICY_BYTES = 512 * 1024;
+const MAX_ENTRIES = 4096;
+const DIGEST = /^[a-f0-9]{64}$/u;
+const marker = Object.freeze({ schemaVersion: 1, managed: true });
+
+export class OperationPermissionError extends Error {
+  constructor(readonly code: "OPERATION_PERMISSION_DENIED" | "OPERATION_APPROVAL_REQUIRED" | "OPERATION_PERMISSION_CHANGED" | "OPERATION_POLICY_INVALID" | "OPERATION_APPROVAL_TOO_LARGE", message: string) {
+    super(message);
+    this.name = "OperationPermissionError";
+  }
+}
+
+export function parseOperationPolicy(value: unknown): OperationPolicy {
+  const fail = (): never => { throw new OperationPermissionError("OPERATION_POLICY_INVALID", "Operation permission policy is invalid; repair it in Ghostget before execution."); };
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return fail();
+  const record = value as Record<string, unknown>;
+  if (Object.keys(record).sort().join(",") !== "entries,revision,schemaVersion" || record.schemaVersion !== 1
+    || !Number.isSafeInteger(record.revision) || (record.revision as number) < 1
+    || !Array.isArray(record.entries) || record.entries.length > MAX_ENTRIES) return fail();
+  let previous = "";
+  const entries = record.entries.map((candidate: unknown): OperationPolicyEntry => {
+    if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) return fail();
+    const entry = candidate as Record<string, unknown>;
+    if (Object.keys(entry).sort().join(",") !== "decision,digest" || typeof entry.digest !== "string" || !DIGEST.test(entry.digest)
+      || entry.digest <= previous || (entry.decision !== "allow" && entry.decision !== "deny" && entry.decision !== "ask")) return fail();
+    previous = entry.digest;
+    return Object.freeze({ digest: entry.digest, decision: entry.decision });
+  });
+  return Object.freeze({ schemaVersion: 1, revision: record.revision as number, entries: Object.freeze(entries) });
+}
+
+function paths(environment: PermissionEnvironment) {
+  const directory = join(ghostgetStateHome(environment), "operation-permissions");
+  return { directory, marker: join(directory, "managed.json"), policy: join(directory, "policy.json") };
+}
+
+export function readOperationPolicy(environment: PermissionEnvironment = process.env): OperationPolicySnapshot {
+  try {
+    if (!privateStateFilesMayExist("operation-permissions", ["managed.json", "policy.json"], environment)) {
+      return Object.freeze({ managed: false, revision: 0, entries: Object.freeze([]), contentSha256: null });
+    }
+    const selected = paths(environment);
+    const markerText = readPrivateStateFileIfPresent(selected.marker, 256, "operation policy marker", environment);
+    if (markerText !== null && markerText !== `${canonicalJson(marker)}\n`) throw new Error("marker");
+    const text = readPrivateStateFileIfPresent(selected.policy, MAX_POLICY_BYTES, "operation permission policy", environment);
+    if (text === null) {
+      if (markerText !== null) throw new Error("missing policy");
+      return Object.freeze({ managed: false, revision: 0, entries: Object.freeze([]), contentSha256: null });
+    }
+    const policy = parseOperationPolicy(JSON.parse(text) as unknown);
+    if (text !== `${canonicalJson(policy)}\n`) throw new Error("noncanonical policy");
+    return Object.freeze({ managed: true, revision: policy.revision, entries: policy.entries, contentSha256: sha256(text) });
+  } catch {
+    throw new OperationPermissionError("OPERATION_POLICY_INVALID", "Operation permission state is missing or invalid; execution is blocked until it is repaired.");
+  }
+}
+
+export function enableOperationPermissions(expectedRevision: number, environment: PermissionEnvironment = process.env): OperationPolicySnapshot {
+  const snapshot = readOperationPolicy(environment);
+  if (!Number.isSafeInteger(expectedRevision) || expectedRevision !== snapshot.revision) throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Operation policy changed; refresh Ghostget before editing it.");
+  if (snapshot.managed) return snapshot;
+  const selected = paths(environment);
+  ensurePrivateStateDirectory(selected.directory, environment);
+  // Publishing the marker first deliberately makes interrupted opt-in fail closed.
+  const created = createPrivateJsonIfAbsent(selected.marker, marker, { environment });
+  if (!created.created) throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Another control session enabled operation permissions.");
+  if (!createPrivateJsonIfAbsent(selected.policy, { schemaVersion: 1, revision: 1, entries: [] }, { environment }).created) {
+    throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Operation policy appeared concurrently; refresh Ghostget.");
+  }
+  return readOperationPolicy(environment);
+}
+
+export function setOperationPolicyEntry(digest: string, decision: PermissionDecision, expectedRevision: number, environment: PermissionEnvironment = process.env): OperationPolicySnapshot {
+  if (!DIGEST.test(digest) || !["allow", "deny", "ask"].includes(decision)) throw new OperationPermissionError("OPERATION_POLICY_INVALID", "Operation permission update is invalid.");
+  const snapshot = readOperationPolicy(environment);
+  if (!snapshot.managed || snapshot.contentSha256 === null || !Number.isSafeInteger(expectedRevision) || snapshot.revision !== expectedRevision
+    || snapshot.revision >= Number.MAX_SAFE_INTEGER) throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Enable operation permissions or refresh the policy before editing it.");
+  const entries = [...snapshot.entries.filter(entry => entry.digest !== digest), { digest, decision }].sort((a, b) => a.digest.localeCompare(b.digest));
+  const policy = parseOperationPolicy({ schemaVersion: 1, revision: snapshot.revision + 1, entries });
+  if (Buffer.byteLength(canonicalJson(policy)) > MAX_POLICY_BYTES - 1) throw new OperationPermissionError("OPERATION_POLICY_INVALID", "Operation policy exceeds its size limit.");
+  if (!writePrivateJsonIfUnchanged(paths(environment).policy, policy, { expectedCurrentContentSha256: snapshot.contentSha256 })) throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Operation policy changed; refresh Ghostget before editing it.");
+  return readOperationPolicy(environment);
+}

package/src/operation-permission.ts

@@ -0,0 +1,308 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { canonicalJson, sha256 } from "./canonical-json";
+import { loadAuth, parseAuth } from "./auth";
+import { isLocalCliOperation, isProviderOperation, isWebSessionOperation, manifestHash, parseRuntimeManifest, type GhostgetManifest, type OperationInput } from "./model";
+import { providerContractHash, getProviderContract } from "./provider-contracts";
+import { getWebSessionContract, webSessionContractHash } from "./web-session-contracts";
+import { getLocalCliContract, localCliContractHash } from "./local-cli-contracts";
+import { requireProviderPluginAuth } from "./provider-plugin-auth";
+import type { ProviderPluginRegistry, ProviderPluginOperationResolutionV1 } from "./provider-plugin-registry";
+import { ghostgetStateHome, loadInstalledManifest } from "./storage";
+import { projectionAuthIdentityHash, withSettledReadProjectionAuthAdmission } from "./read-projections";
+import { publicWebSessionAuthorityIdentityHash, webSessionAuthenticationPolicy, type InvocationAuthority } from "./web-session-authentication-policy";
+import type { PreparedInvocation, StoredPlan } from "./runtime";
+import { summarizePlanFile } from "./plan-assets";
+import type { ApprovalTarget, CheckedApproval, JsonValue, PermissionDecision } from "./control/protocol";
+import { OperationPermissionError, readOperationPolicy, setOperationPolicyEntry, type PermissionEnvironment, type OperationPolicySnapshot } from "./operation-permission-store";
+export { OperationPermissionError, readOperationPolicy, enableOperationPermissions } from "./operation-permission-store";
+
+type Options = { readonly environment: PermissionEnvironment; readonly registry: ProviderPluginRegistry; readonly signal?: AbortSignal };
+type ProviderTarget = Extract<ApprovalTarget, { readonly kind: "provider" }>;
+type ApprovalLease = Readonly<{ id: string; digest: string }>;
+export type OperationPermissionIdentity = Readonly<{
+  schemaVersion: 1; pluginId: string; transport: string; surfaceId: string; operation: string; contractVersion: number;
+  adapterId: string; manifestHash: string; authId: string; authIncarnation: string; contractHash: string; closureHash: string; portableHash: string | null;
+}>;
+export type OperationPermissionDescription = Readonly<{
+  digest: string; decision: PermissionDecision | "unmanaged"; revision: number; coordinate: OperationPermissionIdentity;
+  manifest: GhostgetManifest; resolution: ProviderPluginOperationResolutionV1; auth: InvocationAuthority;
+}>;
+type Admission = Readonly<{ capability: string; requestDigest: string; revision: number; inputs: ReadonlySet<string>; planDigest: string | null; lease: ApprovalLease | null; stateHome: string }>;
+const admissions = new AsyncLocalStorage<readonly Admission[]>();
+const checkedCapabilities = new WeakMap<CheckedApproval, Readonly<{ capability: string; target: string }>>();
+const MAX_APPROVAL_BYTES = 240 * 1024;
+
+function changed(): never { throw new OperationPermissionError("OPERATION_PERMISSION_CHANGED", "Operation, account, input, or permissions changed; request fresh authorization."); }
+function denied(): never { throw new OperationPermissionError("OPERATION_PERMISSION_DENIED", "This operation is denied in Ghostget. Review its account and operation permissions in the app."); }
+function approvalRequired(): never { throw new OperationPermissionError("OPERATION_APPROVAL_REQUIRED", "This operation requires human approval in Ghostget. Run a live invocation with the app open; cached reads never wait for approval."); }
+
+function resolutionFor(manifest: GhostgetManifest, operationId: string, registry: ProviderPluginRegistry): ProviderPluginOperationResolutionV1 {
+  const operation = manifest.operations[operationId];
+  if (operation === undefined) throw new Error("Operation is not installed.");
+  if (isProviderOperation(operation)) return registry.requireOperationDefinition("provider-api", operation.provider.provider, operation.provider.action, operation.provider.contractVersion);
+  if (isLocalCliOperation(operation)) return registry.requireOperationDefinition("local-cli", operation.localCli.surface, operation.localCli.action, operation.localCli.contractVersion);
+  if (isWebSessionOperation(operation)) return registry.requireOperationDefinition(registry.requireSessionRoute(operation.webSession.site).transport, operation.webSession.site, operation.webSession.action, operation.webSession.contractVersion);
+  throw new OperationPermissionError("OPERATION_PERMISSION_DENIED", "This legacy transport does not support managed operation permissions.");
+}
+
+function currentManifest(adapterId: string, options: Options): GhostgetManifest {
+  const owned = options.registry.resolveOwnedManifest(adapterId);
+  const selected = owned === undefined ? loadInstalledManifest(adapterId, options.environment, options.registry) : parseRuntimeManifest(owned, options.registry);
+  if (!selected.ok) throw new Error("The selected adapter is unavailable or invalid.");
+  return selected.value;
+}
+
+function publicAuthority(manifest: GhostgetManifest, operationId: string, resolution: ProviderPluginOperationResolutionV1): InvocationAuthority | null {
+  const operation = manifest.operations[operationId]!;
+  if (!isWebSessionOperation(operation)) return null;
+  const policy = webSessionAuthenticationPolicy({
+    adapterId: manifest.id, operationId, recipe: operation.webSession, pluginSourceKind: resolution.plugin.sourceKind,
+    portable: resolution.portableIdentity !== null, risk: resolution.operation.risk, state: resolution.operation.state, dispatch: resolution.operation.dispatch,
+    ...(resolution.contractVersion === resolution.operation.contractVersion && resolution.operation.access !== undefined ? { access: resolution.operation.access } : {}),
+  });
+  return policy.kind === "public" ? policy.authority : null;
+}
+
+type AccountIdentity = Readonly<{ auth: ReturnType<typeof loadAuth>; incarnation: string }>;
+type Inspection = {
+  policy: OperationPolicySnapshot;
+  manifests: Map<string, GhostgetManifest>;
+  accounts: Map<string, AccountIdentity | null>;
+  closures: Map<ProviderPluginOperationResolutionV1["binding"], string>;
+  contracts: Map<string, string>;
+};
+function accountIdentity(id: string, options: Options): AccountIdentity {
+  return withSettledReadProjectionAuthAdmission(id, options.environment, () => {
+    const auth = loadAuth(id, options.environment);
+    return { auth, incarnation: projectionAuthIdentityHash(auth.id, sha256(canonicalJson(auth)), options.environment) };
+  });
+}
+function inspectedAccount(id: string, options: Options, inspection: Inspection): AccountIdentity {
+  if (!inspection.accounts.has(id)) {
+    try { inspection.accounts.set(id, accountIdentity(id, options)); } catch { inspection.accounts.set(id, null); }
+  }
+  const account = inspection.accounts.get(id);
+  if (account === null || account === undefined) throw new Error("The selected account is unavailable.");
+  return account;
+}
+function describe(adapterId: string, operationId: string, authId: string | null, options: Options, inspection: Inspection): OperationPermissionDescription {
+  const { policy } = inspection;
+  const manifest = inspection.manifests.get(adapterId) ?? currentManifest(adapterId, options);
+  inspection.manifests.set(adapterId, manifest);
+  const resolution = resolutionFor(manifest, operationId, options.registry);
+  const operation = manifest.operations[operationId]!;
+  const publicAuth = publicAuthority(manifest, operationId, resolution);
+  if (publicAuth !== null && authId !== null) throw new Error("Public operations do not accept an account.");
+  if (publicAuth === null && authId === null) throw new Error("Select an explicit account to inspect private operation permissions.");
+  const selectedId = authId ?? adapterId;
+  const authority = publicAuth !== null
+    ? { auth: publicAuth, incarnation: publicWebSessionAuthorityIdentityHash(publicAuth as Parameters<typeof publicWebSessionAuthorityIdentityHash>[0]) }
+    : inspectedAccount(selectedId, options, inspection);
+  if (publicAuth === null) {
+    requireProviderPluginAuth(resolution.binding, authority.auth as ReturnType<typeof loadAuth>);
+  }
+  const contractKey = canonicalJson([resolution.binding.transport, resolution.binding.surfaceId, resolution.operation.name, resolution.contractVersion]);
+  const contractHash = inspection.contracts.get(contractKey) ?? (isProviderOperation(operation) ? providerContractHash(getProviderContract(operation.provider, options.registry), options.registry)
+    : isWebSessionOperation(operation) ? webSessionContractHash(getWebSessionContract(operation.webSession, options.registry), options.registry)
+      : isLocalCliOperation(operation) ? localCliContractHash(getLocalCliContract(operation.localCli, options.registry), options.registry) : denied());
+  inspection.contracts.set(contractKey, contractHash);
+  const closureHash = inspection.closures.get(resolution.binding) ?? options.registry.implementationClosureHash(resolution.binding);
+  inspection.closures.set(resolution.binding, closureHash);
+  const coordinate: OperationPermissionIdentity = Object.freeze({
+    schemaVersion: 1, pluginId: resolution.plugin.id, transport: resolution.binding.transport, surfaceId: resolution.binding.surfaceId,
+    operation: resolution.operation.name, contractVersion: resolution.contractVersion, adapterId, manifestHash: manifestHash(manifest),
+    authId: authority.auth.id, authIncarnation: authority.incarnation, contractHash,
+    closureHash, portableHash: resolution.portableIdentity === null ? null : sha256(canonicalJson(resolution.portableIdentity)),
+  });
+  const digest = sha256(canonicalJson(coordinate));
+  return Object.freeze({ digest, coordinate, revision: policy.revision, decision: policy.managed ? policy.entries.find(entry => entry.digest === digest)?.decision ?? "deny" : "unmanaged", manifest, resolution, auth: authority.auth });
+}
+
+function inspection(options: Options): Inspection {
+  return { policy: readOperationPolicy(options.environment), manifests: new Map(), accounts: new Map(), closures: new Map(), contracts: new Map() };
+}
+
+export function describeOperationPermission(adapterId: string, operationId: string, authId: string | null, options: Options): OperationPermissionDescription {
+  return describe(adapterId, operationId, authId, options, inspection(options));
+}
+
+/** Snapshot-local reuse keeps control-panel inspection proportional to unique accounts and adapters. Never reuse this snapshot to authorize a later request. */
+export function describeOperationPermissions(requests: readonly Readonly<{ adapterId: string; operationId: string; authId: string | null }>[], options: Options): readonly (OperationPermissionDescription | null)[] {
+  const unavailable = () => Object.freeze(requests.map(() => null));
+  let snapshot: Inspection;
+  try { snapshot = inspection(options); } catch { return unavailable(); }
+  const results = requests.map(request => {
+    try { return describe(request.adapterId, request.operationId, request.authId, options, snapshot); } catch { return null; }
+  });
+  try {
+    for (const [id, manifest] of snapshot.manifests) if (manifestHash(currentManifest(id, options)) !== manifestHash(manifest)) return unavailable();
+    for (const [id, identity] of snapshot.accounts) if (identity !== null && canonicalJson(accountIdentity(id, options)) !== canonicalJson(identity)) return unavailable();
+    for (const [binding, closure] of snapshot.closures) if (options.registry.implementationClosureHash(binding) !== closure) return unavailable();
+    if (canonicalJson(readOperationPolicy(options.environment)) !== canonicalJson(snapshot.policy)) return unavailable();
+  } catch { return unavailable(); }
+  return Object.freeze(results);
+}
+
+export function setOperationPermission(request: {
+  readonly adapterId: string; readonly operationId: string; readonly authId: string | null; readonly decision: PermissionDecision;
+  readonly expectedRevision: number; readonly expectedCapabilityDigest: string;
+}, options: Options) {
+  const description = describeOperationPermission(request.adapterId, request.operationId, request.authId, options);
+  if (description.digest !== request.expectedCapabilityDigest || description.revision !== request.expectedRevision) return changed();
+  return setOperationPolicyEntry(description.digest, request.decision, request.expectedRevision, options.environment);
+}
+
+function describeInvocation(invocation: PreparedInvocation, options: Options): OperationPermissionDescription {
+  const description = describeOperationPermission(invocation.manifest.id, invocation.operationId, invocation.auth.kind === "public-web-session" ? null : invocation.auth.id, options);
+  if (manifestHash(invocation.manifest) !== description.coordinate.manifestHash || canonicalJson(invocation.auth) !== canonicalJson(description.auth)
+    || invocation.readProjectionAuthIdentityHash !== description.coordinate.authIncarnation) return changed();
+  if (invocation.auth.kind !== "public-web-session") parseAuth(invocation.auth);
+  return description;
+}
+
+function activeAdmission(description: OperationPermissionDescription, input: OperationInput, options: Options): Admission | undefined {
+  const hash = sha256(canonicalJson(input));
+  const stateHome = ghostgetStateHome(options.environment);
+  return admissions.getStore()?.findLast(admission => admission.stateHome === stateHome && admission.capability === description.digest && admission.revision === description.revision && admission.inputs.has(hash));
+}
+
+/** Cheap deny check for construction and identity queries. Inspection by the control plane uses describeOperationPermission instead. */
+export function assertOperationPreparationPermission(invocation: PreparedInvocation, options: Options): void {
+  if (!readOperationPolicy(options.environment).managed) return;
+  if (describeInvocation(invocation, options).decision === "deny") denied();
+}
+
+/** Synchronous disclosure never opens IPC or creates an approval request. */
+export function assertOperationPermission(invocation: PreparedInvocation, options: Options): void {
+  const policy = readOperationPolicy(options.environment);
+  if (!policy.managed) {
+    if (admissions.getStore()?.some(admission => admission.revision !== 0)) changed();
+    return;
+  }
+  const description = describeInvocation(invocation, options);
+  if (admissions.getStore()?.some(admission => admission.capability === description.digest && admission.revision !== description.revision)) changed();
+  if (description.decision === "deny") denied();
+  if (description.decision === "ask" && activeAdmission(description, invocation.input, options) === undefined) approvalRequired();
+}
+
+export async function checkOperationPermission(invocation: PreparedInvocation, options: Options): Promise<void> {
+  assertOperationPermission(invocation, options);
+  if (!readOperationPolicy(options.environment).managed) return;
+  const description = describeInvocation(invocation, options);
+  const admission = activeAdmission(description, invocation.input, options);
+  if (admission?.lease !== null && admission?.lease !== undefined) {
+    const { checkApproval } = await import("./control/approval-client");
+    await checkApproval(admission.lease, { environment: options.environment, ...(options.signal === undefined ? {} : { signal: options.signal }) });
+    assertOperationPermission(invocation, options);
+  }
+}
+
+function inputForTarget(input: OperationInput): JsonValue {
+  return JSON.parse(canonicalJson(Object.fromEntries(Object.entries(input).map(([key, value]) => [key,
+    Array.isArray(value) ? value.map(item => typeof item === "object" ? item.reference : item)
+      : typeof value === "object" && "reference" in value ? value.reference : value,
+  ])))) as JsonValue;
+}
+
+function checkedApproval(invocation: PreparedInvocation, description: OperationPermissionDescription, stored: StoredPlan | null): CheckedApproval {
+  const previewOf = (input: OperationInput): unknown => Object.fromEntries(Object.entries(input).map(([key, value]) => [key,
+    Array.isArray(value) ? value.map(item => typeof item === "object" ? summarizePlanFile(item) : item)
+      : typeof value === "object" ? summarizePlanFile(value as Parameters<typeof summarizePlanFile>[0]) : value,
+  ]));
+  const composite = stored?.plan.messagingComposite;
+  const previewInput = composite === undefined ? previewOf(invocation.input) : {
+    recipient: composite.recipient,
+    routeRef: composite.routeRef,
+    contextRef: composite.contextRef,
+    parts: composite.parts.map(part => ({ part: part.partId, text: part.text, input: previewOf(part.input) })),
+  };
+  const preview = canonicalJson(previewInput);
+  if (Buffer.byteLength(preview) > MAX_APPROVAL_BYTES) throw new OperationPermissionError("OPERATION_APPROVAL_TOO_LARGE", "This operation exceeds the human approval preview size limit; no request was executed.");
+  const digest = sha256(canonicalJson({ protocol: "ghostget.operation-approval/1", capability: description.digest, revision: description.revision,
+    inputHash: sha256(canonicalJson(invocation.input)), planDigest: stored?.digest ?? null, previewHash: sha256(preview) }));
+  return Object.freeze({ digest, revision: description.revision, decision: description.decision === "unmanaged" ? "allow" : description.decision,
+    kind: "provider", title: `${description.manifest.displayName}: ${invocation.operationId}`, account: invocation.auth.kind === "public-web-session" ? null : invocation.auth.id,
+    effect: description.manifest.operations[invocation.operationId]!.sideEffect, preview });
+}
+
+/** Recompute agent requests using current installed manifests/auth and encrypted plans. Caller summaries never grant authority. */
+export async function checkProviderApproval(target: ProviderTarget, options: Options): Promise<CheckedApproval> {
+  const { prepareOperationApprovalInvocation } = await import("./runtime");
+  const { invocation, stored } = prepareOperationApprovalInvocation(target, options);
+  if (stored === null && invocation.manifest.operations[invocation.operationId]!.risk !== "R1") {
+    throw new OperationPermissionError("OPERATION_APPROVAL_REQUIRED", "This operation requires an exact saved confirmation plan before human approval.");
+  }
+  const description = describeInvocation(invocation, options);
+  const checked = checkedApproval(invocation, description, stored);
+  checkedCapabilities.set(checked, { capability: description.digest, target: canonicalJson(target) });
+  return checked;
+}
+
+/** A consumed plan is intentionally gone. Recheck retained admission authority, never revive or reload it. */
+export async function recheckProviderApproval(target: ProviderTarget, checked: CheckedApproval, options: Options): Promise<CheckedApproval> {
+  const retained = checkedCapabilities.get(checked);
+  if (retained === undefined || retained.target !== canonicalJson(target)) return changed();
+  const current = describeOperationPermission(target.adapterId, target.operationId, target.authId, options);
+  if (current.digest !== retained.capability || current.revision !== checked.revision || current.decision !== "ask") return changed();
+  return checked;
+}
+
+/** Invocation-local permits cannot authorize another input, account, manifest or policy revision. */
+export async function withOperationPermission<T>(invocation: PreparedInvocation, optionsValue: Options & { readonly plan?: StoredPlan }, work: () => Promise<T>): Promise<T> {
+  const options = { ...optionsValue, environment: Object.freeze({ ...optionsValue.environment }) };
+  const policy = readOperationPolicy(options.environment);
+  if (!policy.managed) return withUnmanagedOperationPermission(options.environment, work);
+  const description = describeInvocation(invocation, options);
+  if (description.decision === "deny") denied();
+  const existing = activeAdmission(description, invocation.input, options);
+  if (existing !== undefined) {
+    if (options.plan !== undefined && existing.planDigest !== options.plan.digest) return changed();
+    await checkOperationPermission(invocation, options);
+    const result = await work();
+    await checkOperationPermission(invocation, options);
+    return result;
+  }
+  const checked = description.decision === "ask" ? checkedApproval(invocation, description, options.plan ?? null) : null;
+  // Capture the authorized values before the first await: readonly TypeScript input is not an immutable runtime object.
+  const inputHashes = [sha256(canonicalJson(invocation.input)), ...(options.plan?.plan.messagingComposite?.parts.map(part => sha256(canonicalJson(part.input))) ?? [])];
+  const planDigest = options.plan?.digest ?? null;
+  const stateHome = ghostgetStateHome(options.environment);
+  let lease: ApprovalLease | null = null;
+  if (description.decision === "ask") {
+    const target: ProviderTarget = { kind: "provider", adapterId: invocation.manifest.id, operationId: invocation.operationId,
+      authId: invocation.auth.kind === "public-web-session" ? null : invocation.auth.id,
+      input: options.plan === undefined ? inputForTarget(invocation.input) : null, planDigest: options.plan?.digest ?? null };
+    const { requestApproval } = await import("./control/approval-client");
+    if (checked === null) return changed();
+    lease = await requestApproval(target, checked.digest, { environment: options.environment, ...(options.signal === undefined ? {} : { signal: options.signal }) });
+  }
+  const admission: Admission = Object.freeze({ capability: description.digest, requestDigest: checked?.digest ?? description.digest, revision: description.revision,
+    inputs: new Set(inputHashes), planDigest, lease, stateHome });
+  try {
+    return await admissions.run([...(admissions.getStore() ?? []), admission], async () => {
+      const current = describeInvocation(invocation, options);
+      if (current.digest !== description.digest || current.revision !== description.revision) changed();
+      await checkOperationPermission(invocation, options);
+      const result = await work();
+      await checkOperationPermission(invocation, options);
+      return result;
+    });
+  } finally {
+    if (lease !== null) {
+      const { releaseApproval } = await import("./control/approval-client");
+      await releaseApproval(lease, { environment: options.environment });
+    }
+  }
+}
+
+/** Preserve synchronous native admission while preventing opt-in during an in-flight legacy request from disclosing its result. */
+export async function withUnmanagedOperationPermission<T>(environment: PermissionEnvironment, work: () => Promise<T>): Promise<T> {
+  const result = await work();
+  if (readOperationPolicy(environment).managed) changed();
+  return result;
+}
+
+export async function withOperationPermissions<T>(invocations: readonly PreparedInvocation[], options: Options, work: () => Promise<T>): Promise<T> {
+  if (invocations.length === 0) return work();
+  return withOperationPermission(invocations[0]!, options, () => withOperationPermissions(invocations.slice(1), options, work));
+}

package/src/pinned-https.ts

@@ -15,6 +15,7 @@ export type PinnedHttpsResponse = PinnedNetworkResponse;
 export type PinnedHttpsDependencies = {
   readonly resolveTarget: typeof resolveSafeNetworkTarget;
   readonly request: NetworkTransport;
+  readonly beforeRequest?: () => void;
 };
 
 export type PinnedHttpsFetch = (
@@ -103,14 +104,18 @@ export async function pinnedHttpsFetch(
     throw new Error("authenticated request timeout is invalid");
   }
   const resolved = { ...defaultDependencies, ...dependencies };
+  init.signal.throwIfAborted();
   const addresses = await resolved.resolveTarget(url, {
     allowPrivateNetwork: false,
     timeoutMs,
   });
+  init.signal.throwIfAborted();
   const address = addresses[0];
   if (address === undefined) throw new Error("authenticated HTTPS origin did not resolve to a safe address");
   const headers = new Headers(init.headers);
   const body = requestBody(init.body);
+  resolved.beforeRequest?.();
+  init.signal.throwIfAborted();
   const response = await resolved.request({
     url,
     address,

package/src/provider-http.ts

@@ -76,7 +76,7 @@ function canonicalTokenPath(path: string): string {
   return current;
 }
 
-function readPrivateTokenFile(path: string): string {
+function readPrivateTokenFile(path: string, expectedContent?: string): string {
   if (!isAbsolute(path)) throw new Error("OAuth token file path must be absolute");
   const canonical = canonicalTokenPath(path);
   const descriptor = openSync(
@@ -112,6 +112,11 @@ function readPrivateTokenFile(path: string): string {
       || before.ctimeNs !== after.ctimeNs
       || before.mode !== after.mode
     ) throw new Error("OAuth token file changed while it was read");
+    // Bind write readback before decoding, including byte-order marks and
+    // formatting. Never derive cleanup authority from different stored bytes.
+    if (expectedContent !== undefined && !buffer.equals(Buffer.from(expectedContent, "utf8"))) {
+      throw new Error("OAuth credential file does not match its intended content");
+    }
     return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
   } finally {
     closeSync(descriptor);
@@ -190,11 +195,14 @@ function parseGoogleInstalledAppRefresh(value: unknown): GoogleInstalledAppRefre
 }
 
 /** Load and strictly bind a private token document without enforcing freshness. */
-export function loadOAuthCredential(auth: OAuthTokenAuth): LoadedOAuthCredential {
+export function loadOAuthCredential(
+  auth: OAuthTokenAuth,
+  options: Readonly<{ expectedContent?: string }> = {},
+): LoadedOAuthCredential {
   let content: string;
   let parsed: unknown;
   try {
-    content = readPrivateTokenFile(auth.path);
+    content = readPrivateTokenFile(auth.path, options.expectedContent);
     parsed = JSON.parse(content) as unknown;
   } catch (error) {
     throw new Error(`could not load private ${auth.provider} OAuth token document`, { cause: error });

package/src/provider-plugin-contract-identity.ts

@@ -303,8 +303,9 @@ const identities = Object.freeze({
   "linkedin-web": {
     schemaVersion: 1,
     pluginVersion: "1.6.0",
-    implementationSha256: "11b52ca3dd9cbafe4829eed9f27d59bdc1c312db943ea29b93cbab6417ac7025",
+    implementationSha256: "95000a4d81f2fdbd222fa793b229704ba77ab9a23d02b26db5fa561bd5d6e491",
     legacyCurrentReadImplementationSha256: [
+      "11b52ca3dd9cbafe4829eed9f27d59bdc1c312db943ea29b93cbab6417ac7025",
       "e4614ab9c7733d7526b8157410e462f1bb48fdaa1c2319a6a4179c18b9e6839d",
       "97194dc5a8ec3afc4f4a20152efe51dbdc2fa8a8dde0cd9484b54718c4767f45",
       "64621493e09949fcb9973270140fec1d7398374cf48d3ef150a0c24b882fdeb8",
@@ -316,7 +317,6 @@ const identities = Object.freeze({
       "dbda2aee2075a0a3726241fd24932113ae6c2d139ae1f7036ea827a335f7344c",
       "9acb34f9ef5f59dd46b249766af236a3876a4975e0797e330f2975b3fd4ed643",
       "951102310bd87f93ce0863c1a444371d62f412934cc805f82c9981f82edfe50e",
-      "4fd6c293984be688a9273acb09bccea64a75134daca745b322fa8d33dfe9f97c",
     ],
     legacyReadImplementationSha256: {
       test: "00a99426ec31182f8d37d5cceb819947a09e630b468bb6e3ed8827f5b0fa4628",

package/src/provider-plugin-import-analysis.ts

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+
+type LiteralModuleImport = {
+  readonly kind: string;
+  readonly path: string;
+};
+
+const scanners = Object.freeze({
+  js: new Bun.Transpiler({ loader: "js" }),
+  ts: new Bun.Transpiler({ loader: "ts" }),
+});
+const MAX_MEMO_ENTRIES = 2_048;
+const MAX_MEMO_TEXT_BYTES = 4 * 1024 * 1024;
+const importsMemo = new Map<string, {
+  readonly imports: readonly LiteralModuleImport[];
+  readonly textBytes: number;
+}>();
+let memoTextBytes = 0;
+
+/**
+ * Pure syntax only: callers still read current bytes, enforce their bounds,
+ * resolve every edge from its current importer, and revalidate the filesystem.
+ * Keep only immutable scanner output; never retain source text or an AST.
+ */
+export function scanProviderPluginValueImports(
+  source: string,
+  loader: "js" | "ts",
+): readonly LiteralModuleImport[] {
+  const key = `${loader}\0${createHash("sha256").update(source).digest("hex")}`;
+  const cached = importsMemo.get(key);
+  if (cached !== undefined) return cached.imports;
+  const imports = Object.freeze(scanners[loader].scanImports(source).map(
+    ({ kind, path }) => Object.freeze({ kind, path }),
+  ));
+  const textBytes = key.length + imports.reduce(
+    (total, entry) => total + Buffer.byteLength(entry.kind) + Buffer.byteLength(entry.path),
+    0,
+  );
+  // Count entries as well as returned text so empty modules stay bounded too.
+  // Oversized foreign input is still rejected by the caller's own import bound.
+  if (imports.length > 4_096 || textBytes > MAX_MEMO_TEXT_BYTES) return imports;
+  while (importsMemo.size >= MAX_MEMO_ENTRIES
+    || memoTextBytes + textBytes > MAX_MEMO_TEXT_BYTES) {
+    const oldest = importsMemo.entries().next().value;
+    if (oldest === undefined) break;
+    importsMemo.delete(oldest[0]);
+    memoTextBytes -= oldest[1].textBytes;
+  }
+  importsMemo.set(key, { imports, textBytes });
+  memoTextBytes += textBytes;
+  return imports;
+}

package/src/provider-plugin-module-analysis.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { extname } from "node:path";
 import ts from "typescript";
 
@@ -8,6 +9,12 @@ const opaqueModuleLoaderNames = new Set([
   "getBuiltinModule",
 ]);
 
+// Only a boolean is retained, keyed by the freshly supplied source and every
+// parser input. Filename is included because the source-local binding proof
+// creates a TypeScript program. No AST, path resolution, or authority is cached.
+const nonLiteralLoadMemo = new Map<string, boolean>();
+const MAX_NON_LITERAL_LOAD_MEMO_ENTRIES = 4_096;
+
 function hasOneLiteralModuleArgument(node: ts.CallExpression): boolean {
   const [argument] = node.arguments;
   return node.arguments.length === 1
@@ -244,12 +251,20 @@ function localEvalCallbackProof(sourceFile: ts.SourceFile): (node: ts.Node) => b
  * rather than attempting to sandbox deliberately obfuscated JavaScript.
  */
 export function hasNonLiteralModuleLoad(source: string, path: string): boolean {
+  const scriptKind = providerPluginScriptKind(path);
+  const key = createHash("sha256")
+    .update(JSON.stringify([path, scriptKind]))
+    .update("\0")
+    .update(source)
+    .digest("hex");
+  const cached = nonLiteralLoadMemo.get(key);
+  if (cached !== undefined) return cached;
   const sourceFile = ts.createSourceFile(
     path,
     source,
     ts.ScriptTarget.ESNext,
     false,
-    providerPluginScriptKind(path),
+    scriptKind,
   );
   let callbackProof: ((node: ts.Node) => boolean) | undefined;
   const isLocalCallback = (node: ts.Node): boolean => {
@@ -332,5 +347,10 @@ export function hasNonLiteralModuleLoad(source: string, path: string): boolean {
     node.forEachChild((child) => visit(child, node));
   };
   visit(sourceFile);
+  if (nonLiteralLoadMemo.size >= MAX_NON_LITERAL_LOAD_MEMO_ENTRIES) {
+    const oldest = nonLiteralLoadMemo.keys().next().value;
+    if (oldest !== undefined) nonLiteralLoadMemo.delete(oldest);
+  }
+  nonLiteralLoadMemo.set(key, found);
   return found;
 }

package/src/provider-plugin-registry.ts

@@ -24,6 +24,7 @@ import {
   sep,
 } from "node:path";
 import ts from "typescript";
+import { scanProviderPluginValueImports } from "./provider-plugin-import-analysis";
 import {
   hasNonLiteralModuleLoad,
   providerPluginScriptKind,
@@ -540,10 +541,6 @@ function readDependencySourceFromDisk(path: string): Buffer {
   );
 }
 
-const providerPluginImportScanners = Object.freeze({
-  js: new Bun.Transpiler({ loader: "js" }),
-  ts: new Bun.Transpiler({ loader: "ts" }),
-});
 const providerPluginModuleExtensions = new Set([
   ".cjs",
   ".cts",
@@ -698,11 +695,10 @@ function valueImports(source: string, path: string): readonly {
       `provider plugin implementation module ${path} uses configuration-dependent JSX or TSX; publish deterministic JavaScript or TypeScript instead`,
     );
   }
-  const scanner =
+  const loader =
     extension === ".ts" || extension === ".mts" || extension === ".cts"
-      ? providerPluginImportScanners.ts
-      : providerPluginImportScanners.js;
-  return scanner.scanImports(moduleSource);
+      ? "ts" : "js";
+  return scanProviderPluginValueImports(moduleSource, loader);
 }