@modelprofile.com/authswitch-signin 10.4.0

package/ts_signin/signin.grants.ts

@@ -0,0 +1,518 @@
+// OpenAI protocol portions are adapted in TypeScript from OpenAI Codex (Apache-2.0) and modified by Task Venture Capital GmbH; see third-party-notices.md.
+
+import * as plugins from './plugins.js';
+import { parseOpenAiTokenClaims, revokeOpenAiRefreshToken } from './signin.protocol.js';
+import { openAiTokensOfCredential, refreshOpenAiCredential } from './signin.credential.js';
+import type { IOpenAiLoginResult, IOpenAiOAuthCredential } from './signin.interfaces.js';
+
+/**
+ * The state of a stored grant:
+ * - `active`: its tokens are usable and refreshed when due. `retryAt` is set after a refresh that was never sent.
+ * - `refresh_uncertain`: a refresh may have been sent. The refresh token may already be spent, so it is never
+ *   sent again; the attempt either commits the rotated tokens or, once `attempt.expiresAt` passed, the grant
+ *   needs a new sign-in.
+ * - `reauth_required`: only a new sign-in brings the grant back.
+ */
+export type TOpenAiGrantState = 'active' | 'refresh_uncertain' | 'reauth_required';
+
+/**
+ * Why a grant needs a new sign-in:
+ * - `refresh_failed`: a refresh was sent and did not produce tokens (refused, or its outcome is unknown);
+ * - `refresh_interrupted`: a refresh may have been sent and its attempt ended without an answer;
+ * - `identity_changed`: a refresh answered for another workspace or user.
+ */
+export type TOpenAiGrantReauthReason = 'refresh_failed' | 'refresh_interrupted' | 'identity_changed';
+
+/**
+ * One grant as the store keeps it. The store seals `credential` at rest and hands the record back unchanged;
+ * everything else is credential-free.
+ */
+export interface IOpenAiGrantRecord {
+  /** Rises by one with every change of the record; `compareAndSet` and `remove` compare it. */
+  revision: number;
+  /** Rises by one with every new access token; a provider's 401 names the generation it rejected. */
+  generation: number;
+  state: TOpenAiGrantState;
+  credential: IOpenAiOAuthCredential;
+  /** The ChatGPT workspace the grant acts in; a refresh that states another is refused. */
+  accountId: string;
+  /** The ChatGPT user the grant was signed in as; a refresh that states another is refused. */
+  userId: string;
+  isFedrampAccount: boolean;
+  /** When the current access token expires, ISO 8601. */
+  accessExpiresAt: string;
+  /** When the current tokens were issued, by the sign-in or the last refresh, ISO 8601. */
+  refreshedAt: string;
+  /** After a refresh that was never sent: the earliest time to try again. */
+  retryAt: string | null;
+  retryCount: number;
+  /** While `refresh_uncertain`: the attempt that may have sent the refresh token, and when it is given up. */
+  attempt: { id: string; expiresAt: string } | null;
+  /** While `reauth_required`: why. */
+  reauthReason: TOpenAiGrantReauthReason | null;
+}
+
+/**
+ * Where grants live, supplied by the caller. Every write names the revision it read, so two processes that act on
+ * one grant cannot both win: `compareAndSet` and `remove` must compare and write in one atomic step, as a
+ * database's conditional update does. A store keeps `credential` sealed at rest and never logs it.
+ */
+export interface IOpenAiGrantStore {
+  load(grantId: string): Promise<IOpenAiGrantRecord | null>;
+  /** Stores a new grant; `conflict` when one exists under the id. */
+  create(grantId: string, record: IOpenAiGrantRecord): Promise<'stored' | 'conflict'>;
+  /** Replaces the grant only while it is still at `expectedRevision`. */
+  compareAndSet(grantId: string, expectedRevision: number, next: IOpenAiGrantRecord): Promise<'stored' | 'conflict'>;
+  /** Deletes the grant only while it is still at `expectedRevision`; `conflict` when it moved or is gone. */
+  remove(grantId: string, expectedRevision: number): Promise<'removed' | 'conflict'>;
+}
+
+/** Access for one request: what FlexHarness's ChatGPT connection takes, with the generation it belongs to. */
+export interface IOpenAiGrantAccess {
+  accessToken: string;
+  accountId: string;
+  isFedrampAccount: boolean;
+  expiresAt: string;
+  generation: number;
+}
+
+export interface IOpenAiGrantResolveOptions {
+  /** Stops waiting. A refresh already sent keeps running to its end, so its outcome is recorded. */
+  signal?: AbortSignal;
+  /** The generation the provider just rejected with 401; the grant is refreshed if it is still the current one. */
+  rejectedGeneration?: number;
+  /** How long the access must stay valid, in milliseconds (at most one hour). Defaults to one minute. */
+  minValidityMs?: number;
+}
+
+/** What a caller may show about a grant: no token. */
+export interface IOpenAiGrantStatus {
+  revision: number;
+  generation: number;
+  state: TOpenAiGrantState;
+  reauthReason: TOpenAiGrantReauthReason | null;
+  accountId: string;
+  isFedrampAccount: boolean;
+  plan: string | null;
+  accessExpiresAt: string;
+  refreshedAt: string;
+  retryAt: string | null;
+}
+
+/**
+ * What the service said about revoking a removed grant:
+ * - `confirmed`: it revoked the grant's current refresh token;
+ * - `unconfirmed`: it revoked the stored token, but a refresh may have replaced it at the service before;
+ * - `failed`: it did not confirm the revocation. The sign-in may still be valid at the service.
+ */
+export type TOpenAiGrantRevocation = 'confirmed' | 'unconfirmed' | 'failed';
+
+/**
+ * Why a grant cannot answer:
+ * - `not_found`: no grant under the id;
+ * - `reauth_required`: only a new sign-in brings it back (`reauthReason` says why);
+ * - `access_not_fresh`: the grant is intact, but the service could not renew it yet (`retryAt`);
+ * - `invalid_argument`, `invalid_record`: the caller's input or the stored record;
+ * - `aborted`: the caller's signal;
+ * - `contended`: the record kept changing under this call; try again.
+ */
+export type TOpenAiGrantErrorCode = 'not_found' | 'reauth_required' | 'access_not_fresh' | 'invalid_argument'
+  | 'invalid_record' | 'aborted' | 'contended';
+
+/** A grant failure. Its message is fixed and names no token. */
+export class OpenAiGrantError extends Error {
+  constructor(
+    public readonly code: TOpenAiGrantErrorCode,
+    public readonly details: { reauthReason?: TOpenAiGrantReauthReason; retryAt?: string } = {},
+  ) {
+    super(`OpenAI grant operation failed (${code}).`);
+    this.name = 'OpenAiGrantError';
+  }
+}
+
+export interface IOpenAiGrantManagerOptions {
+  store: IOpenAiGrantStore;
+  fetch?: typeof fetch;
+  now?: () => number;
+  /** How often a process polls a grant another process is refreshing. Defaults to 250 ms. */
+  waitIntervalMs?: number;
+}
+
+/** Codex refreshes an access token that expires within five minutes (`CHATGPT_ACCESS_TOKEN_REFRESH_WINDOW_MINUTES`). */
+const ACCESS_REFRESH_WINDOW_MS = 5 * 60 * 1000;
+/** Codex refreshes tokens older than eight days even while the access token is valid (`TOKEN_REFRESH_INTERVAL`). */
+const TOKEN_REFRESH_INTERVAL_MS = 8 * 24 * 60 * 60 * 1000;
+/** One refresh request is bounded by thirty seconds; an attempt is given up thirty seconds after that. */
+const REFRESH_REQUEST_TIMEOUT_MS = 30_000;
+const REFRESH_ATTEMPT_LEASE_MS = 60_000;
+const DEFAULT_MIN_VALIDITY_MS = 60_000;
+const MAX_MIN_VALIDITY_MS = 3_600_000;
+const MAX_RESOLVE_ROUNDS = 8;
+const MAX_WRITE_ROUNDS = 4;
+const MAX_GRANT_ID_BYTES = 512;
+
+const isoTime = (value: unknown): number => {
+  if (typeof value !== 'string') return NaN;
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value ? time : NaN;
+};
+
+const isCount = (value: unknown, minimum: number): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum;
+
+const requireGrantId = (grantId: string): string => {
+  if (typeof grantId !== 'string' || !grantId || Buffer.byteLength(grantId, 'utf8') > MAX_GRANT_ID_BYTES) {
+    throw new OpenAiGrantError('invalid_argument');
+  }
+  return grantId;
+};
+
+/** The identity and expiry a credential's access token states; `null` when it states none of them usable. */
+const accessFactsOf = (credential: IOpenAiOAuthCredential): {
+  accountId: string; userId: string; isFedrampAccount: boolean; expiresAt: string;
+} | null => {
+  try {
+    openAiTokensOfCredential(credential);
+    const access = parseOpenAiTokenClaims(credential.accessToken);
+    const identity = parseOpenAiTokenClaims(credential.idToken);
+    const accountId = access.chatgptAccountId ?? identity.chatgptAccountId;
+    const userId = access.chatgptUserId ?? identity.chatgptUserId;
+    if (!accountId || !userId || !access.expiresAt) return null;
+    if (identity.chatgptAccountId !== undefined && identity.chatgptAccountId !== accountId) return null;
+    return { accountId, userId, isFedrampAccount: access.chatgptAccountIsFedramp, expiresAt: access.expiresAt };
+  } catch { return null; }
+};
+
+/** A stored record this manager would have written; anything else is refused before it is used. */
+const checkRecord = (record: IOpenAiGrantRecord): IOpenAiGrantRecord => {
+  const valid = record !== null && typeof record === 'object'
+    && isCount(record.revision, 1) && isCount(record.generation, 1) && isCount(record.retryCount, 0)
+    && ['active', 'refresh_uncertain', 'reauth_required'].includes(record.state)
+    && typeof record.accountId === 'string' && record.accountId.length > 0
+    && typeof record.userId === 'string' && record.userId.length > 0
+    && typeof record.isFedrampAccount === 'boolean'
+    && Number.isFinite(isoTime(record.accessExpiresAt)) && Number.isFinite(isoTime(record.refreshedAt))
+    && (record.retryAt === null || Number.isFinite(isoTime(record.retryAt)))
+    && (record.state === 'refresh_uncertain'
+      ? record.attempt !== null && typeof record.attempt === 'object' && typeof record.attempt.id === 'string'
+        && record.attempt.id.length > 0 && Number.isFinite(isoTime(record.attempt.expiresAt))
+      : record.attempt === null)
+    && (record.state === 'reauth_required'
+      ? ['refresh_failed', 'refresh_interrupted', 'identity_changed'].includes(record.reauthReason ?? '')
+      : record.reauthReason === null);
+  if (!valid) throw new OpenAiGrantError('invalid_record');
+  const facts = accessFactsOf(record.credential);
+  if (!facts || facts.accountId !== record.accountId || facts.userId !== record.userId
+    || facts.isFedrampAccount !== record.isFedrampAccount || facts.expiresAt !== record.accessExpiresAt) {
+    throw new OpenAiGrantError('invalid_record');
+  }
+  return record;
+};
+
+/**
+ * Keeps ChatGPT sign-ins usable for any number of processes that share one store: it answers current access for
+ * each request, refreshes the tokens when they are due or the provider rejected exactly the current generation,
+ * and never sends a refresh token whose outcome is unknown a second time. Within a process one refresh per grant
+ * runs at a time; across processes the store's compare-and-set on the revision decides, and a process that finds
+ * another's refresh in flight waits for its outcome. It holds no credential of its own: every call reads the
+ * store, and no error, status or return value carries a refresh or ID token.
+ */
+export class OpenAiGrantManager {
+  private readonly store: IOpenAiGrantStore;
+  private readonly fetcher: typeof fetch | undefined;
+  private readonly now: () => number;
+  private readonly waitIntervalMs: number;
+  private readonly refreshes = new Map<string, Promise<void>>();
+
+  constructor(options: IOpenAiGrantManagerOptions) {
+    if (!options || typeof options.store !== 'object' || options.store === null) {
+      throw new OpenAiGrantError('invalid_argument');
+    }
+    const waitIntervalMs = options.waitIntervalMs ?? 250;
+    if (!Number.isSafeInteger(waitIntervalMs) || waitIntervalMs < 1 || waitIntervalMs > 10_000) {
+      throw new OpenAiGrantError('invalid_argument');
+    }
+    this.store = options.store;
+    this.fetcher = options.fetch;
+    this.now = options.now ?? (() => Date.now());
+    this.waitIntervalMs = waitIntervalMs;
+  }
+
+  /** The record a new sign-in starts: generation one, active. */
+  private recordOf(result: IOpenAiLoginResult, revision: number, generation: number): IOpenAiGrantRecord {
+    const facts = result && typeof result === 'object' ? accessFactsOf(result.credential) : null;
+    if (!facts) throw new OpenAiGrantError('invalid_argument');
+    return {
+      revision, generation, state: 'active', credential: result.credential,
+      accountId: facts.accountId, userId: facts.userId, isFedrampAccount: facts.isFedrampAccount,
+      accessExpiresAt: facts.expiresAt, refreshedAt: new Date(this.now()).toISOString(),
+      retryAt: null, retryCount: 0, attempt: null, reauthReason: null,
+    };
+  }
+
+  private statusOf(record: IOpenAiGrantRecord): IOpenAiGrantStatus {
+    let plan: string | null = null;
+    try { plan = parseOpenAiTokenClaims(record.credential.idToken).chatgptPlanType ?? null; } catch { plan = null; }
+    return {
+      revision: record.revision, generation: record.generation, state: record.state,
+      reauthReason: record.reauthReason, accountId: record.accountId, isFedrampAccount: record.isFedrampAccount,
+      plan, accessExpiresAt: record.accessExpiresAt, refreshedAt: record.refreshedAt, retryAt: record.retryAt,
+    };
+  }
+
+  private async load(grantId: string): Promise<IOpenAiGrantRecord | null> {
+    const record = await this.store.load(grantId);
+    return record === null ? null : checkRecord(record);
+  }
+
+  /** Stores the grant a device sign-in produced. Throws `OpenAiGrantError` `contended` when a grant exists under the id. */
+  public async create(grantId: string, result: IOpenAiLoginResult): Promise<IOpenAiGrantStatus> {
+    requireGrantId(grantId);
+    const record = this.recordOf(result, 1, 1);
+    if (await this.store.create(grantId, record) !== 'stored') throw new OpenAiGrantError('contended');
+    return this.statusOf(record);
+  }
+
+  /**
+   * Replaces a grant with a new sign-in, over the revision the caller read: a grant that needs a new sign-in is
+   * repaired this way. The generation keeps rising, so a 401 of the old tokens cannot be mistaken for the new.
+   * The replaced tokens are not revoked.
+   */
+  public async replace(grantId: string, expectedRevision: number, result: IOpenAiLoginResult): Promise<IOpenAiGrantStatus> {
+    requireGrantId(grantId);
+    if (!isCount(expectedRevision, 1)) throw new OpenAiGrantError('invalid_argument');
+    const current = await this.load(grantId);
+    if (!current) throw new OpenAiGrantError('not_found');
+    if (current.revision !== expectedRevision) throw new OpenAiGrantError('contended');
+    const record = this.recordOf(result, current.revision + 1, current.generation + 1);
+    if (await this.store.compareAndSet(grantId, expectedRevision, record) !== 'stored') {
+      throw new OpenAiGrantError('contended');
+    }
+    return this.statusOf(record);
+  }
+
+  /** The grant's state without any token; `null` when there is none. */
+  public async status(grantId: string): Promise<IOpenAiGrantStatus | null> {
+    requireGrantId(grantId);
+    const record = await this.load(grantId);
+    return record ? this.statusOf(record) : null;
+  }
+
+  private isDue(record: IOpenAiGrantRecord, minValidityMs: number): boolean {
+    const now = this.now();
+    return Date.parse(record.accessExpiresAt) <= now + Math.max(minValidityMs, ACCESS_REFRESH_WINDOW_MS)
+      || Date.parse(record.refreshedAt) <= now - TOKEN_REFRESH_INTERVAL_MS;
+  }
+
+  private async wait(signal: AbortSignal | undefined): Promise<void> {
+    if (signal?.aborted) throw new OpenAiGrantError('aborted');
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let onAbort: (() => void) | undefined;
+    try {
+      await new Promise<void>((resolve, reject) => {
+        timer = setTimeout(resolve, this.waitIntervalMs);
+        if (signal) {
+          onAbort = () => reject(new OpenAiGrantError('aborted'));
+          signal.addEventListener('abort', onAbort, { once: true });
+        }
+      });
+    } finally {
+      if (timer) clearTimeout(timer);
+      if (onAbort) signal?.removeEventListener('abort', onAbort);
+    }
+  }
+
+  /** Waits for a promise, or rejects `aborted` as soon as the signal fires; the promise runs on regardless. */
+  private async awaitOrAbort(task: Promise<void>, signal: AbortSignal | undefined): Promise<void> {
+    if (!signal) return task;
+    if (signal.aborted) throw new OpenAiGrantError('aborted');
+    let onAbort: (() => void) | undefined;
+    try {
+      await Promise.race([task, new Promise<never>((_resolve, reject) => {
+        onAbort = () => reject(new OpenAiGrantError('aborted'));
+        signal.addEventListener('abort', onAbort, { once: true });
+      })]);
+    } finally {
+      if (onAbort) signal.removeEventListener('abort', onAbort);
+    }
+  }
+
+  /** Moves a record on over the revision it was read at; `false` when it moved meanwhile. */
+  private async write(grantId: string, current: IOpenAiGrantRecord,
+    change: Partial<IOpenAiGrantRecord>): Promise<boolean> {
+    const next: IOpenAiGrantRecord = { ...current, ...change, revision: current.revision + 1 };
+    return await this.store.compareAndSet(grantId, current.revision, next) === 'stored';
+  }
+
+  /**
+   * Current access for one provider request. The access stays valid for `minValidityMs` at least; tokens that
+   * are due, or whose generation the provider just rejected, are refreshed first.
+   * Throws `OpenAiGrantError`: `reauth_required` when only a new sign-in helps, `access_not_fresh` when the
+   * service could not renew the tokens yet.
+   */
+  public async resolveAccess(grantId: string, options: IOpenAiGrantResolveOptions = {}): Promise<IOpenAiGrantAccess> {
+    requireGrantId(grantId);
+    const minValidityMs = options.minValidityMs ?? DEFAULT_MIN_VALIDITY_MS;
+    const rejected = options.rejectedGeneration;
+    if (!Number.isSafeInteger(minValidityMs) || minValidityMs < 0 || minValidityMs > MAX_MIN_VALIDITY_MS
+      || (rejected !== undefined && !isCount(rejected, 1))) {
+      throw new OpenAiGrantError('invalid_argument');
+    }
+    let refreshedOnce = false;
+    for (let round = 0; round < MAX_RESOLVE_ROUNDS; round++) {
+      if (options.signal?.aborted) throw new OpenAiGrantError('aborted');
+      const record = await this.load(grantId);
+      if (!record) throw new OpenAiGrantError('not_found');
+      if (rejected !== undefined && rejected > record.generation) throw new OpenAiGrantError('invalid_argument');
+      if (record.state === 'reauth_required') {
+        throw new OpenAiGrantError('reauth_required', { reauthReason: record.reauthReason ?? 'refresh_failed' });
+      }
+      if (record.state === 'refresh_uncertain') {
+        await this.settleAttempt(grantId, record, options.signal);
+        continue;
+      }
+      const rejectedCurrent = rejected === record.generation;
+      const expiresAt = Date.parse(record.accessExpiresAt);
+      const usable = !rejectedCurrent && expiresAt > this.now() + minValidityMs;
+      if (!this.isDue(record, minValidityMs) && usable) {
+        return {
+          accessToken: record.credential.accessToken, accountId: record.accountId,
+          isFedrampAccount: record.isFedrampAccount, expiresAt: record.accessExpiresAt, generation: record.generation,
+        };
+      }
+      const retryAt = record.retryAt === null ? null : Date.parse(record.retryAt);
+      if (refreshedOnce || (retryAt !== null && retryAt > this.now())) {
+        // The service was asked and could not renew the tokens yet. Access that is still good enough serves.
+        if (usable) {
+          return {
+            accessToken: record.credential.accessToken, accountId: record.accountId,
+            isFedrampAccount: record.isFedrampAccount, expiresAt: record.accessExpiresAt, generation: record.generation,
+          };
+        }
+        throw new OpenAiGrantError('access_not_fresh', record.retryAt === null ? {} : { retryAt: record.retryAt });
+      }
+      await this.awaitOrAbort(this.refresh(grantId, record), options.signal);
+      refreshedOnce = true;
+    }
+    throw new OpenAiGrantError('contended');
+  }
+
+  /**
+   * Refreshes a grant that is due (by its access expiry or its age) and answers its state; one that is not due is
+   * left as it is. For a periodic job, so a sign-in that no request uses stays alive.
+   */
+  public async keepFresh(grantId: string, options: { signal?: AbortSignal } = {}): Promise<IOpenAiGrantStatus | null> {
+    requireGrantId(grantId);
+    try {
+      await this.resolveAccess(grantId, { signal: options.signal, minValidityMs: 0 });
+    } catch (error) {
+      if (!(error instanceof OpenAiGrantError) || !['reauth_required', 'access_not_fresh', 'not_found'].includes(error.code)) {
+        throw error;
+      }
+    }
+    return this.status(grantId);
+  }
+
+  /**
+   * A record whose refresh may have been sent: this process waits for its own attempt; another process's attempt
+   * is waited for until the record moves on or the attempt's lease passes, and then the grant needs a new sign-in.
+   */
+  private async settleAttempt(grantId: string, record: IOpenAiGrantRecord, signal: AbortSignal | undefined): Promise<void> {
+    const own = this.refreshes.get(grantId);
+    if (own) {
+      await this.awaitOrAbort(own, signal);
+      return;
+    }
+    let current: IOpenAiGrantRecord | null = record;
+    while (current && current.revision === record.revision) {
+      if (!current.attempt || Date.parse(current.attempt.expiresAt) <= this.now()) {
+        await this.write(grantId, current, {
+          state: 'reauth_required', reauthReason: 'refresh_interrupted', attempt: null, retryAt: null,
+        });
+        return;
+      }
+      await this.wait(signal);
+      current = await this.load(grantId);
+    }
+  }
+
+  /** One refresh per grant in this process; a caller that stops waiting leaves it running to its end. */
+  private refresh(grantId: string, record: IOpenAiGrantRecord): Promise<void> {
+    const prior = this.refreshes.get(grantId);
+    if (prior) return prior;
+    const task = this.performRefresh(grantId, record)
+      .finally(() => { if (this.refreshes.get(grantId) === task) this.refreshes.delete(grantId); });
+    this.refreshes.set(grantId, task);
+    return task;
+  }
+
+  private async performRefresh(grantId: string, initial: IOpenAiGrantRecord): Promise<void> {
+    const attemptId = plugins.crypto.randomUUID();
+    const attempt = { id: attemptId, expiresAt: new Date(this.now() + REFRESH_ATTEMPT_LEASE_MS).toISOString() };
+    // The marker is stored before the refresh token is sent: a process that dies after this point leaves a
+    // record that can only lead to a new sign-in, never to a second use of the same refresh token.
+    if (!await this.write(grantId, initial, { state: 'refresh_uncertain', attempt, retryAt: null })) return;
+    const marked: IOpenAiGrantRecord = { ...initial, state: 'refresh_uncertain', attempt, retryAt: null,
+      revision: initial.revision + 1 };
+    const result = await refreshOpenAiCredential(initial.credential, {
+      fetch: this.fetcher, signal: AbortSignal.timeout(REFRESH_REQUEST_TIMEOUT_MS), now: () => new Date(this.now()),
+    });
+    const current = await this.load(grantId);
+    if (!current || current.revision !== marked.revision || current.attempt?.id !== attemptId) return;
+    if (result.success) {
+      const facts = accessFactsOf(result.credential);
+      if (!facts || facts.accountId !== initial.accountId || facts.userId !== initial.userId) {
+        await this.write(grantId, current, {
+          state: 'reauth_required', reauthReason: 'identity_changed', attempt: null, retryAt: null,
+        });
+        return;
+      }
+      await this.write(grantId, current, {
+        state: 'active', credential: result.credential, generation: current.generation + 1,
+        isFedrampAccount: facts.isFedrampAccount, accessExpiresAt: facts.expiresAt,
+        refreshedAt: new Date(this.now()).toISOString(), retryAt: null, retryCount: 0, attempt: null,
+        reauthReason: null,
+      });
+      return;
+    }
+    if (result.requestOutcome === 'notSent') {
+      const backoffMs = Math.min(30_000 * 2 ** Math.min(current.retryCount, 10), 1_800_000);
+      const retryMs = Math.max(backoffMs, Math.min(result.retryAfterMs ?? 0, 3_600_000));
+      await this.write(grantId, current, {
+        state: 'active', attempt: null, retryAt: new Date(this.now() + retryMs).toISOString(),
+        retryCount: current.retryCount + 1,
+      });
+      return;
+    }
+    await this.write(grantId, current, {
+      state: 'reauth_required', reauthReason: 'refresh_failed', attempt: null, retryAt: null,
+    });
+  }
+
+  /**
+   * Removes a grant and then asks the service to revoke its refresh token. The grant is removed whatever the
+   * service answers; `revocation` says what it answered. `removed: false` when there was no grant.
+   */
+  public async remove(grantId: string, options: { signal?: AbortSignal } = {}): Promise<{
+    removed: boolean; revocation: TOpenAiGrantRevocation | null;
+  }> {
+    requireGrantId(grantId);
+    for (let round = 0; round < MAX_WRITE_ROUNDS; round++) {
+      const record = await this.store.load(grantId);
+      if (!record) return { removed: false, revocation: null };
+      if (!isCount(record.revision, 1)) throw new OpenAiGrantError('invalid_record');
+      if (await this.store.remove(grantId, record.revision) !== 'removed') continue;
+      let token: string | null = null;
+      try { token = openAiTokensOfCredential(record.credential).refreshToken; } catch { token = null; }
+      if (token === null) return { removed: true, revocation: 'failed' };
+      try {
+        await revokeOpenAiRefreshToken(token, { fetch: this.fetcher, signal: options.signal });
+      } catch {
+        return { removed: true, revocation: 'failed' };
+      }
+      const current = record.state === 'active' && record.attempt === null;
+      return { removed: true, revocation: current ? 'confirmed' : 'unconfirmed' };
+    }
+    throw new OpenAiGrantError('contended');
+  }
+}

