Skip to content

Latest commit

 

History

History
126 lines (66 loc) · 28.3 KB

LINUX.md

File metadata and controls

126 lines (66 loc) · 28.3 KB

Linux implementation and verification

Source1.41.0 adds a distinct headless terminal account/saved-session command surface, including explicit switch --resume, optional follow-up and exec mode. Native x64/ARM64 command/terminal tests and real two-account x64 contextual CLI resumption are verified separately. The commands are absent from published1.40.7. GUI CLI-only selection and terminal session restoration are different capabilities. Current desktop/full-environment acceptance remains open; historical sections below keep their checkpoint-time scope.

Release1.40.2 preview scope

Complete x64/ARM64 DEB/RPM/tar.gz preview downloads include the runtime. Supported account handoff and broad desktop acceptance remain open. The approved installed desktop is OpenAI's Debian package26.1007.71326 with exact executable/CLI/ASAR checksums; newer versions and RPM-native discovery require review. X11/XWayland and an existing file credential policy are required. Versioned vendor downloads preserve already-reviewed client bytes when latest advances; the utility never disables updates or rewrites credential policy.

The owner test environment has two accounts registered through ordinary browser login. The owner confirmed both accounts appeared without pressing Refresh after the startup fix. One ordinary Switch click then applied the other real account and launched Codex. Fifteen/sixteen production storage/policy/identity/usage checks verify the exact previous-login backup, approved managed launch and cleared no-chat checkpoint; both encrypted accounts remain accessible through the existing keyring. Sanitized receipts and separate empty-home startup screenshots. No active chat existed and quota was exhausted: authenticated inference/active-chat continuation remains unverified. Credentials never enter public CI. Earlier checkpoint records below retain their original one-account/candidate scope.

Source1.40.2 retains the single native Linux titlebar and fixes automatic startup recovery after keyring unlock. The existing60-second clock starts with the normal window and routes through the guarded initializer; account actions remain disabled until initialization actually succeeds. The earlier owner-operated comparison retains its original one-account scope. Use the separate local interactive recipe for direct owner login; credentials never enter public CI.

Source1.40.0 ordinary integration — issue74 / PR75

Ordinary account/usage actions use the verified client and existing encrypted vault. The selected context must already allow ChatGPT file credentials; the app does not rewrite backend/login/workspace policy. Use Start Codex in the title bar before working so the original process has a verified in-memory launch receipt. An external or previously unmanaged client must be quit normally first. Closing this utility leaves Codex running; restarting the utility requires a new managed start before desktop handoff.

Manual Switch uses the shared encrypted checkpoint coordinator: discover active chats, verify date-prefixed names, normally quit only the original client and wait for its descendants, back up/apply the selected login, start the approved client in the same home, open the original thread IDs and send one Continue only when the existing eligible-idle policy allows it. Each thread's cwd is checked against actual upstream context policy. Uncertain sends are retained for recovery without automatic repetition. Real two-account active-identity/settings/inference/Continue acceptance is still pending; source integration and offline contracts are not that acceptance.

For a separately trusted CLI, supply both --codex-cli <absolute native executable> and --codex-cli-sha256 <exact SHA256>. --client-context <existing directory> selects upstream effective project policy. CLI-only mode exposes accounts/usage and credential application, never desktop restart/chat resumption; any running approved desktop still prevents application. No shell, cross-home synchronization or host credential import is used. Normal Linux hardware temperature/resource telemetry remains unavailable.

The older source checkpoints below describe their capture-time gates, before ordinary integration. Unsigned packages and supported Linux Release/full desktop acceptance remain separate.

Source1.39.0 adds controlled normal X11 close and complete Linux preview package candidates in issue66/PR67. Native architecture, fresh installed-app/data-preservation and supported-OS CI are required before that scoped promotion. Ordinary account/handoff UI remains gated; no supported account-switching Linux Release is claimed.

Source1.38.0 adds native desktop IPC identity and controlled launch, checkpoint62. Actual peer-bound pidfd/image/resource and private socket checks precede IPC; erased startup metadata needs original managed-launch provenance. This is independent of normal desktop shutdown, authenticated handoff and installation acceptance, which remain required in5/6/7. Account/handoff UI remains gated.

Linux support is in progress in issue5, starting with native storage50. Source1.33.0 introduces Secret Service protection; native provider verification, Linux host evidence, client trust, actual manual handoff and packages are required before advertising supported account switching. Published downloads remain1.27.6, without a Linux package. KDE/KWallet, broader environments and actual account/handoff acceptance remain separate gates.

