export declare const CODEX_AUTH_CACHE_OFF_SWITCH_ENV = "PAPERCLIP_CODEX_AUTH_CACHE"; /** * True when the cache is enabled. The cache is on by default. It turns off only * when {@link CODEX_AUTH_CACHE_OFF_SWITCH_ENV} is an explicit falsy value * (`0`, `false`, `no`, or `off`). */ export declare function isCodexAuthCacheEnabled(env?: NodeJS.ProcessEnv): boolean; /** * Sanitizes an `account_id` to one safe path segment. Rejects an empty value, a * relative segment (`.` or `..`), a path separator, and a NUL byte, so a raw * `account_id` can never become a path traversal. Returns the trimmed, safe * segment. (Security condition 3.) */ export declare function toCacheKey(accountId: string): string; /** * Resolves the company-scoped cache root under the same isolation boundary as * the managed Codex home (`resolveManagedCodexHomeDir`). The root is always * company-scoped, so a Codex credential can never cross a company boundary. * There is no instance-global fallback root: `companyId` is required, and an * empty value is a fail-loud error. `companyId` is sanitized to a single safe * path segment, so a traversal value (`..`, `/etc`, `a/b`) can never make the * cache root escape the `companies/` directory. Every downstream path (the * entry path, the vend, and the clear) inherits this guard. (Security * condition 1.) */ export declare function resolveCodexAuthCacheDir(env: NodeJS.ProcessEnv | undefined, companyId: string): string; /** * True when `homePath` sits inside the per-identity credential store of ANY * company: `/companies//codex-auth-cache/…` (or is a store * root itself). These directories are identity-anchored slots owned by the * device-login promotion, the vend, and the copy-back, each under its own * lock. The managed-home seeding pass consults this to refuse to symlink, * heal, or overwrite an entry's `auth.json`: an agent may bind `CODEX_HOME` * to an entry (through the login's account-home secret), and seeding it like * an ordinary managed home would silently swap the bound account's durable * credential for the host login. */ export declare function isCodexAuthCachePath(env: NodeJS.ProcessEnv, homePath: string): boolean; /** * Resolves the entry path for one identity: `//auth.json`. * The `account_id` is validated first by {@link toAccountHandle} (a strict * allowlist), the entry point of this function, then sanitized again by * {@link toCacheKey} (a denylist) as a second, independent layer. After the * join, this verifies the resolved entry path stays under the cache root and * ends at exactly `/auth.json`. This function does no filesystem * work; it is safe for a read path (the vend and the clear). (Security * condition 3.) */ export declare function resolveCodexAuthCacheEntryPath(env: NodeJS.ProcessEnv | undefined, accountId: string, companyId: string): string; /** * Resolves the entry path and creates the cache root and the entry directory * private (mode 0700), each guarded by `lstat`. The `account_id` is validated * at the entry point of this function through {@link resolveCodexAuthCacheEntryPath}. * Use this on the write path before the entry is written. */ export declare function ensureCodexAuthCacheEntryDir(env: NodeJS.ProcessEnv | undefined, accountId: string, companyId: string): Promise; export interface EnsureCodexAuthCacheEntryDirExclusiveResult { /** The entry path: `/auth.json`. */ entryPath: string; /** True only when this exact call found the account's own home directory * absent and created it. */ created: boolean; } /** * Same as {@link ensureCodexAuthCacheEntryDir}, but the absence check and the * directory creation run inside one lock keyed to the company-scoped cache * root. Two different logins for the SAME Codex account can promote at the * same time (each login owns its own promotion slot), so a plain * check-then-create sequence lets both concurrent callers see the slot as * absent and both report `created: true`. Under this lock, only the caller * that truly finds the slot absent gets `created: true`; the other caller * correctly reports `created: false` and so never deletes a home the first * caller's login already wrote to and named with a company secret. */ export declare function ensureCodexAuthCacheEntryDirExclusive(env: NodeJS.ProcessEnv | undefined, accountId: string, companyId: string): Promise; /** * Serializes one company's whole device-login promotion sequence: the * account-home directory create-or-reuse decision, the credential write, and * the secret bind or cleanup that follows. Two different logins for the SAME * Codex account run this sequence one at a time under this lock, so no login * can decide to delete the shared account-home directory while another * login's flow is still mid-way through writing its credential or binding * its own secret to that same directory. * * `ensureCodexAuthCacheEntryDirExclusive` alone is not enough: it locks only * the short directory-creation step, so its lock is already released by the * time a login reaches the secret bind. A second login can then write its * credential and be about to bind its own secret while the first login's * later, unrelated secret-write failure decides to remove the directory both * logins now share, deleting a credential home the second login still needs. * Holding this lock across the full sequence for every login closes that * window: a login that must clean up its own directory always finishes that * cleanup, including the directory-recreation of any later login that lands * on the now-empty slot, before the next login's sequence starts. */ export declare function withCodexAccountHomePromotionLock(env: NodeJS.ProcessEnv | undefined, companyId: string, fn: () => Promise): Promise; export declare function withAccountHomeSecretMutationLock(env: NodeJS.ProcessEnv | undefined, companyId: string, fn: () => Promise): Promise; /** * Confirms a `local_encrypted` secret value that names a directory under this * company's Codex account-home cache root still exists on disk. Call this * inside {@link withAccountHomeSecretMutationLock}, before a create or a * rotate commits the value. * * The lock alone stops a write and the account-home cleanup's * check-and-delete from interleaving; it does not stop them from running in * either order. When the cleanup's check-and-delete runs first — it finds no * secret names the directory, because this write had not committed yet, and * removes the directory — a write that was only queued behind the lock still * goes on, once the lock frees, to commit the very directory the cleanup * just removed. That would leave an active secret naming a directory that * does not exist. This check closes that window: a write whose value would * name a directory the cleanup already removed fails instead of committing. * * A value outside this company's cache root is left alone. Only a value * under the cache root can ever be an account-home directory, so this never * rejects an unrelated `local_encrypted` secret write, such as an API key or * a hand-typed token. */ export declare function assertAccountHomeCacheDirStillValid(env: NodeJS.ProcessEnv | undefined, companyId: string, value: string): Promise; /** * Reads the usable subscription `account_id` from an `auth.json` payload. Returns * `null` for an absent, unusable, or api-key credential (no subscription * identity). This mirrors `parseAuth` in `codex-auth-merge-decision.cjs`; keep * the two in step when the auth format changes. * * The returned value is the exact, untrimmed `account_id` string. A caller * passes it on to {@link toAccountHandle} unchanged: that function is the * one place that decides whether surrounding whitespace is acceptable, and it * must see the raw value to reject an identifier that differs from another * one only by whitespace. Trimming here, before that check runs, would let * two distinct identifiers collapse onto the same account handle. */ export declare function readSubscriptionAccountId(bytes: Buffer): string | null; export type WriteCodexAuthCacheEntryOutcome = "written" | "kept-slot"; /** * Writes `sandboxAuthBytes` into its per-identity cache slot when the slot is * absent, or when the source is a strictly-newer same-identity subscription * credential (seed mode). The mutation runs under the merge lock on the slot * directory, through the shared {@link writeCredentialSeedOrNewer} writer. Never * logs token bytes or a raw `account_id`. */ export declare function writeCodexAuthCacheEntry(input: { sandboxAuthBytes: Buffer; cacheEntryPath: string; log: (line: string) => void | Promise; /** Environment for the merge lock root. Defaults to `process.env`. */ env?: NodeJS.ProcessEnv; }): Promise; export type VendCodexAuthOutcome = "vended" | "kept-host" | "no-host-identity"; /** * Refreshes the identity the host already holds with a strictly-newer cached * credential of the same `account_id`. Identity-anchored: * * 1. Read the host identity from `sharedHomeAuthPath` first. * 2. When the host holds no usable subscription identity, do nothing. The vend * never picks a credential from the cache at random (matrix rows 3, 4). * 3. Resolve ONLY that exact identity's cache slot. The vend never scans the * cache root. (Security condition 4.) * 4. Run the DEFAULT-mode predicate (cache slot as source, shared home as * destination). Install the cache copy only when it is strictly newer for the * same identity. * * The vend never changes identity and never stages a spent single-use refresh * token (the strictly-newer rule guards it). Never logs token bytes or a raw * `account_id`. */ export declare function selectVendCredential(sharedHomeAuthPath: string, resolveCacheEntryPath: (accountId: string) => string, log: (line: string) => void | Promise, env?: NodeJS.ProcessEnv): Promise; /** * Removes exactly one identity slot from the cache. The `account_id` is * sanitized by {@link toCacheKey}, so the removal can never escape the cache * root. A missing slot is a benign no-op. Any other removal error is fail-loud. */ export declare function clearCodexAuthCacheEntry(env: NodeJS.ProcessEnv | undefined, accountId: string, companyId: string): Promise; /** * Removes every slot in the company-scoped cache root. A missing cache root is a * benign no-op. */ export declare function clearCodexAuthCache(env: NodeJS.ProcessEnv | undefined, companyId: string): Promise; //# sourceMappingURL=codex-auth-cache.d.ts.map