@hraness/ghostget 0.17.2

package/src/confirmed-write-program.ts

@@ -0,0 +1,224 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Either from "effect/Either";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import { canonicalJson } from "./canonical-json";
+import { ConfirmedWriteFailure, confirmedWriteFinally, type ConfirmedWritePhase } from "./confirmed-write-failure";
+import { ConfirmedWritePlatform } from "./confirmed-write-platform";
+import type { RunPreparedOptions } from "./confirmed-write-model";
+import type { PreparedInvocation, StoredPlan, InvocationResult } from "./runtime";
+
+type Platform = Effect.Effect.Success<typeof ConfirmedWritePlatform>;
+type Execution = Effect.Effect.Success<ReturnType<Platform["execution"]>>;
+
+const refuse = (phase: ConfirmedWritePhase, message: string) =>
+  Effect.fail(new ConfirmedWriteFailure({ phase, cause: new Error(message) }));
+const wrapped = (failure: ConfirmedWriteFailure, message: string) =>
+  Effect.fail(new ConfirmedWriteFailure({
+    phase: failure.phase, cause: new Error(message, { cause: failure.cause }),
+    priorCause: Cause.fail(failure),
+  }));
+
+/** The best-effort repair cannot replace the existing selected error. */
+function finalizePreDispatchFailure(state: Execution, message: string) {
+  return Effect.gen(function*() {
+    if (!state.journalTerminal) {
+      yield* state.record({ type: "finished", status: "failed", finalOrigin: null, error: message, at: yield* state.clock() });
+    }
+    yield* state.projectJournal;
+    yield* state.refreshReceipt;
+  }).pipe(Effect.either, Effect.asVoid);
+}
+
+function prepareAndExecute(
+  platform: Platform, invocation: PreparedInvocation, digest: string, options: RunPreparedOptions,
+): Effect.Effect<InvocationResult, ConfirmedWriteFailure> {
+  return Effect.gen(function*() {
+    const checked = yield* platform.checkExecution(invocation, options);
+    if (checked.operation.risk === "R4") return yield* refuse("confirmation", "R4 capabilities are blocked by wrench");
+    const claims = yield* platform.repairClaims;
+    const journals = yield* platform.repairJournals(yield* platform.currentTime(options));
+    if (claims.invalid > 0 || journals.issues.length > 0) {
+      return yield* refuse("confirmation", "local execution recovery has unresolved state; run ghostget doctor before starting another write");
+    }
+    const state = yield* platform.execution(checked, digest, options);
+    const requestJournal = yield* state.journalRequest;
+    const created = yield* Effect.either(state.createJournal(requestJournal));
+    if (Either.isLeft(created)) {
+      return yield* confirmedWriteFinally(Effect.fail(created.left), state.releaseClaim);
+    }
+    if (!(yield* state.removePlan)) {
+      yield* confirmedWriteFinally(Effect.gen(function*() {
+        yield* state.record({ type: "finished", status: "failed", finalOrigin: null, error: "confirmation ownership was lost before plan consumption", at: state.startedAt });
+        yield* state.projectJournal;
+      }), state.releaseClaim);
+      return yield* refuse("confirmation", "confirmation plan was already consumed or cancelled");
+    }
+    const consumed = yield* Effect.either(state.record({ type: "confirmation-consumed", at: state.startedAt }));
+    if (Either.isLeft(consumed)) return yield* wrapped(consumed.left,
+      "confirmation plan was consumed, but its run journal could not claim ownership; run ghostget doctor before retrying");
+    if (!(yield* state.releaseClaim)) {
+      yield* Effect.either(Effect.gen(function*() {
+        yield* state.record({ type: "finished", status: "failed", finalOrigin: null, error: "confirmation ownership claim changed before release", at: state.startedAt });
+        yield* state.projectJournal;
+      })).pipe(Effect.asVoid);
+      return yield* refuse("confirmation", "confirmation ownership claim changed unexpectedly; run ghostget doctor before retrying");
+    }
+    yield* state.refreshReceipt;
+    const provisional = yield* Effect.either(state.persistProvisional);
+    if (Either.isLeft(provisional)) {
+      yield* Effect.either(Effect.gen(function*() {
+        yield* state.record({
+          type: "finished", status: "failed", finalOrigin: null,
+          error: "provisional receipt could not be projected before dispatch", at: yield* state.clock()
+        });
+      })).pipe(Effect.asVoid);
+      return yield* wrapped(provisional.left, "refusing to start execution because its provisional receipt could not be stored");
+    }
+    const request = yield* state.ledgerRequest;
+    const ledger = yield* Effect.either(state.acquireLedger(request));
+    if (Either.isLeft(ledger)) {
+      yield* finalizePreDispatchFailure(state, "idempotency state could not be inspected before dispatch");
+      return yield* wrapped(ledger.left, "refusing to start a remote write because its idempotency state could not be inspected");
+    }
+    const acquired = ledger.right;
+    if (!acquired.acquired) {
+      yield* finalizePreDispatchFailure(state, "another run already owns this idempotency scope");
+      if (acquired.existing.inputHash !== state.inputHash || acquired.existing.adapterHash !== state.adapter.hash || acquired.existing.authHash !== state.auth.hash) {
+        return yield* refuse("journal", "idempotency key was already used in a different action scope");
+      }
+      if (acquired.existing.status === "succeeded") return {
+        receipt: yield* state.readReceipt(acquired.existing.runId), output: null, replayed: true, privateArtifactsPreserved: false,
+      };
+      return yield* refuse("journal", `a prior attempt (${acquired.existing.runId}) may have reached the provider; inspect 'ghostget runs show ${acquired.existing.runId}' and reconcile it before retrying`);
+    }
+    const claimed = yield* Effect.either(Effect.gen(function*() {
+      yield* state.record({ type: "ledger-claimed", ledgerRelativePath: yield* state.ledgerRelativePath(acquired.snapshot.path), at: yield* state.clock() });
+    }));
+    if (Either.isLeft(claimed)) {
+      yield* finalizePreDispatchFailure(state, "idempotency claim could not be bound to the run journal");
+      return yield* wrapped(claimed.left, "refusing to start a remote write because its run journal could not claim the idempotency ledger");
+    }
+    const recovery = yield* Effect.either(Effect.gen(function*() {
+      yield* state.storeCapsule;
+      yield* state.record({ type: "recovery-stored", at: yield* state.clock() });
+      yield* state.refreshReceipt;
+    }));
+    if (Either.isLeft(recovery)) {
+      yield* finalizePreDispatchFailure(state, "encrypted recovery state could not be made durable before dispatch");
+      return yield* wrapped(recovery.left, "refusing to start a remote write because its encrypted recovery capsule could not be stored");
+    }
+    const maxOutputBytes = yield* state.outputLimit;
+    const dispatched = yield* Effect.either(state.dispatch);
+    const projected = yield* state.projectExecution(Either.isRight(dispatched)
+      ? { status: "fulfilled", value: dispatched.right }
+      : { status: "rejected", reason: dispatched.left.cause }, maxOutputBytes);
+    const terminal = yield* Effect.either(state.record(projected.terminalEvent));
+    if (Either.isLeft(terminal)) yield* Effect.either(state.reloadJournal).pipe(Effect.asVoid);
+    if (state.journalTerminal) yield* Effect.either(state.projectJournal).pipe(Effect.asVoid);
+    return yield* state.result(projected.result);
+  });
+}
+
+/** Admission and actual physical cleanup belong to the same program as dispatch. */
+function withWriteAdmission(
+  platform: Platform, invocation: PreparedInvocation, digest: string, options: RunPreparedOptions,
+): Effect.Effect<InvocationResult, ConfirmedWriteFailure> {
+  return Effect.gen(function*() {
+    const selected = yield* platform.admission(invocation, options);
+    if (selected.cleanupIdentity !== null) {
+      const admission = yield* platform.acquireWeb(selected.cleanupIdentity, options.now);
+      const settlement = yield* Effect.exit(Effect.gen(function*() {
+        const outcome = yield* Effect.exit(prepareAndExecute(platform, selected.invocation, digest,
+          { ...selected.options, registerCleanupBarrier: admission.registerCleanupBarrier }));
+        const cleanup = Effect.gen(function*() {
+          yield* platform.cleanup(admission.closeRegistration);
+          const joined = yield* Effect.all(admission.barriers.map(barrier =>
+            Effect.either(platform.nativeCleanup(() => barrier))), { concurrency: "unbounded" });
+          yield* platform.cleanup(() => {
+            if (joined.some(Either.isLeft)) admission.cleanupUnsafe();
+            else { admission.cleanupComplete(); admission.release(); }
+          });
+        });
+        return yield* confirmedWriteFinally(outcome, cleanup);
+      }));
+      if (Exit.isFailure(settlement)) {
+        return yield* confirmedWriteFinally(settlement, platform.cleanup(() => {
+          admission.closeRegistration();
+          if (admission.current.claim.containment.status === "parent-owned") { admission.cleanupComplete(); admission.release(); }
+        }));
+      }
+      return settlement.value;
+    }
+    if (selected.portableIdentity !== null) {
+      const owned = yield* platform.acquirePortable(selected.portableIdentity, selected.options.runId, options.now);
+      const outcome = yield* Effect.exit(prepareAndExecute(platform, selected.invocation, digest, selected.options));
+      const cleanup = yield* Effect.exit(Effect.gen(function*() {
+        yield* platform.cleanup(owned.context.closeRegistration);
+        yield* platform.nativeCleanup(owned.context.join);
+        yield* platform.cleanup(owned.context.complete);
+      }));
+      if (Exit.isFailure(cleanup)) {
+        // A failed physical proof never releases the durable lease.
+        return yield* confirmedWriteFinally(confirmedWriteFinally(outcome, cleanup),
+          platform.cleanup(() => {
+            const selected = Cause.failureOption(cleanup.cause);
+            owned.context.unsafe(Option.isSome(selected) ? selected.value.cause : Cause.squash(cleanup.cause));
+          }));
+      }
+      return yield* confirmedWriteFinally(outcome, platform.cleanup(owned.release));
+    }
+    return yield* prepareAndExecute(platform, selected.invocation, digest, selected.options);
+  });
+}
+
+export function confirmedWriteProgram(digest: string): Effect.Effect<InvocationResult, ConfirmedWriteFailure, ConfirmedWritePlatform> {
+  return Effect.gen(function*() {
+    const platform = yield* ConfirmedWritePlatform;
+    const initial = yield* platform.initialPlan(digest);
+    if (initial.plan.messagingComposite !== undefined) return yield* refuse("confirmation",
+      "messaging composite execution is unavailable until a reviewed provider executor is installed");
+    const configured = yield* platform.configure;
+    const claims = yield* platform.repairClaims;
+    const journals = yield* platform.repairJournals(configured.observedAt);
+    if (claims.invalid > 0 || journals.issues.length > 0) return yield* refuse("confirmation",
+      "local execution recovery has unresolved state; run ghostget doctor before confirming");
+    const runId = yield* platform.newRunId;
+    const claim = yield* platform.claim(digest, runId, configured.observedAt);
+    let stored: StoredPlan | null = null;
+    let invocation: PreparedInvocation | null = null;
+    const selected = yield* confirmedWriteFinally(Effect.gen(function*() {
+      stored = yield* platform.initialPlan(digest);
+      invocation = yield* platform.freshPlan(stored, configured.registry, configured.observedAt);
+      if (stored.plan.duplicateRisk !== undefined) {
+        const current = yield* platform.duplicateRisk(stored);
+        if (current === undefined || canonicalJson(current) !== canonicalJson(stored.plan.duplicateRisk)) {
+          return yield* refuse("confirmation", "duplicate-risk source evidence changed after preview; inspect the source run and preview again");
+        }
+      }
+      return { stored, invocation };
+    }), Effect.gen(function*() {
+      // Preserve the existing duplicate-risk mismatch witness: invocation has
+      // already been assigned, so this branch deliberately retains its claim.
+      if (invocation === null && stored !== null) {
+        if (yield* platform.removePlan(digest)) {
+          if (!(yield* platform.retainingJournal(digest))) yield* platform.cleanupAssets(digest);
+        }
+        yield* platform.releaseClaim(claim);
+      } else if (invocation === null) yield* platform.releaseClaim(claim);
+    }));
+    let started = false;
+    return yield* confirmedWriteFinally(Effect.gen(function*() {
+      const prepared = yield* platform.prepareOptions(selected.invocation, selected.stored, claim, runId, configured.registry);
+      started = true;
+      return yield* withWriteAdmission(platform, selected.invocation, digest, prepared);
+    }), Effect.gen(function*() {
+      if (!started) {
+        yield* platform.removePlan(digest);
+        if (!(yield* platform.retainingJournal(digest))) yield* platform.cleanupAssets(digest);
+      }
+      yield* platform.releaseClaim(claim);
+    }));
+  }).pipe(Effect.uninterruptible);
+}

