@traice/codex-collector 0.1.2 → 0.1.3

package/README.md

@@ -71,9 +71,9 @@ The installer:
 - creates or reuses the `internal-spend-poc` workspace in local dev
 - enables the workspace `internalSpendEnabled` flag
 - creates a real API key for `/api/v1/internal-usage`
-- writes private collector config, including the API key, to
-  `~/.traice/internal-spend-codex/install.json` (user-only mode on macOS/Linux;
-  the user-profile ACL on Windows)
+- stores the API key in macOS Keychain, Windows Credential Manager, or Linux
+  Secret Service and writes only its reference to
+  `~/.traice/internal-spend-codex/install.json`
 - appends an idempotent trAIce `[otel]` block to user-level
   `~/.codex/config.toml`
 
@@ -145,8 +145,20 @@ contract and fill employee/team fields directly or via identity mapping.
 The API key can be provided with `TRAICE_API_KEY`, `--api-key-stdin`, or
 `--api-key`. Prefer `TRAICE_API_KEY` or `--api-key-stdin` for user installs so
 keys do not end up in shell history. A later `install` reuses the saved key, and
-`collect` always reads it from the private config, so neither command prompts
-again unless the config was removed.
+`collect` resolves it from secure storage, so neither command prompts again.
+
+Credential storage defaults to `--credential-store auto`. It uses the native OS
+credential manager when available. On headless systems it falls back explicitly
+to `~/.traice/internal-spend-codex/credentials.json` with a user-only directory
+and file (`0700`/`0600` on POSIX); that fallback is not encrypted at rest. Use
+`--credential-store keyring` to require native secure storage and fail rather
+than fall back, or `--credential-store file` for an externally encrypted or
+managed environment. Existing plaintext `install.json` credentials migrate on
+the next `install` or `collect`.
+
+For containers, CI, MDM, or an external secret manager, inject
+`TRAICE_API_KEY` only into the `collect` process. That override is used without
+being persisted.
 
 Private config and collector state default to `~/.traice/internal-spend-codex`.
 Use `--out /path/to/private-dir` only when an org installer manages that
