Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

15.8 KB
Raw Blame
/**
 * The ChatGPT-subscription half of the Codex providers, as PortOS models it.
 *
 * PortOS already ships `codex` (CLI) and `codex-tui` provider records, and
 * `providerPrerequisites.js` can tell you whether the `codex` binary is on
 * PATH. That is only half of "can this provider run": Codex authenticates
 * against a ChatGPT subscription (or an API key, or Bedrock), and until now
 * nothing in PortOS could say whether that sign-in exists, which plan backs it,
 * whether it has expired, or whether the subscription's usage window is spent.
 * The user found out inside a failed agent transcript.
 *
 * OpenAI's documented Codex **app-server** owns that lifecycle, so this is the
 * clean-room boundary PortOS consumes: `account/read` is the source of truth
 * and `account/login/start` runs the browser flow. PortOS never reads, copies,
 * returns, logs, or persists `~/.codex/auth.json`, an access token, or a
 * refresh token — Codex keeps its own credentials and refreshes them itself.
 *
 * This module is the PURE half: constants, protocol-payload normalization, the
 * redactor every log/error path runs through, and the readiness state machine.
 * The process/JSON-RPC half is `services/codexAppServer.js`.
 *
 * **SENTINEL DISCIPLINE** (AGENTS.md). Three different "nothing here" answers
 * must never collapse into each other:
 *
 *   - `runtimeInstalled: null` — NOT PROBED. Never reads as "the binary is
 *     missing".
 *   - `accountFetched: false` — `account/read` has not answered. Never reads as
 *     SIGNED OUT; that is a claim only a successful read may make.
 *   - `rateLimits: null` — the quota read failed or never ran, which is NOT the
 *     same as a successful read that legitimately reported no active window.
 *     An empty-but-fetched answer normalizes to an object, so a subscription
 *     with no limit window in flight is never mistaken for a broken fetch.
 */

/**
 * The one invocation PortOS is allowed to spawn. Fixed argv, never assembled
 * from a provider record or a request: the app-server is a protocol endpoint,
 * not a user-configurable command line, and a config write must not be able to
 * choose the exec target.
 */
export const CODEX_APP_SERVER_COMMAND = 'codex';
export const CODEX_APP_SERVER_ARGS = Object.freeze(['app-server']);

/** JSON-RPC methods this phase speaks. Read-only plus the explicit auth verbs. */
export const CODEX_RPC = Object.freeze({
  initialize: 'initialize',
  initialized: 'initialized',
  accountRead: 'account/read',
  rateLimitsRead: 'account/rateLimits/read',
  loginStart: 'account/login/start',
  loginCancel: 'account/login/cancel',
  logout: 'account/logout',
});

/** Server-to-client notifications that invalidate PortOS's cached readiness. */
export const CODEX_NOTIFICATIONS = Object.freeze({
  accountUpdated: 'account/updated',
  rateLimitsUpdated: 'account/rateLimits/updated',
  loginCompleted: 'account/login/completed',
});

/**
 * Every state the Providers page has to be able to paint differently, because
 * each one has a different fix. `unknown` is deliberately its own state rather
 * than a pessimistic `signedOut`: telling a signed-in user to sign in again
 * because a probe failed is worse than saying PortOS could not tell.
 */
export const CODEX_ACCOUNT_STATUS = Object.freeze({
  runtimeMissing: 'runtime-missing',
  unknown: 'unknown',
  signedOut: 'signed-out',
  loginPending: 'login-pending',
  ready: 'ready',
  quotaExhausted: 'quota-exhausted',
  reauthRequired: 'reauth-required',
});

/** Typed failures the routes and the client both branch on. */
export const CODEX_ERROR_CODES = Object.freeze({
  runtimeMissing: 'CODEX_RUNTIME_MISSING',
  startFailed: 'CODEX_APP_SERVER_START_FAILED',
  exited: 'CODEX_APP_SERVER_EXITED',
  timeout: 'CODEX_APP_SERVER_TIMEOUT',
  protocol: 'CODEX_APP_SERVER_PROTOCOL_ERROR',
  authRevoked: 'CODEX_AUTH_REVOKED',
  loginTimeout: 'CODEX_LOGIN_TIMEOUT',
  loginCancelled: 'CODEX_LOGIN_CANCELLED',
  loginFailed: 'CODEX_LOGIN_FAILED',
  unknownLogin: 'CODEX_UNKNOWN_LOGIN',
});