package/src/confirmed-write-runtime.ts

@@ -0,0 +1,16 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import type { ConfirmedWriteFailure } from "./confirmed-write-failure";
+
+/** The only interpreter for a closed, complete confirmed-write invocation. */
+export async function runConfirmedWrite<A>(
+  program: Effect.Effect<A, ConfirmedWriteFailure>,
+): Promise<A> {
+  const exit = await Effect.runPromiseExit(program.pipe(Effect.uninterruptible));
+  if (Exit.isSuccess(exit)) return exit.value;
+  const selected = Cause.failureOption(exit.cause);
+  if (Option.isSome(selected)) throw selected.value.cause;
+  throw Cause.squash(exit.cause);
+}

package/src/cursor-token.ts

@@ -0,0 +1,228 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+} from "node:crypto";
+import { join } from "node:path";
+
+import { canonicalJson } from "./canonical-json";
+import {
+  createPrivateJsonIfAbsent,
+  readRegularFile,
+  ghostgetStateHome,
+} from "./storage";
+
+const TOKEN_VERSION = "smn1";
+const TOKEN_PREFIX = `${TOKEN_VERSION}.`;
+const KEY_FILE_NAME = ".cursor-encryption-key";
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+const MAX_KEY_FILE_BYTES = 128;
+const MAX_TOKEN_CHARACTERS = 8192;
+const MAX_ENVELOPE_BYTES = Math.floor(
+  ((MAX_TOKEN_CHARACTERS - TOKEN_PREFIX.length) * 3) / 4,
+);
+const MAX_PLAINTEXT_BYTES = MAX_ENVELOPE_BYTES - IV_BYTES - AUTH_TAG_BYTES;
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+function invalidToken(message: "authentication failed" | "is malformed"): Error {
+  return new Error(`cursor token ${message}`);
+}
+
+function validateCoordinates(
+  scope: string,
+  authId: string,
+  authHash: string,
+): void {
+  if (
+    typeof scope !== "string"
+    || !/^[a-z][a-z0-9-]{0,47}$/u.test(scope)
+  ) {
+    throw new Error("cursor-token scope must be lowercase kebab-case");
+  }
+  if (
+    typeof authId !== "string"
+    || !/^[a-z][a-z0-9-]{0,47}$/u.test(authId)
+  ) {
+    throw new Error("cursor-token auth ID must be lowercase kebab-case");
+  }
+  if (
+    typeof authHash !== "string"
+    || !/^[a-f0-9]{64}$/u.test(authHash)
+  ) {
+    throw new Error("cursor-token auth hash is malformed");
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function keyPath(environment: Environment): string {
+  return join(ghostgetStateHome(environment), KEY_FILE_NAME);
+}
+
+function cursorEncryptionKey(
+  environment: Environment,
+  createIfMissing: boolean,
+): Buffer {
+  const path = keyPath(environment);
+  if (createIfMissing) {
+    createPrivateJsonIfAbsent(path, {
+      schemaVersion: 1,
+      key: randomBytes(KEY_BYTES).toString("hex"),
+    }, {
+      environment,
+      privateParent: true,
+    });
+  }
+  const text = readRegularFile(path, MAX_KEY_FILE_BYTES, "cursor encryption key");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text) as unknown;
+  } catch {
+    throw new Error("cursor encryption key is malformed");
+  }
+  if (
+    !isRecord(parsed)
+    || Object.keys(parsed).sort().join(",") !== "key,schemaVersion"
+    || parsed.schemaVersion !== 1
+    || typeof parsed.key !== "string"
+    || !/^[a-f0-9]{64}$/u.test(parsed.key)
+  ) {
+    throw new Error("cursor encryption key is malformed");
+  }
+  return Buffer.from(parsed.key, "hex");
+}
+
+function additionalData(
+  scope: string,
+  authId: string,
+  authHash: string,
+): Buffer {
+  return Buffer.from(
+    `io-cursor-token\0${TOKEN_VERSION}\0${scope}\0${authId}\0${authHash}`,
+    "utf8",
+  );
+}
+
+function canonicalPayload(payload: unknown): Buffer {
+  let encoded: string;
+  try {
+    encoded = canonicalJson(payload);
+  } catch {
+    throw new Error("cursor-token payload must be JSON-compatible");
+  }
+  const bytes = Buffer.from(encoded, "utf8");
+  if (bytes.byteLength > MAX_PLAINTEXT_BYTES) {
+    throw new Error("cursor-token payload exceeds its size bound");
+  }
+  return bytes;
+}
+
+function decodeEnvelope(token: string): {
+  readonly ciphertext: Buffer;
+  readonly iv: Buffer;
+  readonly tag: Buffer;
+} {
+  if (
+    typeof token !== "string"
+    || token.length > MAX_TOKEN_CHARACTERS
+    || !token.startsWith(TOKEN_PREFIX)
+  ) {
+    throw invalidToken("is malformed");
+  }
+  const encoded = token.slice(TOKEN_PREFIX.length);
+  if (encoded === "" || /[^A-Za-z0-9_-]/u.test(encoded)) {
+    throw invalidToken("is malformed");
+  }
+  let envelope: Buffer;
+  try {
+    envelope = Buffer.from(encoded, "base64url");
+  } catch {
+    throw invalidToken("is malformed");
+  }
+  if (
+    envelope.toString("base64url") !== encoded
+    || envelope.byteLength <= IV_BYTES + AUTH_TAG_BYTES
+    || envelope.byteLength > MAX_ENVELOPE_BYTES
+  ) {
+    throw invalidToken("is malformed");
+  }
+  return {
+    iv: envelope.subarray(0, IV_BYTES),
+    ciphertext: envelope.subarray(IV_BYTES, -AUTH_TAG_BYTES),
+    tag: envelope.subarray(-AUTH_TAG_BYTES),
+  };
+}
+
+export function sealCursorToken(
+  scope: string,
+  authId: string,
+  authHash: string,
+  payload: unknown,
+  environment: Environment = process.env,
+): string {
+  validateCoordinates(scope, authId, authHash);
+  const plaintext = canonicalPayload(payload);
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv(
+    "aes-256-gcm",
+    cursorEncryptionKey(environment, true),
+    iv,
+  );
+  cipher.setAAD(additionalData(scope, authId, authHash));
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const envelope = Buffer.concat([iv, ciphertext, cipher.getAuthTag()]);
+  const token = `${TOKEN_PREFIX}${envelope.toString("base64url")}`;
+  if (token.length > MAX_TOKEN_CHARACTERS) {
+    throw new Error("cursor-token payload exceeds its size bound");
+  }
+  return token;
+}
+
+export function openCursorToken(
+  scope: string,
+  authId: string,
+  authHash: string,
+  token: string,
+  environment: Environment = process.env,
+): unknown {
+  validateCoordinates(scope, authId, authHash);
+  const { ciphertext, iv, tag } = decodeEnvelope(token);
+  let plaintext: Buffer;
+  try {
+    const decipher = createDecipheriv(
+      "aes-256-gcm",
+      cursorEncryptionKey(environment, false),
+      iv,
+    );
+    decipher.setAAD(additionalData(scope, authId, authHash));
+    decipher.setAuthTag(tag);
+    plaintext = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final(),
+    ]);
+  } catch {
+    throw invalidToken("authentication failed");
+  }
+  if (plaintext.byteLength > MAX_PLAINTEXT_BYTES) {
+    throw invalidToken("is malformed");
+  }
+  let text: string;
+  let payload: unknown;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(plaintext);
+    payload = JSON.parse(text) as unknown;
+  } catch {
+    throw invalidToken("is malformed");
+  }
+  try {
+    if (canonicalJson(payload) !== text) throw invalidToken("is malformed");
+  } catch {
+    throw invalidToken("is malformed");
+  }
+  return payload;
+}