package/ts_signin/signin.interfaces.ts

@@ -0,0 +1,75 @@
+// OpenAI protocol portions are adapted in TypeScript from OpenAI Codex (Apache-2.0) and modified by Task Venture Capital GmbH; see third-party-notices.md.
+
+/**
+ * The shapes of one ChatGPT sign-in: the credential it produces, the access that credential grants, what its
+ * claims say about the account, and the outcome of a refresh. Inference with an access token is FlexHarness's
+ * `/openai`, not this.
+ */
+
+/** Whether a failed request reached the provider: `notSent` never did, `outcomeUnknown` may have. */
+export type TOpenAiRequestOutcome = 'notSent' | 'outcomeUnknown';
+
+/**
+ * A ChatGPT sign-in with its rotating refresh token. This exact shape is what the authority seals, so a stored
+ * credential keeps reading back across releases.
+ */
+export interface IOpenAiOAuthCredential {
+  kind: 'chatgptOAuth';
+  providerId: 'openai';
+  accessToken: string;
+  refreshToken: string;
+  idToken: string;
+  /** When this credential was last refreshed; strictly increasing across refreshes. */
+  lastRefreshAt?: string;
+}
+
+/** Access to one ChatGPT workspace, with the workspace and residency its issuer states. */
+export interface IOpenAiAccess {
+  accessToken: string;
+  accountId: string;
+  isFedrampAccount: boolean;
+}
+
+/** What a sign-in's claims say about its account; no token. */
+export interface IOpenAiAccountSummary {
+  providerId: 'openai';
+  authKind: 'chatgptOAuth';
+  accountId?: string;
+  email?: string;
+  plan?: string;
+}
+
+/** What the person signing in does: open the URL and enter the code. */
+export interface IOpenAiDevicePrompt {
+  flow: 'device';
+  verificationUrl: string;
+  userCode: string;
+}
+
+export interface IOpenAiLoginResult {
+  credential: IOpenAiOAuthCredential;
+  account: IOpenAiAccountSummary;
+}
+
+export type TOpenAiOperationErrorCode = 'ABORTED' | 'TIMEOUT';
+
+export interface IOpenAiRefreshSuccess {
+  success: true;
+  credential: IOpenAiOAuthCredential;
+  account: IOpenAiAccountSummary;
+}
+
+export interface IOpenAiRefreshFailure {
+  success: false;
+  credential: IOpenAiOAuthCredential;
+  errorCode: TOpenAiOperationErrorCode | 'REFRESH_FAILED';
+  /** Never replay a rotating grant when this is `outcomeUnknown`. */
+  requestOutcome: TOpenAiRequestOutcome;
+  /** The response status, when an HTTP response was observed. */
+  responseStatus?: number;
+  /** Bounded Retry-After delay from the observed response. */
+  retryAfterMs?: number;
+}
+
+export type TOpenAiRefreshResult = IOpenAiRefreshSuccess | IOpenAiRefreshFailure;
+