/**
 * Which provider records this account state belongs to — the command-keyed,
 * local-runtime-excluding rule. Declared in `providerModels.js`, the pure leaf
 * the browser re-exports, so this module's protocol tables stay server-only.
 */
export { isCodexSubscriptionProvider } from './providerModels.js';

/**
 * Keys whose VALUES may carry a credential. Matched case-insensitively as a
 * substring so a field PortOS has never seen (`chatgptAuthTokens`,
 * `refresh_token`, `clientSecret`) is redacted the first time it appears rather
 * than the first time someone notices it in a log.
 */
const SECRET_KEY_RE = /(token|secret|password|credential|apikey|api_key|accesskey|authorization|bearer|cookie|codeverifier|code_verifier)/i;
const REDACTED = '[redacted]';
const MAX_REDACT_DEPTH = 6;

/**
 * A copy of `value` safe to put in a log line, an error `context`, or an HTTP
 * response: every credential-shaped key replaced, strings clamped, recursion
 * bounded.
 *
 * Applied to protocol payloads on BOTH directions before anything is written
 * anywhere, so "we never log a token" is a property of one function rather than
 * a rule every call site has to remember.
 */
export const redactCodexPayload = (value, depth = 0) => {
  if (value === null || value === undefined) return value ?? null;
  if (typeof value === 'string') return value.length > 200 ? `${value.slice(0, 200)}…` : value;
  if (typeof value === 'number' || typeof value === 'boolean') return value;
  if (depth >= MAX_REDACT_DEPTH) return REDACTED;
  if (Array.isArray(value)) return value.slice(0, 20).map((entry) => redactCodexPayload(entry, depth + 1));
  if (typeof value !== 'object') return REDACTED;
  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
    key,
    SECRET_KEY_RE.test(key) ? REDACTED : redactCodexPayload(entry, depth + 1),
  ]));
};

/**
 * A free-text protocol message with any credential-shaped substring masked, or
 * `null` when there is nothing to say.
 *
 * The payload redactor keys on FIELD NAMES; an upstream failure quoted into a
 * `message` string has no field names to key on ("access_token=… expired",
 * "Authorization: Bearer …"). These messages are both logged AND returned to the
 * browser by the `/codex/*` routes, so they need their own scrub.
 */
export const redactCodexMessage = (value) => {
  if (typeof value !== 'string' || value.trim() === '') return null;
  // Clamped BEFORE the patterns run, so the scan is bounded by a constant no
  // matter what an upstream error decides to quote at us.
  const clamped = value.length > 400 ? `${value.slice(0, 400)}…` : value;
  return clamped
    // `key=<value>` / `key: <value>` where the key is credential-shaped and the
    // value is long enough to BE one. The length floor is what keeps "The secret:
    // sauce" intact while masking "refresh_token: eyJhbGciOi…" — and it is the
    // only exemption, because a long all-letters value after such a key is a
    // passphrase, not a sentence. The value class runs to the next whitespace or
    // quote so a trailing "!" cannot leave half a secret behind.
    .replace(
      /\b([A-Za-z0-9_-]*(?:token|secret|password|passwd|credential|api[_-]?key|access[_-]?key|cookie|signature)[A-Za-z0-9_-]*)(\s*[=:]\s*)("?)([^\s"']{12,})\3?/gi,
      `$1$2${REDACTED}`,
    )
    // An inline authorization credential under ANY scheme — Bearer, Basic,
    // Token, and whatever a future provider invents. Anchored on the header
    // name, so an ordinary sentence containing "token" is untouched.
    .replace(/\b(authorization|proxy-authorization)(\s*[=:]\s*)(\S+\s+)?\S+/gi, `$1$2${REDACTED}`)
    .replace(/\b(bearer|basic|token)\s+[A-Za-z0-9._~+/=-]{12,}/gi, `$1 ${REDACTED}`)
    // A bare vendor key, which carries no label at all to key on.
    .replace(/\b(sk|pk|rk)-[A-Za-z0-9._-]{8,}/g, REDACTED)
    .replace(/\beyJ[A-Za-z0-9._-]{16,}/g, REDACTED);
};

const trimmedString = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : null);