P8.1 is merged in PR51/main3b67458b after all six final-head jobs and author self-review. Native GNOME Keyring18 checks across12 phases and source-app12 captures pass per x64/ARM64 architecture; actual program evidence and limitations. Source1.33.1 adds the separate read-only SQLite52 checkpoint, completed in PR53 as recorded below.

Read-only Linux SQLite/WAL

P8.2 is merged in PR53/mainf4080bf after all six exact-head jobs and author self-review. Its database provider/fixture gate is complete; actual client/account/IPC/handoff acceptance remains open.

The Linux provider resolves distribution libsqlite3.so.0 (libsqlite3-0 on Ubuntu/Debian), using the existing read-only open/statement/busy-timeout path. It does not select a Windows library or immutable mode, rewrite client configuration or enable installed-client IPC. --codex-home <explicit isolated directory> --verify-queues <private report> invokes the ordinary metadata reader before GUI/vault/client initialization; missing/incompatible native SQLite reports unavailable, never a zero queue. UI/account actions stay gated.

python scripts/verify-queues.py --executable artifacts/<native-rid>/CodexSwitch creates only owned disposable fixtures. It checks committed WAL-only additions, uncommitted isolation, saved/server dedup, child/CLI exclusion, removals, malformed/future schemas and exact database/WAL presence and SHA256 before/after each read. Linux additionally removes write permissions from the database/WAL/SHM and containing directory while keeping the explicit reports subdirectory writable; the actual non-root runner must still read committed rows. Shared-memory read coordination is not represented as byte-immutable SHM: SQLite WAL read-only rules. Production reads fixed SELECT metadata queries; statement read-only status is an additional direct-write guard, not a claim to sandbox arbitrary user SQL (SQLite scope).

Storage contract

Linux uses a32-byte key in the configured Secret Service and a distinct CADL1 authenticated AES-GCM envelope (12-byte random nonce/16-byte tag). Windows DPAPI and Mac CADM1 algorithms/identities remain unchanged; foreign envelopes refuse before key lookup. There is no automatic migration, plaintext fallback, implicit unlock or key replacement. Provider unavailable/locked/missing/ambiguous/invalid states remain distinct. Existing ciphertext never authorizes creation of a replacement master key. Keys remain in process memory until explicit release/exit; startup/locked-key tests release the cache or use a new process.

The backend verifies the service owner's effective UID on D-Bus and pins a new proxy to that unique owner before transferring secrets. Native operations use a10-second cancellable deadline off the UI initialization thread. Cross-process key creation uses a no-follow, user-owned0600 lock file in the private vault directory; contention has its own bounded wait. Missing/locked/ambiguous keys fail without altering the existing ciphertext or deleting native keyring items.

Linux private writes walk directories with descriptor-relative no-follow opens, verify ownership/private modes using statx, create0600 staging files exclusively, flush, atomically rename within the same directory and sync the directory. Reads use the verified file descriptor. Existing insecure directories/files are refused instead of silently changing a shared directory's permissions. New directories are0700. Final private directories must belong to the effective user; symlinked components cannot redirect a write. These operations require the declared native Linux environment; no Windows fallback exists.

Native open flags follow the declared process ABI: ARM64's directory/no-follow constants differ from x64. Both require native execution; unknown ABIs refuse instead of guessing. The statx layout follows the stable256-byte Linux UAPI. ARM64 flags, generic flags, statx UAPI.

Secret values are opaque binary bytes. The key contract requires exactly32 bytes and checks newly stored/read values with constant-time comparison; MIME metadata does not define the cryptographic format. GNOME Keyring46.1 labels returned secrets text/plain regardless of the original binary type in its native implementation. Native regression explicitly includes NUL/non-UTF-8 key bytes; no text decoding, trimming or base64 repair is used.

KWallet5 encrypted-session repair — source1.36.0

The source build now includes a private, dynamically linked libsecret0.21.8.2 compatibility library. It repairs unsigned-public-key width, the QCA signed-integer interpretation and minimal shared-secret encoding for the verified KWallet5 provider. GNOME keeps its existing padded shared-secret derivation. The same protocol and libgcrypt algorithms remain in use; there is no plaintext fallback, retry-on-decryption-error or system-library/provider replacement. Existing CADL1/key identities/item attributes remain unchanged. Pinned sources, full patch, LGPL license and rebuild/relink instructions.

