@hraness/ghostget 0.17.2

package/src/provider-plugin-auth.ts

@@ -0,0 +1,36 @@
+import type { GhostgetAuth } from "./auth";
+import type {
+  ProviderPluginAuthKind,
+  ProviderPluginBindingV1,
+  ProviderPluginTransport,
+} from "./provider-plugin";
+
+export type ProviderPluginAuthBinding = {
+  readonly surfaceId: string;
+  readonly transport: ProviderPluginTransport;
+  readonly authKinds: readonly ProviderPluginAuthKind[];
+};
+
+/**
+ * Enforce the kernel-owned relationship between a resolved plugin binding and
+ * an auth locator. Plugins choose accepted auth kinds; realm-bearing locators
+ * remain bound to the exact surface that selected them.
+ */
+export function requireProviderPluginAuth(
+  binding: ProviderPluginAuthBinding | ProviderPluginBindingV1,
+  auth: GhostgetAuth,
+): void {
+  if (!binding.authKinds.includes(auth.kind)) {
+    throw new Error(
+      `provider plugin surface ${binding.surfaceId} does not accept ${auth.kind} auth`,
+    );
+  }
+  if (
+    (auth.kind === "oauth-token-file" || auth.kind === "linked-device-store")
+    && auth.provider !== binding.surfaceId
+  ) {
+    throw new Error(
+      `auth locator ${auth.id} is for ${auth.provider}, not ${binding.surfaceId}`,
+    );
+  }
+}

package/src/provider-plugin-builtins.ts

