dsh-codex-community 0.0.1

package/dist/internal/authorization-bridge.mjs

@@ -0,0 +1,662 @@
+import { randomUUID } from "node:crypto"
+
+import { AuthorizationDeclinedError } from "@deepseek-ai/dsh-authorization"
+
+import {
+  CODEX_CREDENTIAL_KEY,
+  CODEX_PROVIDER_ID,
+  createCodexCredentialStore,
+} from "./codex-credential-store.mjs"
+
+export const AUTHORIZATION_RPC_CHANNEL = "/dsh-codex"
+export const CODEX_AUTHORIZATION_KEY = CODEX_CREDENTIAL_KEY
+
+const ATTEMPT_RETENTION_MS = 5 * 60_000
+const STATUS_WAIT_MS = 25_000
+const MAX_EVENTS = 128
+const MAX_NOTICES = 32
+const MAX_ATTEMPTS = 8
+const MAX_RETAINED_ATTEMPTS = 64
+const MAX_WAITERS_PER_ATTEMPT = 8
+const MAX_METHODS = 16
+const MAX_OPTIONS = 64
+const MAX_ID_CHARS = 128
+const MAX_ANSWER_CHARS = 16_384
+const MAX_MESSAGE_CHARS = 2_048
+const MAX_PLACEHOLDER_CHARS = 512
+const MAX_CODE_CHARS = 256
+const MAX_URL_CHARS = 2_048
+
+class RpcInputError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = "RpcInputError"
+  }
+}
+
+/**
+ * A short-lived interaction adapter around the public authorization seam.
+ * It never reads a credential value: only describeRecord() presence metadata
+ * crosses the interface, while notices and prompt answers live in memory for
+ * the duration of one loopback browser interaction.
+ */
+export class CodexAuthorizationBridge {
+  #authorization
+  #credentials
+  #commitTracker
+  #quotaObserver
+  #attempts = new Map()
+  #closed = false
+  #retentionMs
+  #waitMs
+
+  constructor({ authorization, credentials }, options = {}) {
+    this.#authorization = authorization
+    this.#credentials = credentials
+    this.#commitTracker = options.commitTracker
+    this.#quotaObserver = options.quotaObserver
+    this.#retentionMs = options.retentionMs ?? ATTEMPT_RETENTION_MS
+    this.#waitMs = options.waitMs ?? STATUS_WAIT_MS
+  }
+
+  async status(payload = {}, signal) {
+    const input = objectInput(payload)
+    assertOnlyKeys(input, ["attemptId", "after"])
+    if (input.attemptId === undefined) {
+      if (input.after !== undefined) throw new RpcInputError("after requires attemptId")
+      return this.#publicStatus()
+    }
+
+    const attemptId = requiredString(input, "attemptId", { maxLength: MAX_ID_CHARS })
+    const after = optionalSequence(input.after)
+    const attempt = this.#attempt(attemptId)
+    await waitForAttempt(attempt, after, signal, this.#waitMs)
+    return {
+      attemptId,
+      events: attempt.events.filter((event) => event.seq > after),
+      nextSeq: attempt.events.at(-1)?.seq ?? after,
+      done: attempt.done,
+    }
+  }
+
+  async start(payload = {}) {
+    this.#assertOpen()
+    const input = objectInput(payload)
+    assertOnlyKeys(input, ["method"])
+    const activeAttempts = [...this.#attempts.values()].filter((attempt) => !attempt.done).length
+    if (activeAttempts >= MAX_ATTEMPTS) {
+      throw new RpcInputError("Too many authorization attempts")
+    }
+    if (this.#attempts.size >= MAX_RETAINED_ATTEMPTS) {
+      throw new RpcInputError("Too many recent authorization attempts")
+    }
+    const method = optionalString(input, "method", { maxLength: MAX_ID_CHARS })
+    const entry = this.#authorization.describe(CODEX_AUTHORIZATION_KEY)
+    if (entry === undefined) throw new RpcInputError("Codex authorization is unavailable")
+    if (method !== undefined && !entry.methods.some((candidate) => candidate.id === method)) {
+      throw new RpcInputError("Unknown Codex authorization method")
+    }
+
+    const attempt = {
+      id: randomUUID(),
+      controller: new AbortController(),
+      events: [],
+      nextSeq: 1,
+      noticeCount: 0,
+      prompt: undefined,
+      waiters: new Set(),
+      done: false,
+      cleanup: undefined,
+    }
+    this.#attempts.set(attempt.id, attempt)
+
+    void Promise.resolve().then(() => this.#authorization.begin({
+      key: CODEX_AUTHORIZATION_KEY,
+      ...(method === undefined ? {} : { method }),
+      signal: attempt.controller.signal,
+      interaction: {
+        notify: (notice) => {
+          if (!attempt.done && attempt.noticeCount < MAX_NOTICES) {
+            attempt.noticeCount += 1
+            this.#emit(attempt, {
+              type: "notice",
+              notice: serializeNotice(notice),
+            })
+          }
+        },
+        prompt: (prompt) => this.#prompt(attempt, prompt),
+      },
+    })).then(
+      (outcome) => this.#settle(attempt, {
+        type: "settled",
+        status: outcome.status,
+      }),
+      (error) => this.#settle(attempt, {
+        type: "failed",
+        error: safeAuthorizationFailure(error),
+      }),
+    )
+
+    return { attemptId: attempt.id }
+  }
+
+  respond(payload = {}) {
+    const input = objectInput(payload)
+    assertOnlyKeys(input, ["attemptId", "promptId", "action", "value"])
+    const attempt = this.#attempt(requiredString(input, "attemptId", { maxLength: MAX_ID_CHARS }))
+    const promptId = requiredString(input, "promptId", { maxLength: MAX_ID_CHARS })
+    const action = requiredString(input, "action", { maxLength: 16 })
+    const pending = attempt.prompt
+    if (pending === undefined || pending.id !== promptId) {
+      throw new RpcInputError("The authorization prompt is no longer active")
+    }
+
+    if (action === "answer") {
+      const value = requiredString(input, "value", {
+        allowEmpty: true,
+        maxLength: MAX_ANSWER_CHARS,
+      })
+      const answer = pending.mapAnswer(value)
+      this.#closePrompt(attempt, pending)
+      pending.resolve(answer)
+      return { accepted: true }
+    }
+    if (action === "decline") {
+      this.#closePrompt(attempt, pending)
+      pending.reject(new AuthorizationDeclinedError())
+      return { accepted: true }
+    }
+    throw new RpcInputError("Unknown prompt response action")
+  }
+
+  cancel(payload = {}) {
+    const input = objectInput(payload)
+    assertOnlyKeys(input, ["attemptId"])
+    const attempt = input.attemptId === undefined
+      ? undefined
+      : this.#attempt(requiredString(input, "attemptId", { maxLength: MAX_ID_CHARS }))
+    if (attempt?.done === true) return { accepted: false }
+    const cancel = () => {
+      if (attempt !== undefined) {
+        attempt.controller.abort("cancelled by the interaction surface")
+        this.#rejectPrompt(attempt, new Error("authorization cancelled"))
+      }
+      this.#authorization.cancel(CODEX_AUTHORIZATION_KEY)
+    }
+    if (this.#commitTracker?.tryCancel(cancel) === false) {
+      return { accepted: false, reason: "commit-in-progress" }
+    }
+    if (this.#commitTracker === undefined) cancel()
+    return { accepted: true }
+  }
+
+  async logout(payload = {}) {
+    const input = objectInput(payload)
+    assertOnlyKeys(input, [])
+    for (const attempt of this.#attempts.values()) {
+      if (attempt.done) continue
+      attempt.controller.abort("signed out by the interaction surface")
+      this.#rejectPrompt(attempt, new Error("authorization signed out"))
+    }
+    this.#authorization.cancel(CODEX_AUTHORIZATION_KEY)
+    await this.#credentials.deleteRecord(CODEX_AUTHORIZATION_KEY)
+    return { signedOut: true }
+  }
+
+  dispatch(endpoint, payload, signal) {
+    switch (endpoint) {
+      case "status": return this.status(payload, signal)
+      case "start": return this.start(payload)
+      case "respond": return this.respond(payload)
+      case "cancel": return this.cancel(payload)
+      case "logout": return this.logout(payload)
+      default: throw new RpcInputError("Unknown dsh-codex RPC endpoint")
+    }
+  }
+
+  dispose() {
+    if (this.#closed) return
+    this.#closed = true
+    const cancel = () => {
+      for (const attempt of this.#attempts.values()) {
+        if (!attempt.done) attempt.controller.abort("authorization bridge disposed")
+      }
+      this.#authorization.cancel(CODEX_AUTHORIZATION_KEY)
+    }
+    // A disposed interaction surface may detach from an irreversible commit,
+    // but must not make AuthorizationService report that commit as cancelled.
+    if (this.#commitTracker === undefined) cancel()
+    else this.#commitTracker.tryCancel(cancel)
+    for (const attempt of this.#attempts.values()) {
+      if (attempt.cleanup !== undefined) clearTimeout(attempt.cleanup)
+      this.#rejectPrompt(attempt, new Error("authorization bridge disposed"))
+      wakeAttempt(attempt)
+    }
+    this.#attempts.clear()
+  }
+
+  async #publicStatus() {
+    const entry = this.#authorization.describe(CODEX_AUTHORIZATION_KEY)
+    const credential = await describeCodexCredential(this.#credentials)
+    return {
+      flow: entry === undefined ? undefined : {
+        key: CODEX_AUTHORIZATION_KEY,
+        label: boundedText(entry.label, MAX_MESSAGE_CHARS),
+        methods: entry.methods
+          .filter(({ id }) => typeof id === "string" && id.length > 0 && id.length <= MAX_ID_CHARS)
+          .slice(0, MAX_METHODS)
+          .map(({ id, label }) => ({ id, label: boundedText(label, MAX_MESSAGE_CHARS) })),
+        inFlight: entry.inFlight,
+      },
+      credential,
+      quota: this.#quotaObserver?.snapshot() ?? Object.freeze({ status: "unknown" }),
+    }
+  }
+
+  #attempt(id) {
+    const attempt = this.#attempts.get(id)
+    if (attempt === undefined) throw new RpcInputError("Unknown authorization attempt")
+    return attempt
+  }
+
+  #assertOpen() {
+    if (this.#closed) throw new RpcInputError("Authorization bridge is closed")
+  }
+
+  #prompt(attempt, prompt) {
+    if (attempt.done || attempt.controller.signal.aborted) {
+      return Promise.reject(new Error("authorization attempt is no longer active"))
+    }
+    if (attempt.prompt !== undefined) {
+      return Promise.reject(new Error("authorization flow opened overlapping prompts"))
+    }
+    if (prompt.signal?.aborted === true) {
+      return Promise.reject(new Error("authorization prompt was already withdrawn"))
+    }
+
+    return new Promise((resolve, reject) => {
+      const serialized = serializePrompt(prompt)
+      const pending = {
+        id: randomUUID(),
+        resolve,
+        reject,
+        mapAnswer: serialized.mapAnswer,
+        signal: prompt.signal,
+        onAbort: undefined,
+      }
+      if (prompt.signal !== undefined) {
+        pending.onAbort = () => {
+          if (attempt.prompt !== pending) return
+          this.#closePrompt(attempt, pending)
+          reject(new Error("authorization prompt withdrawn"))
+        }
+        prompt.signal.addEventListener("abort", pending.onAbort, { once: true })
+      }
+      attempt.prompt = pending
+      this.#emit(attempt, {
+        type: "prompt",
+        promptId: pending.id,
+        prompt: serialized.prompt,
+      })
+    })
+  }
+
+  #closePrompt(attempt, pending) {
+    if (pending.signal !== undefined && pending.onAbort !== undefined) {
+      pending.signal.removeEventListener("abort", pending.onAbort)
+    }
+    if (attempt.prompt === pending) attempt.prompt = undefined
+    this.#emit(attempt, { type: "prompt-closed", promptId: pending.id })
+  }
+
+  #rejectPrompt(attempt, error) {
+    const pending = attempt.prompt
+    if (pending === undefined) return
+    this.#closePrompt(attempt, pending)
+    pending.reject(error)
+  }
+
+  #settle(attempt, terminal) {
+    if (attempt.done) return
+    attempt.done = true
+    this.#rejectPrompt(attempt, new Error("authorization attempt settled"))
+    this.#emit(attempt, terminal)
+    attempt.cleanup = setTimeout(() => {
+      this.#attempts.delete(attempt.id)
+    }, this.#retentionMs)
+    attempt.cleanup.unref?.()
+  }
+
+  #emit(attempt, event) {
+    attempt.events.push(Object.freeze({ seq: attempt.nextSeq++, ...event }))
+    if (attempt.events.length > MAX_EVENTS) attempt.events.shift()
+    wakeAttempt(attempt)
+  }
+}
+
+export function installAuthorizationRpc(ctx, options) {
+  const bridge = new CodexAuthorizationBridge({
+    authorization: ctx.authorization,
+    credentials: ctx.credentials,
+  }, options)
+  ctx.connection.rpc.handle(
+    AUTHORIZATION_RPC_CHANNEL,
+    createAuthorizationRpcHandler(bridge),
+    { authority: "loopback" },
+  )
+  ctx.effect(() => () => bridge.dispose(), "dsh-codex: authorization RPC state")
+  return bridge
+}
+
+export function createAuthorizationRpcHandler(bridge) {
+  return async (endpoint, payload, signal) => {
+    try {
+      return { ok: true, value: await bridge.dispatch(endpoint, payload, signal) }
+    } catch (error) {
+      if (signal?.aborted === true) {
+        return {
+          ok: false,
+          error: { code: "cancelled", message: "Request cancelled", details: {} },
+        }
+      }
+      if (error instanceof RpcInputError) {
+        return {
+          ok: false,
+          error: { code: "bad-request", message: error.message, details: { issues: [] } },
+        }
+      }
+      return {
+        ok: false,
+        error: { code: "internal", message: "Authorization request failed", details: {} },
+      }
+    }
+  }
+}
+
+export function registerCodexLoginCommand(ctx, options = {}) {
+  const commitTracker = options.commitTracker
+  ctx.commands.register({
+    name: "codex-login",
+    description: "管理 Codex 登录 / Manage Codex sign-in",
+    input: { hint: "[status|cancel|logout]" },
+    recordInput: false,
+    handler: async ({ rawInput }) => {
+      const action = rawInput.trim()
+      try {
+        if (action === "cancel") {
+          const cancel = () => ctx.authorization.cancel(CODEX_AUTHORIZATION_KEY)
+          if (commitTracker?.tryCancel(cancel) === false) {
+            return {
+              kind: "success",
+              text: "Codex 凭据已开始提交，当前无法取消；请稍候检查登录状态。 / Codex credential commit has started and can no longer be cancelled; check sign-in status shortly.",
+            }
+          }
+          if (commitTracker === undefined) cancel()
+          return {
+            kind: "success",
+            text: "已请求取消 Codex 登录。请在 Codex 设置页重试。 / Codex sign-in cancellation requested. Retry from Codex Settings.",
+          }
+        }
+        if (action === "logout") {
+          ctx.authorization.cancel(CODEX_AUTHORIZATION_KEY)
+          await ctx.credentials.deleteRecord(CODEX_AUTHORIZATION_KEY)
+          return {
+            kind: "success",
+            text: "已退出 Codex 登录。 / Signed out of Codex.",
+          }
+        }
+        if (action !== "" && action !== "status") {
+          return {
+            kind: "error",
+            text: "用法：/codex-login [status|cancel|logout] / Usage: /codex-login [status|cancel|logout]",
+          }
+        }
+
+        const flow = ctx.authorization.describe(CODEX_AUTHORIZATION_KEY)
+        const credential = await describeCodexCredential(ctx.credentials)
+        if (flow?.inFlight === true) {
+          return {
+            kind: "success",
+            text: "Codex 登录正在进行；请在 Codex 设置页继续。 / Codex sign-in is in progress; continue in Codex Settings.",
+          }
+        }
+        if (credential.state === "signed-in") {
+          return {
+            kind: "success",
+            text: "Codex 已登录。 / Codex is signed in.",
+          }
+        }
+        if (credential.state === "invalid") {
+          return {
+            kind: "success",
+            text: "已保存的 Codex 凭据无效；请重新登录或退出后重试。 / The saved Codex credential is invalid; sign in again or sign out before retrying.",
+          }
+        }
+        return {
+          kind: "success",
+          text: flow === undefined
+            ? "Codex 登录当前不可用。 / Codex sign-in is currently unavailable."
+            : "Codex 尚未登录；请打开 Codex 设置页。 / Codex is not signed in; open Codex Settings.",
+        }
+      } catch {
+        return {
+          kind: "error",
+          text: "Codex 登录操作失败，请在设置页重试。 / Codex sign-in action failed. Retry from Settings.",
+        }
+      }
+    },
+  })
+}
+
+async function describeCodexCredential(credentials) {
+  const description = await credentials.describeRecord(CODEX_AUTHORIZATION_KEY)
+  let state = "signed-out"
+  if (description.configured === true) {
+    if (description.kind !== "grant") {
+      state = "invalid"
+    } else {
+      try {
+        const credential = await createCodexCredentialStore(credentials).read(CODEX_PROVIDER_ID)
+        state = credential === undefined ? "signed-out" : "signed-in"
+      } catch {
+        state = "invalid"
+      }
+    }
+  }
+  return {
+    configured: description.configured === true,
+    state,
+    ...(description.kind === undefined ? {} : { kind: description.kind }),
+    writable: description.writable === true,
+  }
+}
+
+export function registerCodexUsageCommand(ctx, quotaObserver) {
+  ctx.commands.register({
+    name: "codex-usage",
+    description: "查看最近观测到的 Codex 额度状态 / Show the last observed Codex quota state",
+    input: { hint: "[status]" },
+    recordInput: false,
+    handler: async ({ rawInput }) => {
+      const action = rawInput.trim()
+      if (action !== "" && action !== "status") {
+        return {
+          kind: "error",
+          text: "用法：/codex-usage [status] / Usage: /codex-usage [status]",
+        }
+      }
+
+      try {
+        return {
+          kind: "success",
+          text: formatQuotaSnapshot(quotaObserver.snapshot()),
+        }
+      } catch {
+        return {
+          kind: "error",
+          text: "暂时无法读取 Codex 额度观测。 / Codex quota observation is temporarily unavailable.",
+        }
+      }
+    },
+  })
+}
+
+function formatQuotaSnapshot(snapshot) {
+  if (snapshot.status === "recent-success") {
+    return `最近一次 Codex 请求成功于 ${new Date(snapshot.observedAt).toISOString()}；这不代表账户剩余额度。 / Last Codex request succeeded at ${new Date(snapshot.observedAt).toISOString()}; this does not represent remaining account quota.`
+  }
+  if (snapshot.status === "exhausted") {
+    if (snapshot.resetAt === undefined) {
+      return "最近观测到 Codex 账户额度耗尽，但未获得通过校验的重置时间。 / Codex account quota was exhausted in the latest observation, but no reset time passed validation."
+    }
+    const reset = new Date(snapshot.resetAt).toISOString()
+    return `最近观测到 Codex 账户额度耗尽；观测到的重置时间：${reset}。 / Codex account quota was exhausted in the latest observation; observed reset time: ${reset}.`
+  }
+  return "暂无近期 Codex 额度观测；插件不会调用未公开的账户额度接口。 / No recent Codex quota observation; the plugin does not call undocumented account-quota endpoints."
+}
+
+function objectInput(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new RpcInputError("RPC payload must be an object")
+  }
+  return value
+}
+
+function requiredString(value, key, options = {}) {
+  const field = value[key]
+  if (typeof field !== "string" || (!options.allowEmpty && field.length === 0)) {
+    throw new RpcInputError(`${key} must be a ${options.allowEmpty ? "string" : "non-empty string"}`)
+  }
+  if (options.maxLength !== undefined && field.length > options.maxLength) {
+    throw new RpcInputError(`${key} is too long`)
+  }
+  return field
+}
+
+function optionalString(value, key, options) {
+  if (value[key] === undefined) return undefined
+  return requiredString(value, key, options)
+}
+
+function assertOnlyKeys(value, allowed) {
+  const keys = new Set(allowed)
+  if (Object.keys(value).some((key) => !keys.has(key))) {
+    throw new RpcInputError("RPC payload contains an unknown field")
+  }
+}
+
+function optionalSequence(value) {
+  if (value === undefined) return 0
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new RpcInputError("after must be a non-negative safe integer")
+  }
+  return value
+}
+
+function serializeNotice(notice) {
+  const url = safeAuthorizationUrl(notice.url)
+  return {
+    message: boundedText(notice.message, MAX_MESSAGE_CHARS),
+    ...(url === undefined ? {} : { url }),
+    ...(notice.code === undefined ? {} : { code: boundedText(notice.code, MAX_CODE_CHARS) }),
+  }
+}
+
+function serializePrompt(prompt) {
+  if (prompt.kind === "select") {
+    const answers = new Map()
+    const options = prompt.options.slice(0, MAX_OPTIONS).map((option, index) => {
+      const id = `option-${index + 1}`
+      answers.set(id, String(option.id))
+      return {
+        id,
+        label: boundedText(option.label, MAX_MESSAGE_CHARS),
+        ...(option.description === undefined
+          ? {}
+          : { description: boundedText(option.description, MAX_MESSAGE_CHARS) }),
+      }
+    })
+    return {
+      prompt: {
+        kind: "select",
+        message: boundedText(prompt.message, MAX_MESSAGE_CHARS),
+        options,
+      },
+      mapAnswer: (answer) => {
+        const selected = answers.get(answer)
+        if (selected === undefined) throw new RpcInputError("Unknown prompt option")
+        return selected
+      },
+    }
+  }
+  return {
+    prompt: {
+      kind: prompt.kind === "secret" ? "secret" : "text",
+      message: boundedText(prompt.message, MAX_MESSAGE_CHARS),
+      ...(prompt.placeholder === undefined
+        ? {}
+        : { placeholder: boundedText(prompt.placeholder, MAX_PLACEHOLDER_CHARS) }),
+    },
+    mapAnswer: (answer) => answer,
+  }
+}
+
+function boundedText(value, maxLength) {
+  const text = String(value)
+  return text.length <= maxLength ? text : text.slice(0, maxLength)
+}
+
+function safeAuthorizationUrl(value) {
+  if (value === undefined) return undefined
+  const text = String(value)
+  if (text.length === 0 || text.length > MAX_URL_CHARS) return undefined
+  try {
+    const url = new URL(text)
+    if (url.username !== "" || url.password !== "") return undefined
+    if (url.protocol === "https:") return url.href
+    if (url.protocol !== "http:" || !isLoopbackHostname(url.hostname)) return undefined
+    return url.href
+  } catch {
+    return undefined
+  }
+}
+
+function isLoopbackHostname(hostname) {
+  return hostname === "localhost"
+    || hostname === "[::1]"
+    || /^127(?:\.\d{1,3}){3}$/u.test(hostname)
+}
+
+function safeAuthorizationFailure(error) {
+  const candidate = typeof error?.code === "string" ? error.code : "AUTHORIZATION_FAILED"
+  const code = /^[A-Z0-9_-]{1,64}$/u.test(candidate) ? candidate : "AUTHORIZATION_FAILED"
+  return { code, message: "Authorization failed" }
+}
+
+function waitForAttempt(attempt, after, signal, waitMs) {
+  if (attempt.done || attempt.events.some((event) => event.seq > after)) return Promise.resolve()
+  if (signal?.aborted === true) return Promise.reject(signal.reason ?? new Error("request cancelled"))
+  if (attempt.waiters.size >= MAX_WAITERS_PER_ATTEMPT) {
+    return Promise.reject(new RpcInputError("Too many status waiters"))
+  }
+  return new Promise((resolve, reject) => {
+    let timer
+    const finish = (error) => {
+      attempt.waiters.delete(wake)
+      if (timer !== undefined) clearTimeout(timer)
+      signal?.removeEventListener("abort", abort)
+      if (error === undefined) resolve()
+      else reject(error)
+    }
+    const wake = () => finish()
+    const abort = () => finish(signal.reason ?? new Error("request cancelled"))
+    attempt.waiters.add(wake)
+    signal?.addEventListener("abort", abort, { once: true })
+    timer = setTimeout(wake, waitMs)
+    timer.unref?.()
+  })
+}
+
+function wakeAttempt(attempt) {
+  for (const wake of [...attempt.waiters]) wake()
+}