@@ -187,3 +199,16 @@ The collector keeps local dedupe state in:
 ```
 
 so restarting it should not intentionally duplicate historical rows.
+
+## Releasing
+
+Do not run `npm publish` locally. From the platform repository, run:
+
+```bash
+npm run release:prepare
+```
+
+This opens a version PR. Merging the reviewed PR triggers GitHub Actions and npm
+trusted publishing (OIDC), so publishing never requires an npm token or an
+interactive `npm login`. Pass `minor`, `major`, or an explicit version after `--`
+when the default patch bump is not appropriate.

package/collector.mjs

@@ -6,6 +6,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statS
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { gunzipSync } from "node:zlib";
+import { readApiKeyCredential, storeApiKey } from "./credentials.mjs";
 
 const DEFAULT_OUT_DIR = "~/.traice/internal-spend-codex";
 const LEGACY_OUT_DIR = ".traice-internal-spend";
@@ -17,16 +18,18 @@ const collectorStartedAtMs = Date.now();
 const pendingTurnLatency = new Map();
 
 const args = parseArgs(process.argv.slice(2));
+const inheritedApiKey = process.env.TRAICE_API_KEY;
 loadEnvFile(resolve("apps/web/.env"));
 
 const configPath = args.get("config") ? resolveHome(args.get("config")) : findDefaultInstallConfigPath();
 const outDir = resolveHome(args.get("out") ?? dirname(configPath));
 const installConfig = readJsonIfExists(configPath) ?? {};
+const apiKey = await resolveCollectorApiKey();
 const config = {
   serverUrl: normalizeUrl(
     args.get("server-url") ?? installConfig.serverUrl ?? process.env.TRAICE_API_URL ?? "http://127.0.0.1:3003",
   ),
-  apiKey: readApiKey() ?? installConfig.apiKey ?? process.env.TRAICE_API_KEY,
+  apiKey,
   workspaceSlug: args.get("workspace-slug") ?? installConfig.workspaceSlug ?? "internal-spend-poc",
   sourceKey: args.get("source-key") ?? installConfig.sourceKey ?? "codex-local",
   sourceName: args.get("source-name") ?? installConfig.sourceName ?? "Codex local collector",
@@ -55,6 +58,21 @@ const config = {
   maxBatchSize: parsePositiveInt(args.get("max-batch-size") ?? installConfig.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE),
 };
 
+async function resolveCollectorApiKey() {
+  const explicitApiKey = readApiKey() ?? inheritedApiKey;
+  if (explicitApiKey) return explicitApiKey;
+  if (installConfig.apiKeyCredential) return readApiKeyCredential(installConfig.apiKeyCredential);
+  if (installConfig.apiKey) {
+    const stored = await storeApiKey(configPath, installConfig.apiKey, "auto");
+    const migrated = { ...installConfig, apiKeyCredential: stored.credential };
+    delete migrated.apiKey;
+    writeFileSync(configPath, `${JSON.stringify(migrated, null, 2)}\n`, { mode: 0o600 });
+    if (stored.warning) console.warn(`[codex-otel] ${stored.warning}`);
+    return readApiKeyCredential(stored.credential);
+  }
+  return undefined;
+}
+
 if (!config.apiKey) {
   console.error(
     [

package/credentials.mjs

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const KEYRING_SERVICE = "trAIce Codex Collector";
+
+export async function storeApiKey(configPath, apiKey, mode = "auto", dependencies = {}) {
+  const account = `config-${createHash("sha256").update(resolve(configPath)).digest("hex").slice(0, 24)}`;
+  if (mode !== "file") {
+    try {
+      const entry = await createEntry(KEYRING_SERVICE, account, dependencies);
+      await entry.setPassword(apiKey);
+      if ((await entry.getPassword()) !== apiKey) throw new Error("credential verification failed");
+      return { credential: { backend: "os-keyring", service: KEYRING_SERVICE, account } };
+    } catch (error) {
+      if (mode === "keyring") throw new Error(`OS credential store unavailable: ${errorMessage(error)}`);
+      return {
+        credential: writeProtectedFile(configPath, apiKey),
+        warning: `OS credential store unavailable; using a user-only protected file (${errorMessage(error)}).`,
+      };
+    }
+  }
+  return { credential: writeProtectedFile(configPath, apiKey) };
+}
+
+export async function readApiKeyCredential(credential, dependencies = {}) {
+  if (credential?.backend === "os-keyring") {
+    const entry = await createEntry(credential.service, credential.account, dependencies);
+    const apiKey = await entry.getPassword();
+    if (!apiKey) throw new Error("Collector API key was not found in the OS credential store. Re-run install.");
+    return apiKey;
+  }
+  if (credential?.backend === "protected-file") {
+    const stored = dependencies.readJson?.(credential.path) ?? readJson(credential.path);
+    if (stored?.apiKey) return stored.apiKey;
+    throw new Error(`Collector API key was not found in ${credential.path}. Re-run install.`);
+  }
+  return null;
+}
+
+async function createEntry(service, account, dependencies) {
+  if (dependencies.createEntry) return dependencies.createEntry(service, account);
+  const { AsyncEntry } = await import("@napi-rs/keyring");
+  return new AsyncEntry(service, account);
+}
+
+function writeProtectedFile(configPath, apiKey) {
+  const directory = dirname(resolve(configPath));
+  const path = resolve(directory, "credentials.json");
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(directory, 0o700);
+  } catch {
+    // Windows uses the ACL inherited from the user's profile directory.
+  }
+  writeFileSync(path, `${JSON.stringify({ apiKey }, null, 2)}\n`, { mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // Best effort on non-POSIX filesystems.
+  }
+  return { backend: "protected-file", path };
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/install.mjs

@@ -5,6 +5,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, copyFile
 import { homedir, hostname, userInfo } from "node:os";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { readApiKeyCredential, storeApiKey } from "./credentials.mjs";
 
 const DEFAULT_OUT_DIR = "~/.traice/internal-spend-codex";
 const LEGACY_INSTALL_CONFIG = ".traice-internal-spend/install.json";
@@ -46,6 +47,7 @@ const sourcePrincipal = args.get("source-principal") ?? `${hostname()}:${userInf
 const seatMonthlyUsd = parseOptionalMoney(args.get("seat-monthly-usd") ?? process.env.TRAICE_SEAT_MONTHLY_USD);
 const providedApiKey = readApiKey();
 const backfillHours = parseBackfillHours(args.get("backfill-hours") ?? "all");
+const credentialStore = parseCredentialStore(args.get("credential-store") ?? "auto");
 
 mkdirSync(outDir, { recursive: true, mode: 0o700 });
 try {
@@ -55,19 +57,23 @@ try {
 }
 
 const previousInstall = readJsonIfExists(installPath) ?? readLegacyInstallIfDefaultOut();
-const previousApiKey = typeof previousInstall?.apiKey === "string" ? previousInstall.apiKey : null;
+let previousApiKey = typeof previousInstall?.apiKey === "string" ? previousInstall.apiKey : null;
+if (!providedApiKey && !previousApiKey && previousInstall?.apiKeyCredential) {
+  previousApiKey = await readApiKeyCredential(previousInstall.apiKeyCredential);
+}
 
 let prisma = null;
 
 try {
   const reusableApiKey = providedApiKey || previousApiKey;
   const setup = reusableApiKey ? providedApiKeySetup(reusableApiKey, !providedApiKey) : await localDevSetup();
+  const storedApiKey = await storeApiKey(installPath, setup.key.raw, credentialStore);
 
   const installConfig = {
     version: 2,
     installedAt: new Date().toISOString(),
     serverUrl,
-    apiKey: setup.key.raw,
+    apiKeyCredential: storedApiKey.credential,
     apiKeyPrefix: setup.key.prefix,
     workspaceId: setup.workspace.id,
     workspaceSlug: setup.workspace.slug,
@@ -110,6 +116,10 @@ try {
         mode: setup.mode,
         workspace: setup.workspace,
         apiKey: { prefix: setup.key.prefix, reused: setup.key.reused },
+        credentialStorage: {
+          backend: storedApiKey.credential.backend,
+          warning: storedApiKey.warning,
+        },
         identity: { employeeEmail, employeeName, teamName, sourcePrincipal },
         cost: { seatMonthlyUsd },
         installConfig: installPath,
@@ -464,6 +474,12 @@ function parseBackfillHours(value) {
   return parsed;
 }
 
+function parseCredentialStore(value) {
+  if (["auto", "keyring", "file"].includes(value)) return value;
+  console.error(`Invalid credential store: ${value}. Use "auto", "keyring", or "file".`);
+  process.exit(2);
+}
+
 function generateApiKey() {
   const raw = `lm_live_${randomBytes(24).toString("hex")}`;
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@traice/codex-collector",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Local Codex usage collector for trAIce Internal Spend.",
   "license": "UNLICENSED",
   "type": "module",
@@ -14,13 +14,16 @@
   "engines": {
     "node": ">=20"
   },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  },
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@ssh.github.com/shmulikdav/trAIce.git",
+    "url": "git+https://github.com/runtraice/trAIce.git",
     "directory": "tools/internal-spend-codex"
   },
   "bugs": {
-    "url": "https://github.com/shmulikdav/trAIce/issues"
+    "url": "https://github.com/runtraice/trAIce/issues"
   },
   "homepage": "https://runtraice.com",
   "keywords": [
@@ -37,6 +40,7 @@
   "files": [
     "cli.mjs",
     "collector.mjs",
+    "credentials.mjs",
     "install.mjs",
     "README.md"
   ]