@@ -0,0 +1,229 @@
+import {
+  type ProviderContract,
+} from "./provider-contract-definitions";
+import { planProviderContractDispatches } from "./provider-contract-planning";
+import { assertContractSemanticIdentity } from "./provider-contract-semantic-identity";
+import type {
+  ProviderApiPluginOperationDefinitionV1,
+  ProviderPluginAuthKind,
+  ProviderPluginImplementationSourceDefinitionV1,
+  ProviderPluginOmniDefinitionV1,
+  WebSessionPluginOperationDefinitionV1,
+} from "./provider-plugin";
+import type { WebSessionContract } from "./web-session-contract-definitions";
+import { planWebSessionContractDispatches } from "./web-session-contract-planning";
+import type { BrowserDispatchPlan, OperationInput } from "./model";
+
+export type ProviderPluginOmniDefinitionsV1 = Readonly<
+  Record<string, ProviderPluginOmniDefinitionV1>
+>;
+
+function omniDefinition(
+  operation: string,
+  definitions: ProviderPluginOmniDefinitionsV1 | undefined,
+): { readonly omni?: ProviderPluginOmniDefinitionV1 } {
+  const inboxRead = operation === "messaging.list"
+    || operation === "messaging.read";
+  const definition = definitions?.[operation];
+  if (inboxRead && definition === undefined) {
+    throw new Error(
+      `provider operation ${operation} must explicitly declare omni normalization support`,
+    );
+  }
+  if (!inboxRead && definition !== undefined) {
+    throw new Error(
+      `provider operation ${operation} has an unexpected inbox normalization declaration`,
+    );
+  }
+  return definition === undefined ? {} : { omni: definition };
+}
+
+function assertOmniDefinitionCoverage(
+  operations: readonly string[],
+  definitions: ProviderPluginOmniDefinitionsV1 | undefined,
+): void {
+  const expected = operations.filter((operation) =>
+    operation === "messaging.list" || operation === "messaging.read")
+    .sort();
+  const actual = Object.keys(definitions ?? {}).sort();
+  if (
+    actual.length !== expected.length
+    || actual.some((operation, index) => operation !== expected[index])
+  ) {
+    throw new Error(
+      "provider omni declarations must exactly cover installed messaging list/read operations",
+    );
+  }
+}
+
+export const browserSessionAuthKinds = Object.freeze([
+  "browser-profile",
+  "cookie-source",
+  "cookies-file",
+] as const satisfies readonly ProviderPluginAuthKind[]);
+
+export const oauthTokenAuthKinds = Object.freeze([
+  "oauth-token-file",
+] as const satisfies readonly ProviderPluginAuthKind[]);
+
+export const linkedDeviceAuthKinds = Object.freeze([
+  "linked-device-store",
+] as const satisfies readonly ProviderPluginAuthKind[]);
+
+/**
+ * Adapt reviewed official-provider definitions into complete plugin-owned host
+ * contracts. Hooks deliberately close over one exact contract version.
+ */
+export function officialContractOperations(
+  contracts: readonly ProviderContract[],
+  options: {
+    readonly semanticIdentity: string;
+    readonly validateInput: (
+      contract: ProviderContract,
+      input: OperationInput,
+    ) => readonly string[];
+    readonly validateSubjectInput?: (
+      contract: ProviderContract,
+      input: OperationInput,
+      subject: string,
+    ) => readonly string[];
+    readonly omni?: ProviderPluginOmniDefinitionsV1;
+  },
+): readonly ProviderApiPluginOperationDefinitionV1[] {
+  assertOmniDefinitionCoverage(
+    contracts.map((contract) => contract.operation),
+    options.omni,
+  );
+  assertContractSemanticIdentity(
+    contracts[0]?.provider ?? "official provider",
+    contracts,
+    options.semanticIdentity,
+  );
+  const validateSubjectInput = options.validateSubjectInput;
+  return Object.freeze(contracts.map((contract) => Object.freeze({
+    name: contract.operation,
+    contractVersion: contract.contractVersion,
+    risk: contract.risk,
+    input: contract.input,
+    sideEffect: contract.sideEffect,
+    idempotency: contract.idempotency,
+    dedupeWindowMs: contract.dedupeWindowMs,
+    state: contract.state,
+    dispatch: contract.dispatch,
+    implementation: contract.implementation,
+    requiredScopeSets: contract.requiredScopeSets,
+    coverage: contract.coverage,
+    planDispatches: (input: OperationInput) =>
+      planProviderContractDispatches(contract, input),
+    validateInput: (input: OperationInput) =>
+      options.validateInput(contract, input),
+    ...omniDefinition(contract.operation, options.omni),
+    ...(validateSubjectInput === undefined
+      ? {}
+      : {
+        validateSubjectInput: (input: OperationInput, subject: string) =>
+          validateSubjectInput(contract, input, subject),
+      }),
+  })));
+}
+
+/**
+ * Adapt reviewed authenticated-session definitions into complete plugin-owned
+ * host contracts. Conditional input laws are encoded in the exact input schema.
+ */
+export function webSessionContractOperations(
+  contracts: readonly WebSessionContract[],
+  semanticIdentity: string,
+  historicalVersions: Readonly<Record<string, readonly number[]>> = {},
+  omni?: ProviderPluginOmniDefinitionsV1,
+  planners: Readonly<Record<string, (input: OperationInput) => readonly BrowserDispatchPlan[]>> = {},
+): readonly WebSessionPluginOperationDefinitionV1[] {
+  assertOmniDefinitionCoverage(
+    contracts.map((contract) => contract.operation),
+    omni,
+  );
+  assertContractSemanticIdentity(
+    contracts[0]?.site ?? "authenticated session",
+    contracts,
+    semanticIdentity,
+  );
+  const installedOperations = new Set(contracts.map((contract) => contract.operation));
+  for (const operation of Object.keys(planners)) {
+    if (!installedOperations.has(operation)) {
+      throw new Error(`provider dispatch planner references uninstalled operation ${operation}`);
+    }
+  }
+  return Object.freeze(contracts.map((contract) => Object.freeze({
+    name: contract.operation,
+    contractVersion: contract.contractVersion,
+    ...(historicalVersions[contract.operation] === undefined
+      ? {}
+      : { historicalContractVersions: historicalVersions[contract.operation] }),
+    risk: contract.risk,
+    input: contract.input,
+    sideEffect: contract.sideEffect,
+    idempotency: contract.idempotency,
+    dedupeWindowMs: contract.dedupeWindowMs,
+    state: contract.state,
+    dispatch: contract.dispatch,
+    implementation: contract.implementation,
+    planDispatches: planners[contract.operation] ?? ((input: OperationInput) =>
+      planWebSessionContractDispatches(contract, input)),
+    validateInput: () => Object.freeze([]),
+    ...omniDefinition(contract.operation, omni),
+  })));
+}
+
+function source(
+  base: string,
+  label: string,
+  relativePath: string,
+): ProviderPluginImplementationSourceDefinitionV1 {
+  return Object.freeze({ label, url: new URL(relativePath, base) });
+}
+
+/**
+ * Declare one trusted source-plugin entrypoint. The registry derives and binds
+ * its complete eager and lazy value-dependency closure automatically.
+ */
+export function providerImplementationEntry(
+  base: string,
+): readonly ProviderPluginImplementationSourceDefinitionV1[] {
+  return Object.freeze([source(base, "plugin.ts", "./plugin.ts")]);
+}
+
+export function officialImplementationSources(
+  base: string,
+  implementation: "linkedin" | "x",
+): readonly ProviderPluginImplementationSourceDefinitionV1[] {
+  return Object.freeze([
+    source(base, "plugin.ts", "./plugin.ts"),
+    source(base, "kernel/provider-plugin-builtins.ts", "../../provider-plugin-builtins.ts"),
+    source(base, "kernel/provider-contract-planning.ts", "../../provider-contract-planning.ts"),
+    source(base, "kernel/provider-contract-semantic-identity.ts", "../../provider-contract-semantic-identity.ts"),
+    source(base, "kernel/provider-context.ts", "../../provider-context.ts"),
+    source(base, "kernel/provider-subject.ts", "../../provider-subject.ts"),
+    source(base, `contracts/${implementation}-input.ts`, `../../provider-contract-input-${implementation}.ts`),
+    source(base, "kernel/provider-http.ts", "../../provider-http.ts"),
+    source(base, "kernel/operation-deadline.ts", "../../operation-deadline.ts"),
+    source(base, `providers/${implementation}.ts`, `../../providers/${implementation}.ts`),
+  ]);
+}
+
+export function webImplementationSources(
+  base: string,
+  providerSources: readonly (readonly [label: string, relativePath: string])[],
+): readonly ProviderPluginImplementationSourceDefinitionV1[] {
+  return Object.freeze([
+    source(base, "plugin.ts", "./plugin.ts"),
+    source(base, "kernel/provider-plugin-builtins.ts", "../../provider-plugin-builtins.ts"),
+    source(base, "kernel/provider-contract-semantic-identity.ts", "../../provider-contract-semantic-identity.ts"),
+    source(base, "kernel/web-session-contract-planning.ts", "../../web-session-contract-planning.ts"),
+    source(base, "kernel/canonical-json.ts", "../../canonical-json.ts"),
+    source(base, "kernel/web-session-execution.ts", "../../web-session-execution.ts"),
+    source(base, "kernel/web-session-client.ts", "../../web-session-client.ts"),
+    source(base, "kernel/operation-deadline.ts", "../../operation-deadline.ts"),
+    source(base, "kernel/pinned-https.ts", "../../pinned-https.ts"),
+    ...providerSources.map(([label, relativePath]) => source(base, label, relativePath)),
+  ]);
+}

