@tonbo/cli 0.6.0 → 0.6.1

package/README.md

@@ -96,7 +96,7 @@ tonbo api-key create ci-reader --member pi-live --read-only --bucket events --ex
 tonbo api-key revoke 70000000-0000-4000-8000-000000000007
 ```
 
-`api-key list` shows your keys, or every key of the account for an owner or admin, with the last four characters of each secret. `api-key create` creates a personal key for you, or with `--member` a key of an Agent (its subject, id or name; owners and admins only). `--read-only`, and either `--bucket` or `--database` and `--database-prefix` (repeat each for several), narrow the key for its whole life; `--expires-in` is one of `15_days`, `1_month`, `6_months`, `1_year` or `never` (the default). The secret is printed once, in that answer only, with a warning on stderr: store it then, because no command can show it again. `api-key show` prints one key, and `api-key revoke` revokes it and every token minted from it.
+`api-key list` shows your keys, or every key of the account for an owner or admin, with the last four characters of each secret. `api-key create` creates a personal key for you, or with `--member` a key of an Agent (its subject, id or name; owners and admins only). `--read-only`, and either `--bucket` or `--database` and `--database-prefix` (repeat each for several), narrow the key for its whole life; `--expires-in` is one of `15_days`, `1_month`, `6_months`, `1_year` or `never` (the default). The secret is printed once, in that answer only, with a warning on stderr: store it then, because no command can show it again. Without `--json`, the answer also carries a ready-to-paste `TONBO_API_KEY=<secret>` line on stdout, beside the secret, for your application's environment (a `.env` file or a secret store), and stderr notes that `TONBO_API_KEY` in your own shell overrides your `tonbo login`, for this CLI too. stderr never carries the secret, and `--json` prints only the answer. `api-key show` prints one key, and `api-key revoke` revokes it and every token minted from it.
 
 ## Buckets
 
@@ -108,6 +108,22 @@ tonbo bucket delete events
 
 `bucket list` and `bucket show` print each bucket's region, state, read access and URL; a stream lives at `{url}/{stream}`. `bucket create` creates a bucket in `--region`, or in the account's default region. `bucket update` publishes a bucket for anonymous reads with `--public` or takes it private with `--private`. `bucket delete` deletes a bucket and every stream in it; the bucket's name is never used again.
 
+## Databases
+
+```console
+tonbo database create notes
+tonbo database show notes
+```
+
+`database create` creates a database in `--region`, or in the default region, and prints its fields with its URL. Without `--json` it then writes the next step to stderr, opening the database by name from code:
+
+```text
+Next: npm i @tonbo/sqlite-ursula
+      open("notes") from "@tonbo/sqlite-ursula/tonbo"
+```
+
+`open("notes")` resolves the database through `GET /v1/databases/notes`. It takes its key from, in order, its `apiKey` option, then `TONBO_API_KEY`, then the `tonbo login` credentials file (`key_sources` in `contracts/cli/credentials-v1.json`). A key narrowed to databases reads the databases it reaches there, so an application can be given a narrowed key.
+
 ## Usage
 
 `usage show` prints the account's rated usage of one calendar month in UTC, the current one unless `--period YYYY-MM` names another: one line per product, region, dimension and model with its quantity and amount, and the total, in US dollars.

package/dist/bin/tonbo.js

@@ -8,7 +8,7 @@ import { readFileSync } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { execFile } from "node:child_process";
-import os from "node:os";
+import os2 from "node:os";
 import { promisify } from "node:util";
 
 // ../../packages/tonbo-cli-core/dist/src/callback-page.js
@@ -177,178 +177,11 @@ async function requestJson(fetcher, url, init = {}) {
   throw new HttpError(requestId ? `${message} (request ${requestId})` : message, response.status, body, requestId);
 }
 
-// ../../packages/tonbo-cli-core/dist/src/auth.js
-var exec = promisify(execFile);
-var DEFAULT_LOGIN_HINT = "tonbo login";
-var LOOPBACK_HOST = "127.0.0.1";
-function loginHostname(hostname = os.hostname()) {
-  const cleaned = hostname.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 64);
-  return cleaned || "computer";
-}
-var AuthClient = class {
-  credentials;
-  fetcher;
-  loginOrigin;
-  browserOpener;
-  hostname;
-  loginHint;
-  constructor(credentials, fetcher, loginOrigin2 = "https://tonbo.dev", browserOpener = openBrowser, hostname = loginHostname(), loginHint = DEFAULT_LOGIN_HINT) {
-    this.credentials = credentials;
-    this.fetcher = fetcher;
-    this.loginOrigin = loginOrigin2;
-    this.browserOpener = browserOpener;
-    this.hostname = hostname;
-    this.loginHint = loginHint;
-  }
-  /** The personal key requests are made with: TONBO_API_KEY, or the saved
-   * login while it has not expired. */
-  async apiKey() {
-    const injected = process.env.TONBO_API_KEY?.trim();
-    if (injected)
-      return injected;
-    const login = await this.credentials.load();
-    if (!login)
-      throw new Error(`Not logged in. Run \`${this.loginHint}\`.`);
-    if (login.expires_at && Date.parse(login.expires_at) <= Date.now())
-      throw new Error(`Your Tonbo login has expired. Run \`${this.loginHint}\`.`);
-    return login.key;
-  }
-  /**
-   * The browser handoff of /cli/login: PKCE S256 with a loopback redirect on
-   * a free port, then the one-time code is redeemed for a personal key named
-   * "CLI on <hostname>", which replaces that host's earlier login key.
-   */
-  async login(progress = () => {
-  }, account) {
-    const verifier = randomBytes(48).toString("base64url");
-    const challenge = createHash("sha256").update(verifier).digest("base64url");
-    const state = randomBytes(24).toString("base64url");
-    const code = await this.listenForCode(state, (redirectUri) => {
-      const authorization = new URL("/cli/login", this.loginOrigin);
-      authorization.search = new URLSearchParams({
-        code_challenge: challenge,
-        code_challenge_method: "S256",
-        redirect_uri: redirectUri,
-        state,
-        hostname: this.hostname,
-        ...account ? { account } : {}
-      }).toString();
-      return this.browserOpener(authorization.toString());
-    }, progress);
-    progress({ status: "started", step: "key-redemption" });
-    const redeemed = await requestJson(this.fetcher, new URL("/api/cli/login/token", this.loginOrigin).toString(), {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ code, code_verifier: verifier })
-    });
-    progress({ status: "completed", step: "key-redemption" });
-    const login = {
-      version: 1,
-      account_id: redeemed.account_id,
-      key_id: redeemed.api_key.id,
-      key: redeemed.key,
-      expires_at: redeemed.api_key.expires_at
-    };
-    progress({ status: "started", step: "credential-store" });
-    await this.credentials.save(login);
-    progress({ status: "completed", step: "credential-store" });
-    return login;
-  }
-  listenForCode(expectedState, ready, progress) {
-    return new Promise((resolve, reject) => {
-      let settled = false;
-      const sockets = /* @__PURE__ */ new Set();
-      let authorizationStarted = false;
-      const startAuthorization = () => {
-        if (authorizationStarted)
-          return;
-        authorizationStarted = true;
-        progress({ status: "completed", step: "browser" });
-        progress({ status: "started", step: "browser-authorization" });
-      };
-      const finish = (result, completedResponseSocket) => {
-        if (settled)
-          return;
-        settled = true;
-        clearTimeout(timeout);
-        const complete = (closeError) => {
-          if (closeError)
-            reject(closeError);
-          else if ("code" in result) {
-            progress({ status: "completed", step: "callback-close" });
-            resolve(result.code);
-          } else
-            reject(result.error);
-        };
-        if ("code" in result)
-          progress({ status: "started", step: "callback-close" });
-        if (!server.listening) {
-          complete();
-          return;
-        }
-        server.close(complete);
-        for (const socket of sockets) {
-          if (socket !== completedResponseSocket)
-            socket.destroy();
-        }
-        server.closeIdleConnections();
-      };
-      const timeout = setTimeout(() => {
-        finish({ error: new Error("Timed out waiting for browser login.") });
-      }, 5 * 60 * 1e3);
-      const server = createServer((request, response) => {
-        const url = new URL(request.url ?? "/", `http://${LOOPBACK_HOST}`);
-        if (url.pathname !== "/callback" || url.searchParams.get("state") !== expectedState) {
-          respond(response, "invalid");
-          return;
-        }
-        const denied = url.searchParams.get("error");
-        if (denied) {
-          const responseSocket2 = response.socket;
-          respond(response, "denied", () => finish({ error: new Error(`The login was not approved (${denied}).`) }, responseSocket2));
-          return;
-        }
-        const code = url.searchParams.get("code");
-        if (!code) {
-          respond(response, "invalid");
-          return;
-        }
-        startAuthorization();
-        progress({ status: "completed", step: "browser-authorization" });
-        const responseSocket = response.socket;
-        respond(response, "complete", () => finish({ code }, responseSocket));
-      });
-      server.on("connection", (socket) => {
-        sockets.add(socket);
-        socket.once("close", () => sockets.delete(socket));
-      });
-      server.once("error", (error) => finish({ error }));
-      progress({ status: "started", step: "callback-server" });
-      server.listen(0, LOOPBACK_HOST, () => {
-        const { port } = server.address();
-        progress({ status: "completed", step: "callback-server" });
-        progress({ status: "started", step: "browser" });
-        void ready(`http://${LOOPBACK_HOST}:${port}/callback`).then(startAuthorization).catch((error) => finish({
-          error: error instanceof Error ? error : new Error("Could not open the login browser.")
-        }));
-      });
-    });
-  }
-};
-function respond(response, outcome, finished) {
-  const page = callbackResponse(outcome);
-  if (finished)
-    response.once("finish", finished);
-  response.writeHead(page.status, { ...page.headers, connection: "close" });
-  response.end(page.body);
-}
-async function openBrowser(url) {
-  if (process.platform === "darwin")
-    return void await exec("open", [url]);
-  if (process.platform === "win32")
-    return void await exec("rundll32", ["url.dll,FileProtocolHandler", url]);
-  return void await exec("xdg-open", [url]);
-}
+// ../../packages/tonbo-cli-core/dist/src/credentials.js
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 
 // ../../packages/tonbo-cli-core/dist/src/generated/contracts.js
 var agentNameContract = {
@@ -718,18 +551,455 @@ var managementOperations = {
     "cli": "tonbo database usage"
   }
 };
