@infrarates/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oimo Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,249 @@
-# Temporary Holding Version
+# Oimo CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Requires Node.js 22.11 or newer, with no runtime dependencies. The npm
+package is `@infrarates/cli` and the command is `oimo`. MIT licence.
+
+Install it from public npm (see [Releases](#releases)):
+
+```sh
+npm install -g @infrarates/cli          # install
+npm install -g @infrarates/cli@latest   # update to the newest release
+oimo --version
+npm uninstall -g @infrarates/cli        # remove
+```
+
+From a checkout, `npm install -g .` in this directory or `node oimo.mjs`
+runs the unreleased code. Run `npm test` for its tests.
+
+## Read data with an organization API key
+
+Create a key on the Oimo **API keys** page. The server accepts keys for
+reviewed price history, customer price/terms/status reads, providers, catalog,
+activity and comparisons. These additional key routes require deploying the
+accompanying providers-tracker-ui changes.
+
+```sh
+export OIMO_API_KEY='your-organization-api-key'
+oimo providers list
+oimo prices latest --provider openai --limit 100
+oimo prices history --providers openai,anthropic --all > prices.json
+oimo terms latest --provider openai
+oimo terms diff --provider openai --doc terms-of-use
+oimo status
+oimo catalog --provider openai
+oimo compare resources
+oimo compare prices --resource 'resource-id-from-compare-resources'
+```
+
+Keys always get the customer view, even if a staff session also exists. Pending
+rows are hidden and status responses omit internal details. Keys carry an
+organization identity and no user role; management and personal commands require
+a user session.
+
+`OIMO_API_KEY` is not tied to an origin. A command that accepts a key
+sends it, as a Bearer header, to the origin that command targets:
+`https://oimo.com` by default, otherwise the one named by `--base-url` or
+`OIMO_BASE_URL`. This differs from saved sessions, which are stored per
+origin and never sent anywhere else. The origin must be HTTPS (HTTP only on
+loopback) and redirects are refused, so the key reaches the origin you named
+and no other. When a key is set, no session is sent with it; session commands
+never send the key.
+
+A key works only in the environment that issued it, so create one per
+environment and set it for the command instead of exporting a production key
+in a shell that also targets other origins:
+
+```sh
+OIMO_API_KEY="$OIMO_DEVELOP_KEY" oimo prices latest --base-url https://oimo.dev
+OIMO_API_KEY="$OIMO_DEVELOP_KEY" OIMO_BASE_URL=https://oimo.dev oimo status
+```
+
+Do not point `--base-url` or `OIMO_BASE_URL` at an origin you do not
+trust with the key in your environment.
+
+## Customer operations with a session
+
+Run `oimo login`. It opens your default browser, signs you in through the
+website's existing WorkOS flow, and asks you to approve CLI access for the shown
+account. Approval starts a fresh WorkOS authorization-code exchange for the CLI;
+AuthKit requires a fresh sign-in (`max_age=0`). The new session has its own
+refresh token, so browser and CLI refreshes do not invalidate each other. The callback leaves
+the website's session and staff organization selection in place. No cookie
+copying is needed.
+The CLI validates the returned session with `/v1/me` before saving it.
+
+Automatic login requires deploying the accompanying `/auth/cli` server routes.
+Use `--base-url https://oimo.dev` to sign in against the develop deployment.
+For local development, start the service with `AUTH_DEV_USER=you@example.com`
+and run `oimo login --base-url http://localhost:8080`.
+
+If your browser cannot be launched automatically, the terminal prints a URL.
+Open it on the same computer. `login --no-browser` prints the URL without trying
+to launch a browser. Login waits up to five minutes; `--timeout <seconds>` sets
+a deadline from 1 to 600 seconds. Ctrl-C or the browser's Cancel button ends it.
+
+The handoff uses a temporary listener bound to `127.0.0.1`, a random state value,
+and an ephemeral X25519 key. The server requires same-origin browser consent,
+binds the new code exchange to the approved account with a separate signed
+OAuth state cookie, and encrypts the new CLI session with
+X25519/HKDF-SHA256/AES-256-GCM. The encrypted result is POSTed to loopback,
+with no credentials in URLs or the terminal. The CLI checks
+the browser Origin, callback state, encryption tag and expiry, then closes the
+listener. The handshake uses no persistent server records and works across
+service instances.
+
+`login --session-stdin` retains manual session import for scripts: it reads
+`OIMO_SESSION` or a session value from stdin. Automatic browser login
+always obtains a fresh session even if that environment variable is set.
+Manually importing a browser session shares its refresh token; use browser
+login to obtain independent credentials. Existing CLI sessions created before
+this change must log in again to gain that independence.
+
+```sh
+oimo login
+oimo me
+oimo organizations get
+oimo organizations create --data '{"name":"My workspace"}'
+oimo organizations switch --data '{"organizationId":"org_..."}'
+oimo webhooks list
+oimo webhooks create --data @webhook.json
+oimo webhooks deliveries webhook-id
+oimo webhooks test webhook-id
+oimo members list
+oimo members update membership-id --data '{"role":"member"}'
+oimo invitations create --data '{"email":"person@example.com","role":"member"}'
+oimo api-keys create --data '{"name":"My integration"}'
+oimo preferences get
+oimo provider-requests list
+oimo logout
+```
+
+The CLI sends the session cookie and target Origin; existing role checks, current
+membership checks, tenant boundaries and last-admin protection remain in force.
+Admins manage people; admins and members manage integrations. Creation and
+rotation commands print newly issued API keys or signing secrets in their JSON
+responses, as the API does. JSON bodies may be inline, `@file.json`, or `-` for
+stdin. See the service README for request-body schemas and `oimo --help`
+for every command and its options.
+
+Sessions are stored per origin at `~/.config/oimo/sessions.json` with
+permissions 0600. `--config <file>` overrides the location. Responses that rotate
+or switch sessions update the saved value, and one that ends the session removes
+it; when a response sets the cookie twice, the last one is kept, as in a
+browser. Each update is applied to the file's current contents under a lock
+file (`sessions.json.lock`), so commands running at the same time, against the
+same or different origins, do not undo each other's rotations or logouts. The
+organization a staff user is viewing is saved beside the session
+and sent with later commands, until a switch into an organization they belong
+to, a new login or `logout` clears it. An environment session overrides the
+saved value and keeps nothing between commands, so a staff viewer selection
+does not carry over; unset it after login to use the saved session and
+rotations. `logout` removes only the selected origin's local session; it does
+not revoke either remote WorkOS session or unset environment credentials.
+Website logout ends the browser's WorkOS session and leaves an independently
+created CLI session usable. Revoking the CLI's WorkOS session leaves the browser
+session usable; revoking all sessions for the user ends both. Revocation is
+enforced when the affected access token expires and its next refresh fails.
+
+## Output and paging
+
+`prices history` shows a readable table in an interactive terminal: provider,
+resource, dimension, exact price with currency, and billing unit. Each observation
+also shows its tier, source and recorded timestamp, plus effective dates and
+renames when present. Names wrap rather than being truncated; very narrow
+terminals use stacked observations. The header shows the pinned snapshot and
+providers, and a paginated result prints a command to read the next page with
+the same `--base-url`, `--limit` and `--config`.
+
+Piping or redirecting history output defaults to JSON with all original fields.
+Use `--format json` to get JSON in the terminal, or `--format table` to redirect
+the readable display. Rates retain their decimal strings and native currencies
+and units, without conversions or rounding. Other commands print JSON; empty
+responses print `null`, and `terms content` prints the upstream text.
+Terms are vendor-written, so in an interactive terminal their control
+characters (escape sequences, BEL, bidirectional overrides) are shown escaped
+as `\uXXXX` instead of being interpreted; line breaks and tabs are kept. Piped
+or redirected output is the text as served.
+Errors go to stderr with exit code 1.
+
+`prices history` reads `/v1/prices/history`, including older rates. By default,
+one page is read. JSON includes `asOf`, `providers`, `prices` and `nextCursor`. `--all` combines
+all pages in memory and prints only after every page succeeds. The cursor pins
+the snapshot and providers; subsequent requests send only cursor and limit.
+`--alias` takes an alias group's id or comparison name (`compare aliases` lists
+them) and reads that resource at every provider that sells it; the answer adds
+`alias` with the group's revision and members, and the cursor pins that revision.
+Keep `asOf` to reproduce a reading. Default page size is 5000, maximum 10000.
+Credit-denominated providers require explicit selection under the API defaults.
+
+```sh
+oimo prices history --as-of 2026-10-01T00:00:00Z --limit 100
+oimo prices history --providers openai --limit 20
+oimo prices history --providers openai --format json
+oimo prices history --alias claude-opus-5.5 --all
+oimo prices history --all > prices.json
+oimo prices history --cursor 'cursor-from-previous-response'
+oimo prices resource-history --provider openai --resource gpt-5
+oimo prices latest --provider openai --offset 100 --limit 100 --sort price --dir asc
+oimo prices history --base-url https://oimo.dev --all
+```
+
+`prices latest` uses offset paging (maximum 1000 rows per page; without
+`--limit`, an API key or a customer session gets the first 1000); it is a current
+reading, not a pinned export, and has no automatic paging. `resource-history`
+reads the existing per-resource `/api/prices/history` endpoint. Other list
+commands follow their existing API bounds; use `--after` where shown in help.
+Timestamps and provider names are validated by the API.
+
+`OIMO_BASE_URL` sets a default origin; `--base-url` overrides it. Saved
+sessions are never sent to another origin; an environment API key goes to the
+selected origin (see above). HTTP is supported only on loopback
+for local development. Redirects are refused and each request times out after
+30 seconds. Requests are not automatically retried, including mutations.
+
+## Releases
+
+The package is `@infrarates/cli` on public npm, first released as 0.1.0
+(OIM-511). The `@infrarates` scope is the one Oimo can already publish to: its packages
+are maintained by Jorge's personal npm account (`jtkm6`), which is also the
+account that links the package to the publish workflow. The owner of `@oimo`
+is unconfirmed. The command stays `oimo`.
+
+- `oimo --version` prints the installed package's `package.json` version, so
+  a release changes only that file. Versions follow semver: a removed or
+  renamed command or option is a major bump while the version is 1.x or
+  later (a minor one while it is 0.x).
+- `install-smoke.mjs` (part of `npm test`) packs the package, checks the
+  tarball holds exactly `package.json` and the `files` list (which includes
+  `LICENSE`), installs it globally into an empty prefix with an empty npm
+  cache and config, runs the installed `oimo` from outside the repository,
+  installs the next patch release's tarball over it (the upgrade path, e.g.
+  0.1.0 → 0.1.1), then uninstalls it. Release versions are plain
+  `MAJOR.MINOR.PATCH`; the test refuses any other `package.json` version. It
+  has passed on `node:22.11.0-slim` (the `engines` floor) and `node:24-slim`
+  with only this directory copied in:
+
+  ```sh
+  podman run --rm -v "$PWD:/src:ro,Z" node:22.11.0-slim \
+    sh -c 'cp -r /src /cli && cd /cli && npm test'
+  ```
+
+- `.github/workflows/publish-cli.yml` publishes. A pull request that touches
+  this directory runs the tests and `npm publish --dry-run`. To release:
+  1. merge a PR that bumps `version` in `package.json`;
+  2. tag that merged commit `cli-v<version>` and push the tag
+     (`git tag cli-v0.1.1 <sha> && git push origin cli-v0.1.1`);
+  3. a platform reviewer approves the run in the `npm-publish` environment.
+
+  The workflow refuses a tag that does not match `package.json` or a commit
+  that is not on `main`. It publishes with npm trusted publishing, where the
+  job's GitHub OIDC token buys a one-time publish token, so no npm token is
+  stored. It then installs the published version from npm on Node 22.11 and
+  checks `oimo --version`. There is no provenance attestation because the
+  repository is private.
+
+  The package's Trusted Publisher settings on npmjs.com link it to
+  `oimo-ai/oimo`, `publish-cli.yml` and the `npm-publish` environment, which
+  is what lets that one job publish without a token. npm also requires
+  `repository.url` in `package.json` to name `oimo-ai/oimo` exactly;
+  without it the publish fails with only `ENEEDAUTH`.

package/browser-login.d.mts

@@ -0,0 +1,14 @@
+export function openBrowser(
+  url: string,
+  platform?: NodeJS.Platform,
+): Promise<void>;
+export function browserLogin(
+  origin: string,
+  options?: {
+    opener?: (url: string) => Promise<unknown>;
+    noBrowser?: boolean;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    report?: (text: string) => void;
+  },
+): Promise<string>;

package/browser-login.mjs

@@ -0,0 +1,244 @@
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import {
+  createDecipheriv,
+  createPublicKey,
+  diffieHellman,
+  generateKeyPairSync,
+  hkdfSync,
+  randomBytes,
+  timingSafeEqual,
+} from "node:crypto";
+
+export function openBrowser(url, platform = process.platform) {
+  const [command, args] =
+    platform === "darwin"
+      ? ["open", [url]]
+      : platform === "win32"
+        ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+        : ["xdg-open", [url]];
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "ignore", shell: false });
+    child.once("error", reject);
+    child.once("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error("Browser launch failed")),
+    );
+    child.unref();
+  });
+}
+const matches = (left, right) => {
+  if (typeof left !== "string") return false;
+  const a = Buffer.from(left),
+    b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+};
+
+function decrypt(payload, privateKey, origin, callback, state) {
+  if (typeof payload !== "string" || !/^[A-Za-z0-9_-]+$/.test(payload))
+    throw new Error();
+  const envelope = JSON.parse(
+    Buffer.from(payload, "base64url").toString("utf8"),
+  );
+  if (
+    envelope.v !== 1 ||
+    typeof envelope.key !== "string" ||
+    !/^[A-Za-z0-9_-]{43}$/.test(envelope.key)
+  )
+    throw new Error();
+  for (const field of ["iv", "ciphertext", "tag"])
+    if (
+      typeof envelope[field] !== "string" ||
+      !/^[A-Za-z0-9_-]+$/.test(envelope[field])
+    )
+      throw new Error();
+  const publicKey = createPublicKey({
+    key: { kty: "OKP", crv: "X25519", x: envelope.key },
+    format: "jwk",
+  });
+  const info = Buffer.from(
+    JSON.stringify(["oimo-cli-login-v1", origin, callback, state]),
+  );
+  const key = Buffer.from(
+    hkdfSync(
+      "sha256",
+      diffieHellman({ privateKey, publicKey }),
+      Buffer.from(state, "base64url"),
+      info,
+      32,
+    ),
+  );
+  const iv = Buffer.from(envelope.iv, "base64url"),
+    tag = Buffer.from(envelope.tag, "base64url");
+  if (iv.length !== 12 || tag.length !== 16) throw new Error();
+  const decipher = createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAAD(info);
+  decipher.setAuthTag(tag);
+  const value = JSON.parse(
+    Buffer.concat([
+      decipher.update(Buffer.from(envelope.ciphertext, "base64url")),
+      decipher.final(),
+    ]).toString("utf8"),
+  );
+  if (
+    value.origin !== origin ||
+    !matches(value.state, state) ||
+    !Number.isSafeInteger(value.expiresAt) ||
+    value.expiresAt <= Date.now() ||
+    value.expiresAt > Date.now() + 120_000
+  )
+    throw new Error();
+  if (value.cancelled === true) return null;
+  if (
+    typeof value.session !== "string" ||
+    !value.session ||
+    /[\s;,\x00-\x1f\x7f]/.test(value.session)
+  )
+    throw new Error();
+  return value.session;
+}
+
+/** Bind before launching the browser; accept one authenticated handoff only. */
+export async function browserLogin(
+  origin,
+  {
+    opener = openBrowser,
+    noBrowser = false,
+    timeoutMs = 300_000,
+    signal,
+    report = (text) => process.stderr.write(text),
+  } = {},
+) {
+  const { privateKey, publicKey } = generateKeyPairSync("x25519");
+  const state = randomBytes(32).toString("base64url");
+  let callback,
+    host,
+    completed = false,
+    timer;
+  let resolveLogin, rejectLogin;
+  const received = new Promise((resolve, reject) => {
+    resolveLogin = resolve;
+    rejectLogin = reject;
+  });
+  // Install a rejection handler while the browser-launch promise is pending.
+  received.catch(() => {});
+  const server = createServer(async (request, response) => {
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    response.setHeader(
+      "Content-Security-Policy",
+      "default-src 'none'; frame-ancestors 'none'",
+    );
+    response.setHeader("Referrer-Policy", "no-referrer");
+    const fail = (status) => {
+      response.writeHead(status);
+      response.end("Invalid sign-in callback.");
+    };
+    if (
+      completed ||
+      request.method !== "POST" ||
+      request.url !== "/callback" ||
+      request.headers.host !== host ||
+      request.headers.origin !== origin ||
+      request.headers["content-type"]?.split(";", 1)[0] !==
+        "application/x-www-form-urlencoded"
+    ) {
+      fail(403);
+      return;
+    }
+    try {
+      let size = 0;
+      const chunks = [];
+      for await (const chunk of request) {
+        size += chunk.length;
+        if (size > 65_536) {
+          fail(413);
+          request.resume();
+          return;
+        }
+        chunks.push(chunk);
+      }
+      const form = new URLSearchParams(Buffer.concat(chunks).toString("utf8"));
+      if (
+        form.getAll("state").length !== 1 ||
+        form.getAll("payload").length !== 1 ||
+        !matches(form.get("state"), state)
+      ) {
+        fail(403);
+        return;
+      }
+      const session = decrypt(
+        form.get("payload"),
+        privateKey,
+        origin,
+        callback,
+        state,
+      );
+      if (completed) {
+        fail(409);
+        return;
+      }
+      completed = true;
+      response.end(
+        session
+          ? "Signed in to Oimo CLI. You can close this tab."
+          : "CLI sign-in cancelled. You can close this tab.",
+        () => {
+          if (session) resolveLogin(session);
+          else rejectLogin(new Error("CLI sign-in cancelled."));
+        },
+      );
+    } catch {
+      if (!response.headersSent) fail(400);
+    }
+  });
+  server.requestTimeout = 15_000;
+  server.headersTimeout = 10_000;
+  server.keepAliveTimeout = 1_000;
+  const abort = () => rejectLogin(new Error("CLI sign-in cancelled."));
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    host = `127.0.0.1:${server.address().port}`;
+    callback = `http://${host}/callback`;
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) {
+      abort();
+      return await received;
+    }
+    timer = setTimeout(
+      () =>
+        rejectLogin(
+          new Error(
+            "CLI sign-in timed out. Run oimo login again. New to Oimo? Accounts open from the waitlist: run oimo login once your invitation email has arrived and you have finished signing up.",
+          ),
+        ),
+      timeoutMs,
+    );
+    const url = new URL("/auth/cli", origin);
+    url.search = new URLSearchParams({
+      callback,
+      state,
+      key: publicKey.export({ format: "jwk" }).x,
+    }).toString();
+    report(`Finish sign-in in your browser:\n${url.href}\n`);
+    if (!noBrowser) {
+      // Launching may hang on a headless system; it must not extend the login deadline.
+      void Promise.resolve()
+        .then(() => opener(url.href))
+        .catch(() =>
+          report(
+            "Could not open a browser automatically. Open the link above on this computer.\n",
+          ),
+        );
+    }
+    return await received;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", abort);
+    server.close();
+    server.closeAllConnections();
+  }
+}