package/src/provider-plugin-cleanup-barrier.ts

@@ -0,0 +1,229 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import type { ProcessOwnerIdentity } from "./process-identity";
+
+export type PortableProviderPluginCleanupContainment = {
+  readonly hostStarting: (host: ProcessOwnerIdentity) => void;
+  readonly hostStarted: (host: ProcessOwnerIdentity) => void;
+  readonly cleanupUnsafe: (cause?: unknown) => void;
+};
+
+type CleanupBarrierScope = {
+  readonly barriers: Promise<void>[];
+  readonly containment?: PortableProviderPluginCleanupContainment;
+  accepting: boolean;
+};
+
+export type PortableProviderPluginCleanupBarrier = {
+  readonly settled: boolean;
+  readonly verified: () => void;
+  readonly unsafe: (cause?: unknown) => void;
+};
+
+export type PortableProviderPluginOperationOutcome<T> =
+  | {
+      readonly status: "fulfilled";
+      readonly value: T;
+    }
+  | {
+      readonly status: "rejected";
+      readonly reason: unknown;
+    };
+
+/**
+ * Cleanup safety is intentionally separate from the provider result. A
+ * provider failure can be safely quiescent; an unverified cleanup cannot.
+ */
+export class PortableProviderPluginCleanupUnverifiedError extends Error {
+  constructor(cause?: unknown) {
+    super(
+      "portable provider plugin cleanup could not be verified; its invocation lease was preserved",
+      cause === undefined ? undefined : { cause },
+    );
+    this.name = "PortableProviderPluginCleanupUnverifiedError";
+  }
+}
+
+const cleanupBarrierStorage = new AsyncLocalStorage<CleanupBarrierScope>();
+
+/**
+ * Register cleanup work in the current exact invocation-lease scope. The
+ * handle is still useful outside a scope, but no global state is retained.
+ */
+export function registerPortableProviderPluginCleanupBarrier():
+  PortableProviderPluginCleanupBarrier {
+  const scope = cleanupBarrierStorage.getStore();
+  if (scope?.accepting === false) {
+    throw new Error(
+      "portable provider plugin cleanup registration began after its operation scope closed",
+    );
+  }
+  let settled = false;
+  let resolveBarrier: (() => void) | undefined;
+  let rejectBarrier: ((cause: unknown) => void) | undefined;
+  if (scope !== undefined) {
+    const barrier = new Promise<void>((resolve, reject) => {
+      resolveBarrier = resolve;
+      rejectBarrier = reject;
+    });
+    // Cleanup may fail before the lease owner reaches its join gate. Observe
+    // the rejection immediately while retaining the original promise for the
+    // fail-closed allSettled join.
+    void barrier.catch(() => undefined);
+    scope.barriers.push(barrier);
+  }
+  const handle: PortableProviderPluginCleanupBarrier = {
+    get settled() {
+      return settled;
+    },
+    verified: () => {
+      if (settled) return;
+      settled = true;
+      resolveBarrier?.();
+    },
+    unsafe: (cause?: unknown) => {
+      if (settled) return;
+      settled = true;
+      let unsafeCause: unknown = cause ?? new Error(
+        "portable provider plugin cleanup was not verified",
+      );
+      try {
+        scope?.containment?.cleanupUnsafe(unsafeCause);
+      } catch (error) {
+        unsafeCause = error;
+      }
+      rejectBarrier?.(unsafeCause);
+    },
+  };
+  return Object.freeze(handle);
+}
+
+/**
+ * Announce the exact admission-gated host before portable code is allowed to
+ * execute. A lease-backed scope persists this identity synchronously.
+ */
+export function announcePortableProviderPluginHostStarting(
+  host: ProcessOwnerIdentity,
+): void {
+  cleanupBarrierStorage.getStore()?.containment?.hostStarting(host);
+}
+
+/**
+ * Announce that the already-bound host crossed its admission gate.
+ */
+export function announcePortableProviderPluginHostStarted(
+  host: ProcessOwnerIdentity,
+): void {
+  cleanupBarrierStorage.getStore()?.containment?.hostStarted(host);
+}
+
+/**
+ * Keep a host promise in the lease scope even when an outer operation
+ * deadline has already returned a terminal outcome. A real host separately
+ * reports whether its cleanup was safe; a test or alternate host's settled
+ * promise is its cleanup boundary.
+ */
+export function trackPortableProviderPluginHostCompletion<T>(
+  host: Promise<T>,
+): Promise<T> {
+  const barrier = registerPortableProviderPluginCleanupBarrier();
+  void host.then(
+    () => barrier.verified(),
+    () => barrier.verified(),
+  );
+  return host;
+}
+
+async function awaitCleanupBarriers(
+  scope: CleanupBarrierScope,
+): Promise<void> {
+  const failures: unknown[] = [];
+  let joined = 0;
+  for (;;) {
+    const pending = scope.barriers.slice(joined);
+    joined = scope.barriers.length;
+    if (pending.length > 0) {
+      const results = await Promise.allSettled(pending);
+      for (const result of results) {
+        if (result.status === "rejected") failures.push(result.reason);
+      }
+      continue;
+    }
+    // Give descendants resumed by the last barrier one microtask to register
+    // their own narrower cleanup boundary before declaring quiescence.
+    await Promise.resolve();
+    if (joined === scope.barriers.length) break;
+  }
+  if (failures.length > 0) {
+    throw new PortableProviderPluginCleanupUnverifiedError(failures[0]);
+  }
+}
+
+/** One native context, shared by a program's individually admitted foreign calls. */
+export function createPortableProviderPluginCleanupContext(options: {
+  readonly containment?: PortableProviderPluginCleanupContainment;
+  readonly cleanupComplete?: () => void;
+} = {}) {
+  const parentScope = cleanupBarrierStorage.getStore();
+  const parentJoin = parentScope === undefined
+    ? undefined
+    : registerPortableProviderPluginCleanupBarrier();
+  const containment = options.containment ?? parentScope?.containment;
+  const scope: CleanupBarrierScope = {
+    barriers: [], accepting: true,
+    ...(containment === undefined ? {} : { containment }),
+  };
+  return Object.freeze({
+    run: <A>(operation: () => A): A => cleanupBarrierStorage.run(scope, operation),
+    closeRegistration: () => { scope.accepting = false; },
+    join: () => awaitCleanupBarriers(scope),
+    complete: () => { options.cleanupComplete?.(); parentJoin?.verified(); },
+    unsafe: (cause: unknown) => { scope.accepting = false; parentJoin?.unsafe(cause); },
+  });
+}
+
+/**
+ * Settle an operation independently from its cleanup join. Callers may publish
+ * an ordinary provider failure, but may release the exact durable lease only
+ * after this function returns an outcome.
+ */
+export async function settlePortableProviderPluginCleanup<T>(
+  operation: () => Promise<T>,
+  options: {
+    readonly containment?: PortableProviderPluginCleanupContainment;
+    /**
+     * Persist the outer lease owner's cleanup-complete transition only after
+     * every barrier in this exact scope has joined successfully.
+     */
+    readonly cleanupComplete?: () => void;
+  } = {},
+): Promise<PortableProviderPluginOperationOutcome<T>> {
+  const context = createPortableProviderPluginCleanupContext(options);
+  try {
+    const outcome = await context.run(
+      async (): Promise<PortableProviderPluginOperationOutcome<T>> => {
+        try {
+          return Object.freeze({
+            status: "fulfilled" as const,
+            value: await operation(),
+          });
+        } catch (reason) {
+          return Object.freeze({
+            status: "rejected" as const,
+            reason,
+          });
+        }
+      },
+    );
+    // Resource owners must register their barrier before starting the
+    // resource. Once the operation settles, descendants may finish already
+    // registered cleanup but cannot introduce a late unjoined boundary.
+    context.closeRegistration();
+    await context.join();
+    context.complete();
+    return outcome;
+  } catch (error) {
+    context.unsafe(error);
+    throw error;
+  }
+}

