@tickernelz/paperclip-pro-adapter-codex-local 2026.925.0

package/dist/server/codex-auth-cache.d.ts

@@ -0,0 +1,206 @@
+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: `<instanceRoot>/companies/<id>/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: `<cacheRoot>/<safeAccountId>/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 `<safeAccountId>/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<string>;
+export interface EnsureCodexAuthCacheEntryDirExclusiveResult {
+    /** The entry path: `<accountHomeDir>/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<EnsureCodexAuthCacheEntryDirExclusiveResult>;
+/**
+ * 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<T>(env: NodeJS.ProcessEnv | undefined, companyId: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Serializes one company's writes to the literal value of any
+ * `local_encrypted` company secret against the account-home cleanup's
+ * claimant scan in {@link withCodexAccountHomePromotionLock}'s caller. Only a
+ * `local_encrypted` secret can hold a literal directory path, so this is the
+ * one provider a cleanup claimant scan must trust. Without this lock, a
+ * secret create or rotation can commit its new value after the scan's last
+ * pass finds no claimant but before the cleanup deletes the directory: the
+ * scan and the write never observe each other, so the write's new value
+ * survives past a directory the delete has already removed.
+ *
+ * The secrets service holds this lock for the full duration of a
+ * `local_encrypted` secret's create or rotate call. A cleanup claimant scan
+ * holds it for the full duration of its final check-and-delete step. The two
+ * critical sections can then never interleave: a write that starts first
+ * finishes (and becomes visible to the scan) before the scan's lock-holding
+ * check runs, and a write that starts after the scan's lock-holding check
+ * finishes only commits once the scan (and any delete it decided on) is
+ * done, so it can never name a directory the delete just removed without the
+ * scan having had a chance to see it first.
+ *
+ * This is a separate lock directory from
+ * {@link withCodexAccountHomePromotionLock}'s, so a device-login promotion
+ * (which holds that lock for its whole sequence, including its own secret
+ * create) can still call into a secrets-service write that takes this lock
+ * without deadlocking on itself.
+ */
+export declare function withAccountHomeSecretMutationLock<T>(env: NodeJS.ProcessEnv | undefined, companyId: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * 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<void>;
+/**
+ * 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<void>;
+    /** Environment for the merge lock root. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}): Promise<WriteCodexAuthCacheEntryOutcome>;
+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<void>, env?: NodeJS.ProcessEnv): Promise<VendCodexAuthOutcome>;
+/**
+ * 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<void>;
+/**
+ * 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<void>;
+//# sourceMappingURL=codex-auth-cache.d.ts.map

package/dist/server/codex-auth-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-auth-cache.d.ts","sourceRoot":"","sources":["../../src/server/codex-auth-cache.ts"],"names":[],"mappings":"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"}