package/dist/internal/authorization-commit-tracker.mjs

@@ -0,0 +1,49 @@
+/**
+ * Coordinate the user-facing cancellation boundary around one local Codex
+ * authorization flow. No credential material enters this state machine.
+ */
+export function createAuthorizationCommitTracker() {
+  let generation = 0
+  let active
+
+  return Object.freeze({
+    begin() {
+      if (active !== undefined) {
+        throw new Error("a Codex authorization attempt is already tracked")
+      }
+      const id = ++generation
+      active = { id, phase: "cancellable" }
+      let finished = false
+
+      return Object.freeze({
+        selectCommit() {
+          if (finished || active?.id !== id || active.phase !== "cancellable") return false
+          active = { id, phase: "committing" }
+          return true
+        },
+        finish() {
+          if (finished) return
+          finished = true
+          if (active?.id === id && active.phase === "cancellable") active = undefined
+        },
+      })
+    },
+
+    /** Check and run cancellation in one synchronous call stack. */
+    tryCancel(cancel) {
+      if (typeof cancel !== "function") throw new TypeError("cancel must be a function")
+      if (active?.phase === "committing") return false
+      cancel()
+      return true
+    },
+
+    isCommitPending() {
+      return active?.phase === "committing"
+    },
+
+    /** Called when the public authorization attempt reaches its terminal state. */
+    settle() {
+      active = undefined
+    },
+  })
+}