/**
 * The non-secret shape of `account/read`.
 *
 * Returns `null` for a successful read that found no account — the ONE input
 * from which "signed out" may be concluded. A response PortOS cannot understand
 * is not that, so it throws rather than inventing a signed-out verdict; the
 * caller turns that into `unknown`.
 *
 * Only three fields survive: how Codex authenticates, which plan backs it, and
 * whether the credentials are Codex-managed. No id, no email, no token — the
 * page needs "is this ready and on which plan", not who the user is.
 */
export const normalizeCodexAccount = (result) => {
  if (result === null || result === undefined) return null;
  if (typeof result !== 'object') throw new Error('account/read returned a non-object result');
  // The documented envelope nests the record; tolerate a bare record too, since
  // an install may be running a Codex older or newer than the one studied.
  const raw = ('account' in result) ? result.account : result;
  if (raw === null || raw === undefined) return null;
  if (typeof raw !== 'object') throw new Error('account/read returned a non-object account');
  const authMethod = trimmedString(raw.type) || trimmedString(raw.authMethod);
  if (!authMethod) throw new Error('account/read returned an account with no auth method');
  return {
    authMethod,
    planType: trimmedString(raw.planType) || trimmedString(raw.chatgptPlanType),
    usesCodexManagedCredentials: raw.usesCodexManagedCredentials === true,
  };
};

/** One rate-limit window, or `null` when the payload has nothing usable in it. */
const normalizeWindow = (raw) => {
  if (!raw || typeof raw !== 'object') return null;
  const usedPercent = typeof raw.usedPercent === 'number' && Number.isFinite(raw.usedPercent)
    ? raw.usedPercent
    : null;
  const windowDurationMins = typeof raw.windowDurationMins === 'number' && Number.isFinite(raw.windowDurationMins)
    ? raw.windowDurationMins
    : null;
  const resetsAt = typeof raw.resetsAt === 'number' && Number.isFinite(raw.resetsAt) && Math.abs(raw.resetsAt) <= 8.64e12
    ? new Date(raw.resetsAt * 1000).toISOString()
    : trimmedString(raw.resetsAt);
  const limitName = trimmedString(raw.limitName);
  if (usedPercent === null && windowDurationMins === null && resetsAt === null) return null;
  return { usedPercent, windowDurationMins, resetsAt, limitName };
};

/**
 * The non-secret shape of `account/rateLimits/read`.
 *
 * Throws for a response that isn't an object, so a FAILED read stays `null` at
 * the call site. A successful read with no active window returns an object
 * whose windows are `null` — "fetched, and there is nothing to report" is a
 * real answer and must not be re-labelled as a failed fetch (AGENTS.md).
 */
export const normalizeCodexRateLimits = (result) => {
  if (result === null || result === undefined) throw new Error('rate limits read returned nothing');
  if (typeof result !== 'object') throw new Error('rate limits read returned a non-object result');
  const raw = result.rateLimits ?? result.codexRateLimits ?? result;
  const source = (raw && typeof raw === 'object') ? raw : {};
  const credits = (source.credits && typeof source.credits === 'object')
    ? { hasCredits: source.credits.hasCredits === true, unlimited: source.credits.unlimited === true }
    : null;
  return {
    primary: normalizeWindow(source.primary),
    secondary: normalizeWindow(source.secondary),
    credits,
  };
};

/**
 * Is the subscription's usage window spent?
 *
 * `null` (not fetched) is NOT exhausted — an unread quota may never take a
 * working provider off the page. Only a window that reports itself at or past
 * 100% counts.
 */
export const codexRateLimitsExhausted = (rateLimits) => {
  if (!rateLimits || typeof rateLimits !== 'object') return false;
  return [rateLimits.primary, rateLimits.secondary]
    .some((window) => typeof window?.usedPercent === 'number' && window.usedPercent >= 100);
};