package/src/provider-plugin-cleanup-execution.ts

@@ -0,0 +1,79 @@
+import type { ProviderPluginCleanupResourceIdentity } from "./provider-plugin-cleanup-resource";
+
+export type ProviderPluginCleanupResourcePublisher = (
+  resource: ProviderPluginCleanupResourceIdentity,
+) => void;
+
+export type ProviderPluginCleanupBarrierRegistrar = (
+  barrier: Promise<void>,
+) => ProviderPluginCleanupResourcePublisher | void;
+
+export type ProviderPluginCleanupProofController = {
+  /** Call only after every published process/resource is exactly quiescent. */
+  readonly verified: () => void;
+  /** Preserve durable admission when exact cleanup cannot be proved. */
+  readonly unsafe: (reason: unknown) => void;
+};
+
+/**
+ * Register cleanup before starting resource-owning asynchronous work. If the
+ * durable registrar has closed, `start` is never called.
+ */
+export function startProviderPluginCleanupTrackedOperation<T>(
+  register: ProviderPluginCleanupBarrierRegistrar | undefined,
+  start: (
+    publishCleanupResource: ProviderPluginCleanupResourcePublisher | undefined,
+    cleanup: ProviderPluginCleanupProofController,
+  ) => Promise<T>,
+): Promise<T> {
+  if (register === undefined) {
+    return start(undefined, Object.freeze({
+      verified: () => undefined,
+      unsafe: () => undefined,
+    }));
+  }
+  let resolveCleanup: (() => void) | undefined;
+  let rejectCleanup: ((reason: unknown) => void) | undefined;
+  let settled = false;
+  const cleanupBarrier = new Promise<void>((resolve, reject) => {
+    resolveCleanup = resolve;
+    rejectCleanup = reject;
+  });
+  // Prevent a rejection from becoming process-global before the outer cleanup
+  // join observes the registered barrier.
+  void cleanupBarrier.catch(() => undefined);
+  const publishCleanupResource = register(cleanupBarrier);
+  const cleanup: ProviderPluginCleanupProofController = Object.freeze({
+    verified: () => {
+      if (settled) return;
+      settled = true;
+      resolveCleanup?.();
+    },
+    unsafe: (reason) => {
+      if (settled) return;
+      settled = true;
+      rejectCleanup?.(
+        reason instanceof Error
+          ? reason
+          : new Error("provider cleanup could not be verified"),
+      );
+    },
+  });
+  try {
+    return Promise.resolve(start(
+      typeof publishCleanupResource === "function"
+        ? publishCleanupResource
+        : undefined,
+      cleanup,
+    )).catch((error: unknown) => {
+      // A runtime that rejects before it can prove cleanup must never leave an
+      // indefinitely pending barrier or accidentally release durable admission.
+      // If cleanup was already verified, the settled guard preserves that proof.
+      cleanup.unsafe(error);
+      throw error;
+    });
+  } catch (error) {
+    cleanup.unsafe(error);
+    throw error;
+  }
+}