Native prerequisites on Ubuntu24.04 include meson ninja-build build-essential pkg-config libglib2.0-dev libgcrypt20-dev gettext xsltproc patch; runtime needs GLib/libgcrypt. KWallet5 requires its distro provider and QCA crypto plugin. python3 scripts/build-linux-secret.py --output artifacts/linux-secret builds and verifies the private library before dotnet native tests/publish. scripts/build-linux.sh includes this step. A cached build is reused only if its reviewed source/patch/architecture and binary hash match; changed inputs require a fresh output and -p:CodexSecretDir=<that absolute output> for dotnet. Package verification requires the native ELF for the target architecture and LGPL license. The loader uses the absolute library beside the app, ABI1, and never substitutes system libsecret when the private library is missing.

The native suite tests positive KWallet5 storage with1024 independent binary-key sessions, existing-format ciphertext/original-key preservation, real save/reopen/tamper, lock/in-place unlock/original PID, process restart persistence, concurrency, ambiguity/malformed/missing keys, bounded timeout/offline refusal and actual account-policy APIs. Fixed leading-zero HKDF vectors and1024 public-key serialization checks run against the exact patched upstream C source. PR59 completed actual x64/ARM64 acceptance, inspected app images and exact-head review/merge; receipts. Test controls use only an owned private bus/HOME/XDG wallet; no personal data is touched. Full KDE/Wayland, authenticated GUI/peer/handoff and install packages remain separate.

KWallet6 and KSecrets — source1.37.0

Declared provider contracts and acceptance distinguish legacy KWallet6 from normalized KSecrets using the original unique-owner PID and root-owned native executable SHA256 before key transfer. Service/version names alone are insufficient. Debian6.13.0-1,6.26.0-1 and6.30.0-1 packages are checksum-pinned independently for x64/ARM64; unverified distribution builds refuse without replacing keys/data. They use existing encrypted-only libsecret ABI1 modes; system providers/configuration and original CADL1/item identities are preserved.

The native workflow retains Ubuntu24.04 GNOME/KWallet5/client/SQLite/app gates and adds three disposable Debian provider images on each actual architecture. Each image installs only reviewed public provider/client packages, then runs offline with only public app/tests/scripts and a dedicated output mounted. The actual lifecycle/account suite includes1024 sessions, forged-version refusal, wrong original process-image refusal and recovery with the unchanged original key. Test-only PAM controls and Qt offscreen are isolated from real desktops; KSecrets6.30 additionally uses its real password dialog on owned Xvfb because the old PAM D-Bus control was removed. Password/hash data never enters argv/environment/logs. Own-window app captures use a private session D-Bus/HOME/XDG and X11/Xvfb; they do not certify complete KDE/Wayland or authenticated switching.

After the usual native build/publish and reviewed official-client package download:

python scripts/verify-kde6-containers.py --architecture X64 --tests artifacts/linux-native/linux-x64/tests --app artifacts/linux-native/linux-x64/app --client-package artifacts/linux-native/linux-x64/upstream-client.deb --output artifacts/linux-native/linux-x64/kde6 --revision <exact40-character-source-SHA>

Use the actual architecture and fresh dedicated output. The disposable Docker images require their checksum-pinned Debian bases and public .NET SDK image; no user HOME, Git credentials, personal bus or live Codex is mounted. No provider is installed on the host by this helper. Code b46b382 native results, 22 inspected app images and exact source/hash receipts pass all six CI jobs; PR61 records final-head promotion.

The historical guard investigation below records source1.35.1. It does not describe the new KWallet5 transport path.

KDE encrypted-session compatibility — source1.35.1

KWallet was unavailable for account storage in source1.35.1. Native investigation of Ubuntu24.04 KWallet5.115.0/libsecret0.21.4 found intermittent encrypted-session failures; repeated independent binary-key reads reproduced Client public key size is invalid, and a separate run failed secret decoding. libsecret exports a variable-length unsigned DH public integer, whereas the inspected KWallet5.115/5.116/6.19 implementation rejects values shorter than128 bytes. Successful individual roundtrips cannot establish reliable provider acceptance. KWallet native source, libsecret public-key serialization.

After verifying the Secret Service owner's UID, the production provider compares its unique bus owner with registered KDE wallet/secrets names. A match reports explicit incompatibility before negotiating a session, searching/creating a key or replacing ciphertext. A separate KDE service with a different unique owner does not identify the active Secret Service. No retry-until-success, plaintext algorithm, custom cryptography, forced GNOME configuration, key rotation or test-only bypass is used. The existing GNOME storage path remains independently verified.

verify-linux-keyring.py --provider kwallet5 runs incompatibility/refusal contracts against an actual native provider, not positive storage acceptance: deterministic upstream protocol rejection, new/locked/unlocked/restarted provider refusal, ciphertext preservation, normal save refusal, timeout/offline and original-PID checks. Test-only KDE PAM control passes an ephemeral hash in memory; standard Secret Service unlock attaches the already-open wallet to its actual collection. Failed startup/close cannot bypass owned-process termination. Raw provider state, hashes and secrets are never uploaded. This uses Qt offscreen, not a complete KDE/Wayland session. Issue55 stays open for an upstream-compatible encrypted stack and the full positive storage suite before this guard can be removed.

Native provider suite

Run on the declared Ubuntu24.04 x64/arm64 runner with .NET10.0.4xx, libsecret, actual GNOME Keyring, D-Bus/gdbus tools and Python3.12:

dotnet build tests/linux-vault/CodexSwitch.LinuxVault.Tests.csproj -c Release -p:UseSharedCompilation=false -o artifacts/linux-native/tests
python scripts/verify-linux-keyring.py --assembly artifacts/linux-native/tests/CodexSwitch.LinuxVault.Tests.dll --architecture X64 --report artifacts/linux-native/keyring-summary.json

Use Arm64 only on an actual ARM64 runner. Linux native CI declares both native runners; cross-compilation does not satisfy this gate. The wrapper creates a private file-socket D-Bus with no activation directories and isolated XDG paths, starts an owned foreground GNOME Keyring, then exercises missing service, actual encrypted application save/reopen, modes/ownership/links, ambiguity/malformed keys, concurrent independent processes, lock/unlock, provider/process restart, bounded timeout, missing key and offline refusal. It never uses the user's bus. Its foreign-owner fixture uses chown only inside the verified disposable test root; application execution does not require elevation. Only sanitized semantic results may be published; never upload keyring files, temporary passwords or raw logs.

The test executable unlocks only its disposable GNOME collection through the provider's native diagnostic interface, with the temporary master password encoded by libsecret and supplied on stdin. The production protection assembly has no unlock operation. The harness checks that Secret Service remains the originally spawned foreground PID before/after the unlock; a new helper daemon cannot substitute for the locked provider. GNOME native interface.

Source preview and actual window evidence

Private-file opens are nonblocking before their descriptor type/UID/mode checks. A named pipe at a vault/file destination therefore fails as a non-regular file without waiting for a writer; native regression verifies read/replacement refusal, bounded completion and preservation of the pipe type.

bash scripts/build-linux.sh publishes a complete self-contained source preview for the native x64/ARM64 host and checks its runtime/project DLLs. Run artifacts/<rid>/CodexSwitch; the shared UI has an explicit localized account-capability gate while client/handoff verification is incomplete. Account reads, switching and real credential access are disabled in this preview. Resource collection is explicitly unavailable; it never becomes a fabricated zero. Trayless close exits. Linux tooltips reduce motion by default until native accessibility integration is verified.

--verify-ui <private-directory> shows the same published app with synthetic profiles, exercises EN/KO, dark/light and500×360/600×420/800×600, checks actual geometry and captures its own visible XID using xwd. Image conversion preserves pixels; the common exporter strips metadata and binds exact source/runtime/architecture/hash. CI uses a private Xvfb display and software rendering, with Noto CJK/fontconfig dependencies. This is X11/Xvfb evidence, not a native Wayland or full GNOME/KDE desktop-session acceptance result. Screenshots contain no personal desktop, pointer, home, keyring, account or Codex data. Do not publish raw captures or the keyring sandbox.

The shared row minimum is126 logical pixels including card margins; the118-pixel card body plus8 pixels of margin meets that contract. Native verification checks the row slot, text containment and absence of unexpected account scrolling separately. Linux supplies its own8-pixel title inset; Mac retains84 pixels for native window controls.

Both native provider jobs and the full Windows/Mac regression/evidence must pass at the final reviewed head before issue50 promotion. Neither portable tests nor a Mac dashboard establish Linux provider support. Client discovery/credential backend/SQLite remain in #5, full native switch/resume in #6 and clean-machine packages/accessibility/environment expansion in #7. New binary Release/signing is a separate owner gate.

Trusted client inspection — source1.34.0

The read-only checkpoint is merged in PR56/main3ada2b20 with all six final-head jobs and author review. Source1.35.0 continues issue54 with context-aware account preflight: --client-context <existing directory> selects the actual config/read cwd; trusted project policy and disabled untrusted layers remain the upstream client's decision. Reports name the selected scope without exporting the directory. Shared normal Linux account GUI/lifecycle/IPC/handoff is still gated.

