From 48a19c55b829934d974f0bdf016c422f1c7b7f49 Mon Sep 17 00:00:00 2001 From: Marmel Coder Date: Thu, 12 Nov 2026 16:59:24 +0300 Subject: [PATCH] feat: export and document codex-oauth-proxy user service --- README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ flake.nix | 1 + 2 files changed, 92 insertions(+) diff --git a/README.md b/README.md index 18bc8da..32ae61c 100644 --- a/README.md +++ b/README.md @@ -186,6 +186,97 @@ Note: the `node_modules` symlink is shared across everything in the plugins directory; other manually-installed plugins with conflicting npm dependencies cannot coexist with it. +### Codex OAuth Proxy (systemd user service) + +On Linux with a running systemd user manager, the package provides +`lib/systemd/user/codex-oauth-proxy.service`. Installing the package alone does +not enable or start it. To use the packaged unit without Home Manager: + +```bash +package=$(nix build --no-link --print-out-paths \ + git+https://git.millerson.name/alex/millerson-overlay.nix.git#codex-oauth-proxy) +systemctl --user enable --now "$package/lib/systemd/user/codex-oauth-proxy.service" +systemctl --user status codex-oauth-proxy.service +``` + +Keep the selected package in a Nix profile or another garbage-collection root +while using its unit. To stop it and remove its enablement links: + +```bash +systemctl --user disable --now codex-oauth-proxy.service +``` + +Do not manage the same unit with both this procedure and Home Manager. + +#### Home Manager + +Import the module and make the package available in Home Manager's `pkgs`: + +```nix +imports = [ millerson-nix-overlay.homeManagerModules.default ]; +nixpkgs.overlays = [ millerson-nix-overlay.overlays.default ]; + +programs.codex-oauth-proxy.enable = true; +``` + +The module installs the package and manages the user unit and its +`default.target` link. Its package default selects +`pkgs.millerson-nix-overlay.codex-oauth-proxy`, falling back to +`pkgs.codex-oauth-proxy`. Importing `homeManagerModules.default` does not add an +overlay. Supply the overlay to the actual Home Manager package set, or set +`programs.codex-oauth-proxy.package` explicitly to this flake's package for your +system. + +Apply the configuration with your normal Home Manager activation. Enabling +starts this service without changing `systemd.user.startServices`. To stop and +disable a previously module-managed service, keep the import and apply: + +```nix +programs.codex-oauth-proxy.enable = false; +``` + +Removing the import also removes the cleanup hook, so first activate with +`enable = false`. A fresh disabled configuration leaves a manually managed +same-named service untouched. Starting or stopping a module-managed service +requires an available user manager; activation reports failure if it is unavailable. The module does not enable +lingering or change the global service activation policy. + +#### State and security + +Both units use persistent OAuth state at `%S/codex-oauth-proxy/auth.json`, +normally `~/.local/state/codex-oauth-proxy/auth.json` in a user manager. The state +directory has mode `0700` and the service umask is `0077`. Upstream may migrate +existing credentials when the destination is absent, and refreshes rewrite the +credential file. Keep it writable and outside the Nix store and immutable Home +Manager files. Disabling the service does not delete this credential state. +Missing credentials do not prevent startup, but successful upstream requests +require valid credentials. + +The server binds all interfaces on port `9879` by default, not just loopback. +Restrict access with your network/firewall configuration. The service does not +add TLS or network access controls. + +`ADMIN_API_KEY` protects upstream's admin endpoints. No default key is generated. +If unset or empty, protected requests return HTTP 500; the server can still +start. The packaged unit does not set this variable; a user-manager environment +can supply it. Home Manager has an optional literal setting (placeholder only): + +```nix +programs.codex-oauth-proxy.admin_api_key = "REPLACE_WITH_NON_SECRET_PLACEHOLDER"; +``` + +The default `null` omits the assignment. A non-null value must contain printable +ASCII; an empty string explicitly supplies an empty value. **A literal key in +this option is public in the Nix store, retained generations, and systemd +introspection. Do not put a confidential production key here.** This option is +not a runtime secret-delivery mechanism. + +Both units discard stdout and stderr because upstream logs token previews and +other potentially sensitive request/response data. Production mode does not +establish redaction. Application logs are therefore unavailable in the journal; +systemd status and exit diagnostics remain. Do not override these output settings +without first addressing upstream token logging. + ### PdfCraft (Home Manager) `pdfcraft` is built from source (no upstream binaries are downloaded). A Home diff --git a/flake.nix b/flake.nix index 51dd652..1c46314 100644 --- a/flake.nix +++ b/flake.nix @@ -66,6 +66,7 @@ homeManagerModules.default = { imports = [ + ./modules/codex-oauth-proxy-hm.nix ./modules/open-code-review-hm.nix ./modules/pdfcraft-hm.nix ];