-var accountRoles = [
-  "owner",
-  "admin",
-  "member"
-];
-var apiKeyExpirations = [
-  "15_days",
-  "1_month",
-  "6_months",
-  "1_year",
-  "never"
-];
+var accountRoles = [
+  "owner",
+  "admin",
+  "member"
+];
+var apiKeyExpirations = [
+  "15_days",
+  "1_month",
+  "6_months",
+  "1_year",
+  "never"
+];
+var credentialsContract = {
+  "version": 1,
+  "description": "The login `tonbo login` (and `yield login`) saves: a personal key of one account. @tonbo/cli-core writes and reads it; other readers, such as @tonbo/sqlite-ursula/tonbo, follow `reader`.",
+  "path": {
+    "description": "`${XDG_CONFIG_HOME}/tonbo/credentials.json` when XDG_CONFIG_HOME is set and not empty, else `${HOME}/.config/tonbo/credentials.json`.",
+    "base_env": "XDG_CONFIG_HOME",
+    "fallback_base": [
+      "$HOME",
+      ".config"
+    ],
+    "relative": [
+      "tonbo",
+      "credentials.json"
+    ]
+  },
+  "permissions": {
+    "description": "POSIX only; a reader on Windows skips the mode checks.",
+    "directory_mode": "0700",
+    "file_mode": "0600",
+    "writer": "The writer creates the directory 0700, writes a temporary file 0600 beside the target, syncs it and renames it over the target, so a crash never leaves a partial key. It refuses to replace or remove a symlink or anything that is not a regular file."
+  },
+  "key_sources": {
+    "description": "Where a client takes its key, first match wins. A library takes an explicit option first; the CLIs have none.",
+    "order": [
+      "option",
+      "env",
+      "file"
+    ],
+    "env": "TONBO_API_KEY"
+  },
+  "reader": {
+    "missing": "No file is not logged in: ask the person to run `tonbo login`.",
+    "refuse_symlink": true,
+    "refuse_non_regular_file": true,
+    "refuse_mode_bits": "0077",
+    "refused": "A symlink, a non-regular file, or a file any group or other permission bit is set on is an error and is never read; do not fall back to another source.",
+    "unknown_version": "A `version` other than `current_version`, or content that does not match `schema`, is unusable: ask the person to run `tonbo login`. It is never migrated.",
+    "expired": "A login whose `expires_at` is at or before now is expired: ask the person to run `tonbo login`. `expires_at: null` never expires.",
+    "login_hint": "tonbo login"
+  },
+  "current_version": 1,
+  "schema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://tonbo.dev/contracts/cli/credentials-v1.json",
+    "title": "Tonbo CLI login",
+    "type": "object",
+    "required": [
+      "version",
+      "account_id",
+      "key_id",
+      "key",
+      "expires_at"
+    ],
+    "additionalProperties": true,
+    "properties": {
+      "version": {
+        "const": 1
+      },
+      "account_id": {
+        "type": "string",
+        "minLength": 1,
+        "description": "The account the key belongs to (a UUID)."
+      },
+      "key_id": {
+        "type": "string",
+        "minLength": 1,
+        "description": "The key's id, its `client_id` at the exchange (a UUID)."
+      },
+      "key": {
+        "type": "string",
+        "pattern": "^tbo_",
+        "description": "The personal key's secret (contracts/iam/access-token-v1.json `personal_key`)."
+      },
+      "expires_at": {
+        "type": [
+          "string",
+          "null"
+        ],
+        "format": "date-time",
+        "description": "When the key expires, ISO 8601; null for a key that never expires."
+      }
+    }
+  },
+  "examples": {
+    "usable": [
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": "2027-04-24T00:00:00.000Z"
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null
+      }
+    ],
+    "unusable": [
+      {
+        "access_token": "access",
+        "refresh_token": "refresh",
+        "token_type": "bearer"
+      },
+      {
+        "version": 2,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "not-a-personal-key",
+        "expires_at": null
+      },
+      {
+        "version": 1,
+        "account_id": "",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": "not a date"
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret"
+      }
+    ]
+  }
+};
+
+// ../../packages/tonbo-cli-core/dist/src/credentials.js
+var DIRECTORY_MODE = Number.parseInt(credentialsContract.permissions.directory_mode, 8);
+var FILE_MODE = Number.parseInt(credentialsContract.permissions.file_mode, 8);
+var REFUSED_MODE_BITS = Number.parseInt(credentialsContract.reader.refuse_mode_bits, 8);
+function defaultCredentialsPath(env = process.env) {
+  const rule = credentialsContract.path;
+  const base = env[rule.base_env] || path.join(...rule.fallback_base.map((part) => part === "$HOME" ? os.homedir() : part));
+  return path.join(base, ...rule.relative);
+}
+function isExpiredLogin(login, now = Date.now()) {
+  return login.expires_at !== null && Date.parse(login.expires_at) <= now;
+}
+var UnusableLoginError = class extends Error {
+};
+var FileCredentialStore = class {
+  filename;
+  loginHint;
+  constructor(filename = defaultCredentialsPath(), loginHint = credentialsContract.reader.login_hint) {
+    this.filename = filename;
+    this.loginHint = loginHint;
+  }
+  async load() {
+    let parsed;
+    try {
+      await assertPrivateRegularFile(this.filename);
+      parsed = JSON.parse(await readFile(this.filename, "utf8"));
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return null;
+      throw new Error(`Could not read Tonbo credentials at ${this.filename}.`, { cause: error });
+    }
+    if (!isStoredLogin(parsed))
+      throw new UnusableLoginError(`The saved login at ${this.filename} is not usable by this CLI. Run \`${this.loginHint}\`.`);
+    return parsed;
+  }
+  async save(login) {
+    if (!isStoredLogin(login))
+      throw new Error("Refusing to store a malformed Tonbo login.");
+    const directory = path.dirname(this.filename);
+    await mkdir(directory, { mode: DIRECTORY_MODE, recursive: true });
+    await preparePrivateDirectory(directory);
+    await assertExistingDestinationIsSafe(this.filename);
+    const temporary = path.join(directory, `.${path.basename(this.filename)}.${process.pid}.${randomUUID()}.tmp`);
+    let handle = null;
+    try {
+      handle = await open(temporary, "wx", FILE_MODE);
+      await handle.writeFile(`${JSON.stringify(login, null, 2)}
+`, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      if (process.platform !== "win32")
+        await chmod(temporary, FILE_MODE);
+      await rename(temporary, this.filename);
+    } catch (error) {
+      await handle?.close().catch(() => void 0);
+      await rm(temporary, { force: true }).catch(() => void 0);
+      throw new Error(`Could not store Tonbo credentials at ${this.filename}.`, { cause: error });
+    }
+  }
+  async remove() {
+    await assertExistingDestinationIsSafe(this.filename);
+    await rm(this.filename, { force: true });
+  }
+};
+var RULE_KEYWORDS = /* @__PURE__ */ new Set(["const", "type", "minLength", "pattern", "format", "description"]);
+function matchesRule(value, rule) {
+  if (Object.keys(rule).some((keyword) => !RULE_KEYWORDS.has(keyword)))
+    return false;
+  if ("const" in rule)
+    return value === rule.const;
+  const types = typeof rule.type === "string" ? [rule.type] : rule.type ?? [];
+  if (value === null)
+    return types.includes("null");
+  if (typeof value !== "string" || !types.includes("string"))
+    return false;
+  if (rule.minLength !== void 0 && value.length < rule.minLength)
+    return false;
+  if (rule.pattern !== void 0 && !new RegExp(rule.pattern, "u").test(value))
+    return false;
+  if (rule.format === "date-time" && Number.isNaN(Date.parse(value)))
+    return false;
+  return true;
+}
+function isStoredLogin(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const login = value;
+  const schema = credentialsContract.schema;
+  if (login.version !== credentialsContract.current_version)
+    return false;
+  if (!schema.required.every((name) => Object.hasOwn(login, name)))
+    return false;
+  const properties = schema.properties;
+  return Object.entries(properties).every(([name, rule]) => !Object.hasOwn(login, name) || matchesRule(login[name], rule));
+}
+async function preparePrivateDirectory(directory) {
+  const stat = await lstat(directory);
+  if (stat.isSymbolicLink() || !stat.isDirectory())
+    throw new Error("Tonbo config directory must be a real directory.");
+  if (process.platform !== "win32")
+    await chmod(directory, DIRECTORY_MODE);
+}
+async function assertExistingDestinationIsSafe(filename) {
+  try {
+    const stat = await lstat(filename);
+    if (stat.isSymbolicLink() || !stat.isFile())
+      throw new Error("Tonbo credential path must be a regular file.");
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+}
+async function assertPrivateRegularFile(filename) {
+  const stat = await lstat(filename);
+  if (stat.isSymbolicLink() || !stat.isFile())
+    throw new Error("Tonbo credential path must be a regular file.");
+  if (process.platform !== "win32" && (stat.mode & REFUSED_MODE_BITS) !== 0)
+    throw new Error(`Tonbo credential file must have mode ${credentialsContract.permissions.file_mode}.`);
+}
+
+// ../../packages/tonbo-cli-core/dist/src/auth.js
+var exec = promisify(execFile);
+var DEFAULT_LOGIN_HINT = credentialsContract.reader.login_hint;
+var LOOPBACK_HOST = "127.0.0.1";
+function loginHostname(hostname = os2.hostname()) {
+  const cleaned = hostname.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 64);
+  return cleaned || "computer";
+}
+var AuthClient = class {
+  credentials;
+  fetcher;
+  loginOrigin;
+  browserOpener;
+  hostname;
+  loginHint;
+  constructor(credentials, fetcher, loginOrigin2 = "https://tonbo.dev", browserOpener = openBrowser, hostname = loginHostname(), loginHint = DEFAULT_LOGIN_HINT) {
+    this.credentials = credentials;
+    this.fetcher = fetcher;
+    this.loginOrigin = loginOrigin2;
+    this.browserOpener = browserOpener;
+    this.hostname = hostname;
+    this.loginHint = loginHint;
+  }
+  /** The personal key requests are made with: TONBO_API_KEY, or the saved
+   * login while it has not expired. */
+  async apiKey() {
+    const injected = process.env.TONBO_API_KEY?.trim();
+    if (injected)
+      return injected;
+    const login = await this.credentials.load();
+    if (!login)
+      throw new Error(`Not logged in. Run \`${this.loginHint}\`.`);
+    if (isExpiredLogin(login))
+      throw new Error(`Your Tonbo login has expired. Run \`${this.loginHint}\`.`);
+    return login.key;
+  }
+  /**
+   * The browser handoff of /cli/login: PKCE S256 with a loopback redirect on
+   * a free port, then the one-time code is redeemed for a personal key named
+   * "CLI on <hostname>", which replaces that host's earlier login key.
+   */
+  async login(progress = () => {
+  }, account) {
+    const verifier = randomBytes(48).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    const state = randomBytes(24).toString("base64url");
+    const code = await this.listenForCode(state, (redirectUri) => {
+      const authorization = new URL("/cli/login", this.loginOrigin);
+      authorization.search = new URLSearchParams({
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        redirect_uri: redirectUri,
+        state,
+        hostname: this.hostname,
+        ...account ? { account } : {}
+      }).toString();
+      return this.browserOpener(authorization.toString());
+    }, progress);
+    progress({ status: "started", step: "key-redemption" });
+    const redeemed = await requestJson(this.fetcher, new URL("/api/cli/login/token", this.loginOrigin).toString(), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ code, code_verifier: verifier })
+    });
+    progress({ status: "completed", step: "key-redemption" });
+    const login = {
+      version: 1,
+      account_id: redeemed.account_id,
+      key_id: redeemed.api_key.id,
+      key: redeemed.key,
+      expires_at: redeemed.api_key.expires_at
+    };
+    progress({ status: "started", step: "credential-store" });
+    await this.credentials.save(login);
+    progress({ status: "completed", step: "credential-store" });
+    return login;
+  }
+  listenForCode(expectedState, ready, progress) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const sockets = /* @__PURE__ */ new Set();
+      let authorizationStarted = false;
+      const startAuthorization = () => {
+        if (authorizationStarted)
+          return;
+        authorizationStarted = true;
+        progress({ status: "completed", step: "browser" });
+        progress({ status: "started", step: "browser-authorization" });
+      };
+      const finish = (result, completedResponseSocket) => {
+        if (settled)
+          return;
+        settled = true;
+        clearTimeout(timeout);
+        const complete = (closeError) => {
+          if (closeError)
+            reject(closeError);
+          else if ("code" in result) {
+            progress({ status: "completed", step: "callback-close" });
+            resolve(result.code);
+          } else
+            reject(result.error);
+        };
+        if ("code" in result)
+          progress({ status: "started", step: "callback-close" });
+        if (!server.listening) {
+          complete();
+          return;
+        }
+        server.close(complete);
+        for (const socket of sockets) {
+          if (socket !== completedResponseSocket)
+            socket.destroy();
+        }
+        server.closeIdleConnections();
+      };
+      const timeout = setTimeout(() => {
+        finish({ error: new Error("Timed out waiting for browser login.") });
+      }, 5 * 60 * 1e3);
+      const server = createServer((request, response) => {
+        const url = new URL(request.url ?? "/", `http://${LOOPBACK_HOST}`);
+        if (url.pathname !== "/callback" || url.searchParams.get("state") !== expectedState) {
+          respond(response, "invalid");
+          return;
+        }
+        const denied = url.searchParams.get("error");
+        if (denied) {
+          const responseSocket2 = response.socket;
+          respond(response, "denied", () => finish({ error: new Error(`The login was not approved (${denied}).`) }, responseSocket2));
+          return;
+        }
+        const code = url.searchParams.get("code");
+        if (!code) {
+          respond(response, "invalid");
+          return;
+        }
+        startAuthorization();
+        progress({ status: "completed", step: "browser-authorization" });
+        const responseSocket = response.socket;
+        respond(response, "complete", () => finish({ code }, responseSocket));
+      });
+      server.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+      });
+      server.once("error", (error) => finish({ error }));
+      progress({ status: "started", step: "callback-server" });
+      server.listen(0, LOOPBACK_HOST, () => {
+        const { port } = server.address();
+        progress({ status: "completed", step: "callback-server" });
+        progress({ status: "started", step: "browser" });
+        void ready(`http://${LOOPBACK_HOST}:${port}/callback`).then(startAuthorization).catch((error) => finish({
+          error: error instanceof Error ? error : new Error("Could not open the login browser.")
+        }));
+      });
+    });
+  }
+};
+function respond(response, outcome, finished) {
+  const page = callbackResponse(outcome);
+  if (finished)
+    response.once("finish", finished);
+  response.writeHead(page.status, { ...page.headers, connection: "close" });
+  response.end(page.body);
+}
+async function openBrowser(url) {
+  if (process.platform === "darwin")
+    return void await exec("open", [url]);
+  if (process.platform === "win32")
+    return void await exec("rundll32", ["url.dll,FileProtocolHandler", url]);
+  return void await exec("xdg-open", [url]);
+}
 
 // ../../packages/tonbo-cli-core/dist/src/api.js
 var DEFAULT_API_ORIGIN = "https://api.tonbo.dev";