LinuxClientSession owns the approved native installation and real stdio session. AccountService uses it before Linux initialization/current import/login/refresh/apply and rereads policy before credential writeback. Query children use the retained executable descriptor and validate their own actual isolated policy without forcing file or a provider. File eligibility and required workspace are checked explicitly; unsupported stores/login/profile schemas and inconsistent policy fail before account actions. Linux synchronous account entry points cannot bypass asynchronous verification. Existing Windows/Mac paths keep their existing arguments/algorithms. Canonical and runtime authentication reads use owned0600 regular files in0700 no-follow homes; no permission repair, migration or plaintext fallback is introduced.

Native verification now includes ordinary AccountService calls inside the disposable GNOME bus: incompatible policies prevent import/login/refresh/apply/cache mutation, explicit-file empty initialization saves a genuine CADL1 vault, synthetic local import preserves original bytes, workspace/API restrictions prevent import, changed policy is reread, and isolated query children inspect their actual policy. Synthetic identities and empty authentication stores are setup data, not authenticated login/switch evidence. Real credentials, rate-limit responses, running desktop/peer identity and safe continuation still need their own acceptance. The test provider/required official client install is limited to explicitly disposable native workers; raw homes/config/auth/provider state are never uploaded.

Issue54 adds a separate diagnostic path before normal account actions are enabled. --codex-home <explicit existing home> --verify-client <private report outside that home> inspects only verified client executables and configuration/requirements RPCs. It does not call login, account reads, inference, shutdown, switching or continuation. The upstream child may initialize its own runtime caches; native verification uses only owned disposable homes and checks input config/empty-auth/system-policy byte preservation. Do not use personal homes/accounts for acceptance tests. The normal Linux account, RuntimeLocator/lifecycle and IPC paths stay gated.

Automatic inspection requires a root-managed Debian chatgpt installation matching the reviewed manifest, including exact package version/architecture and SHA256 of the desktop native binary and embedded CLI. Original documented chatgpt is a shell launcher; inspection executes the verified native CLI directly. Root package metadata and ancestor/file ownership, non-writable permissions, no symlinks, native ELF headers, checksums and absence of privilege bits/file capabilities are checked. A verified descriptor remains open through process creation and launch uses the parent's /proc/<pid>/fd reference. Metadata changes invalidate a lease. This proves the specific native binary identity; it does not attest full Electron resources, a running desktop peer or IPC/handoff compatibility. Those remain subsequent native gates.

An explicitly selected CLI requires both --codex-cli <absolute native file> and --codex-cli-sha256 <user-trusted SHA256>. It has CLI-only provenance and no desktop approval. This delegates trust to the user's exact selection; it is not automatic publisher verification. Shell/PATH text, symlink/foreign-owned/writable paths, wrong architectures and elevated executables refuse. New upstream packages/versions require review rather than silently accepting a changed download; current configuration-protocol versions are exact0.162.0-alpha.17.2(desktop26.1007.71326),0.162.1 and reviewed standalone0.163.0(source1.42.6)/0.164.0(source1.42.7). The latter requires tagged-schema review and actual16 native terminal contracts on both architectures; later versions and mismatched initialization remain unavailable. The approved installed-desktop checksum manifest is unchanged. Unsupported filesystems, proc access or protocols report unavailable, with no execution fallback.

The configuration inspection path omits legacy isolated-runtime file/provider overrides, removes native loader injection variables from its child, and requests config/read plus configRequirements/read after initialization. It validates the actual returned home/platform/version/schema and managed-policy consistency. Only observed explicit file permits file-credential capability; keyring, auto, ephemeral, forced API login, managed login restrictions, workspace mismatch and unknown/inconsistent contracts do not. Reported file eligibility does not enable an account action or certify authentication. Config, workspace IDs, personal paths, raw errors and credential values are not exported. Reports use new0600 files in owned0700 directories with no-follow/exclusive creation and cannot replace an existing input/report.

The inspected desktop CLI's generated ConfigReadParams accepts only cwd and includeLayers; its app-server rejects the runtime-only --profile flag and legacy root profile/[profiles] configuration. Such errors report unavailable instead of rewriting input or treating an uninspected profile as active. Current inspection states SelectedHomeContext; project/runtime-profile-aware account operations remain a later compatibility gate before account actions are enabled.

The native CI installs only the checksum-pinned official package on an explicitly disposable runner, checks native trust failures, and exercises ordinary effective configuration/system layers/managed requirements. It never changes a pre-existing system policy: any such policy makes the test refuse. Each test-created policy is removed only after verifying its exact owned contents; all synthetic input bytes are compared before/after. Raw package/provider/client state is never uploaded. Actual x64/ARM64 source-window images and all six final-head workflows remain required before promotion. KDE/KWallet55, real manual switching/resumption6 and clean packages7 stay open. Official Linux package guidance, native config RPC, credential policy.