/**
 * What `account/login/start` gives the browser, and nothing else.
 *
 * Both documented shapes are accepted: `authUrl` for the browser flow and
 * `verificationUrl` (+ a short user code) for the device-code flow. Everything
 * else in the response — including any token material a future Codex might add
 * — is dropped here rather than filtered downstream.
 *
 * Throws when there is no `loginId`: without it the login cannot be cancelled
 * or correlated with its completion notification, so returning a URL the user
 * could open would strand them in a flow PortOS can no longer settle.
 */
export const normalizeCodexLoginStart = (result) => {
  if (!result || typeof result !== 'object') throw new Error('login start returned a non-object result');
  const loginId = trimmedString(result.loginId);
  if (!loginId) throw new Error('login start returned no loginId');
  const httpsUrl = (value) => {
    const url = trimmedString(value);
    return url && URL.canParse(url) && new URL(url).protocol === 'https:' ? url : null;
  };
  const authUrl = httpsUrl(result.authUrl);
  const verificationUrl = httpsUrl(result.verificationUrl);
  if (!authUrl && !verificationUrl) throw new Error('login start returned no sign-in URL');
  return {
    loginId,
    authUrl,
    verificationUrl,
    userCode: trimmedString(result.userCode),
  };
};

/**
 * Does this protocol error mean the stored ChatGPT sign-in is gone (revoked,
 * expired, withdrawn from the workspace) rather than merely unreachable?
 *
 * Matched on the message because the app-server surfaces the upstream 401 as
 * free text; a false negative degrades to `unknown`, which is the safe side.
 */
export const isCodexAuthError = (error) => {
  const message = typeof error?.message === 'string' ? error.message : '';
  return /\b(401|unauthorized|unauthenticated|invalid[_ -]?grant|token (?:expired|revoked)|re-?authenticate)\b/i
    .test(message);
};

/**
 * The whole state machine, in one pure function.
 *
 * @param {object} input
 * @param {boolean|null} input.runtimeInstalled — `null` = NOT PROBED
 * @param {boolean} input.accountFetched — did `account/read` actually answer?
 * @param {object|null} input.account — normalized account; `null` only means
 *   signed out when `accountFetched` is true
 * @param {object|null} input.rateLimits — `null` = NOT FETCHED
 * @param {boolean} input.loginPending — a PortOS-initiated login is in flight
 * @param {{code: string, message: string}|null} input.error
 * @returns {string} one of {@link CODEX_ACCOUNT_STATUS}
 */
export const deriveCodexAccountStatus = ({
  runtimeInstalled = null,
  accountFetched = false,
  account = null,
  rateLimits = null,
  loginPending = false,
  error = null,
} = {}) => {
  if (runtimeInstalled === false) return CODEX_ACCOUNT_STATUS.runtimeMissing;
  if (error?.code === CODEX_ERROR_CODES.authRevoked) return CODEX_ACCOUNT_STATUS.reauthRequired;
  if (!accountFetched) {
    return (!error && loginPending) ? CODEX_ACCOUNT_STATUS.loginPending : CODEX_ACCOUNT_STATUS.unknown;
  }
  if (!account) return loginPending ? CODEX_ACCOUNT_STATUS.loginPending : CODEX_ACCOUNT_STATUS.signedOut;
  if (codexRateLimitsExhausted(rateLimits)) return CODEX_ACCOUNT_STATUS.quotaExhausted;
  return CODEX_ACCOUNT_STATUS.ready;
};

/** One line for the card and the run log, per status. */
export const describeCodexAccountStatus = (status, account = null) => {
  switch (status) {
    case CODEX_ACCOUNT_STATUS.runtimeMissing: return 'Codex CLI is not installed';
    case CODEX_ACCOUNT_STATUS.signedOut: return 'No ChatGPT account is signed in';
    case CODEX_ACCOUNT_STATUS.loginPending: return 'Waiting for the ChatGPT sign-in to finish';
    case CODEX_ACCOUNT_STATUS.reauthRequired: return 'ChatGPT sign-in has expired — sign in again';
    case CODEX_ACCOUNT_STATUS.quotaExhausted: return 'ChatGPT usage limit reached for this window';
    case CODEX_ACCOUNT_STATUS.ready:
      return account?.planType ? `Signed in on the ${account.planType} plan` : 'Signed in';
    default: return 'Codex account state is unknown';
  }
};