@@ -883,99 +1153,6 @@ function unconfirmed(what, idempotencyKey, same) {
   };
 }
 
-// ../../packages/tonbo-cli-core/dist/src/credentials.js
-import { randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
-import os2 from "node:os";
-import path from "node:path";
-function defaultConfigDirectory() {
-  const base = process.env.XDG_CONFIG_HOME || path.join(os2.homedir(), ".config");
-  return path.join(base, "tonbo");
-}
-var UnusableLoginError = class extends Error {
-};
-var FileCredentialStore = class {
-  filename;
-  loginHint;
-  constructor(filename = path.join(defaultConfigDirectory(), "credentials.json"), loginHint = DEFAULT_LOGIN_HINT) {
-    this.filename = filename;
-    this.loginHint = loginHint;
-  }
-  async load() {
-    let parsed;
-    try {
-      await assertPrivateRegularFile(this.filename);
-      parsed = JSON.parse(await readFile(this.filename, "utf8"));
-    } catch (error) {
-      if (error.code === "ENOENT")
-        return null;
-      throw new Error(`Could not read Tonbo credentials at ${this.filename}.`, { cause: error });
-    }
-    if (!isStoredLogin(parsed))
-      throw new UnusableLoginError(`The saved login at ${this.filename} is not usable by this CLI. Run \`${this.loginHint}\`.`);
-    return parsed;
-  }
-  async save(login) {
-    if (!isStoredLogin(login))
-      throw new Error("Refusing to store a malformed Tonbo login.");
-    const directory = path.dirname(this.filename);
-    await mkdir(directory, { mode: 448, recursive: true });
-    await preparePrivateDirectory(directory);
-    await assertExistingDestinationIsSafe(this.filename);
-    const temporary = path.join(directory, `.${path.basename(this.filename)}.${process.pid}.${randomUUID()}.tmp`);
-    let handle = null;
-    try {
-      handle = await open(temporary, "wx", 384);
-      await handle.writeFile(`${JSON.stringify(login, null, 2)}
-`, "utf8");
-      await handle.sync();
-      await handle.close();
-      handle = null;
-      if (process.platform !== "win32")
-        await chmod(temporary, 384);
-      await rename(temporary, this.filename);
-    } catch (error) {
-      await handle?.close().catch(() => void 0);
-      await rm(temporary, { force: true }).catch(() => void 0);
-      throw new Error(`Could not store Tonbo credentials at ${this.filename}.`, { cause: error });
-    }
-  }
-  async remove() {
-    await assertExistingDestinationIsSafe(this.filename);
-    await rm(this.filename, { force: true });
-  }
-};
-function isStoredLogin(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value))
-    return false;
-  const login = value;
-  return login.version === 1 && typeof login.account_id === "string" && login.account_id.length > 0 && typeof login.key_id === "string" && login.key_id.length > 0 && typeof login.key === "string" && login.key.startsWith("tbo_") && (login.expires_at === null || typeof login.expires_at === "string" && !Number.isNaN(Date.parse(login.expires_at)));
-}
-async function preparePrivateDirectory(directory) {
-  const stat = await lstat(directory);
-  if (stat.isSymbolicLink() || !stat.isDirectory())
-    throw new Error("Tonbo config directory must be a real directory.");
-  if (process.platform !== "win32")
-    await chmod(directory, 448);
-}
-async function assertExistingDestinationIsSafe(filename) {
-  try {
-    const stat = await lstat(filename);
-    if (stat.isSymbolicLink() || !stat.isFile())
-      throw new Error("Tonbo credential path must be a regular file.");
-  } catch (error) {
-    if (error.code !== "ENOENT")
-      throw error;
-  }
-}
-async function assertPrivateRegularFile(filename) {
-  const stat = await lstat(filename);
-  if (stat.isSymbolicLink() || !stat.isFile())
-    throw new Error("Tonbo credential path must be a regular file.");
-  if (process.platform !== "win32" && (stat.mode & 63) !== 0)
-    throw new Error("Tonbo credential file must have mode 0600.");
-}
-
 // ../../packages/tonbo-cli-core/dist/src/format.js
 function table(headings, rows) {
   const widths = headings.map((heading, column) => Math.max(heading.length, ...rows.map((row) => (row[column] ?? "").length)));
@@ -1402,12 +1579,20 @@ async function apiKeyCreateCommand(deps, name, options = {}) {
       "",
       `  ${created.key}`,
       "",
+      "For your application's environment (.env or secret store):",
+      "",
+      `  TONBO_API_KEY=${created.key}`,
+      "",
       apiKeyFields(created)
     ].join("\n")
   );
   deps.notice(
     "This is the only time the key's secret is shown: store it now. Anyone holding it acts as its member."
   );
+  if (!options.json)
+    deps.notice(
+      "Do not set TONBO_API_KEY in your own shell: it overrides your `tonbo login`, for this CLI too."
+    );
 }
 async function apiKeyShowCommand(deps, keyId, options = {}) {
   const apiKey = await deps.api.getApiKey(await deps.auth.apiKey(), keyId);
@@ -1582,6 +1767,13 @@ async function databaseCreateCommand(deps, name, options = {}) {
       databaseFields(database)
     ].join("\n")
   );
+  if (!options.json) deps.notice(databaseNextStep(database.name));
+}
+function databaseNextStep(name) {
+  return [
+    "Next: npm i @tonbo/sqlite-ursula",
+    `      open(${JSON.stringify(name)}) from "@tonbo/sqlite-ursula/tonbo"`
+  ].join("\n");
 }
 async function databaseShowCommand(deps, name, options = {}) {
   const database = await deps.api.getDatabase(await deps.auth.apiKey(), name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "The Tonbo CLI: sign in and manage account resources from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {