nimblybase 0.1.4 → 0.1.6

package/README.md

@@ -30,13 +30,29 @@ keychain on macOS, and otherwise in
 `~/.config/nimblybase/credentials.json` with permissions `0600`. `nimbly
 login` always says which one it used.
 
-For a machine without a browser, create an access token in the dashboard
+For a machine without a local browser, run `nimbly login --device`. Open the
+displayed verification page on another device and enter the short code. The
+dashboard shows the requesting client and approved workspace/scopes. The CLI
+waits at the server's polling interval, backs off on slow-down, and stops on
+denial or expiry. A failed attempt keeps your previous login. Device sign-in
+still requires a person; it is not unattended CI authentication.
+
+For an explicit pasted-token fallback, create an access token in the dashboard
 under **Access tokens** and run `nimbly login --token <token>`. Omitting the
 value prompts without echoing it.
 
 In CI, set `NIMBLYBASE_TOKEN` instead. It takes precedence over anything
 stored and is never written to disk.
 
+Stored browser grants and newly saved access tokens stay bound to the API used
+at login. A repository link, `--api`, or environment setting cannot retarget that
+credential. To switch servers, explicitly run `nimbly login --api <destination>`;
+the previous login is kept if verification fails. Older bare tokens remain usable
+on the original UAT default until you log in again to bind another destination.
+An injected CI token requires an explicit `NIMBLYBASE_API_URL`/`--api` when a
+repository selects a different API. It never refreshes a separate personal login.
+Use HTTPS; local development may use literal `http://127.0.0.1:<port>` or `[::1]`.
+
 ## Requirements before creating
 
 For a new empty application, choose `--recipe static-d1` explicitly when a static

package/dist/index.js

@@ -68,6 +68,7 @@ function parse(argv) {
         spa: { type: "boolean" },
         build: { type: "boolean" },
         "token-only": { type: "boolean" },
+        device: { type: "boolean" },
         off: { type: "boolean" },
         using: { type: "string" },
         check: { type: "string" },
@@ -140,6 +141,7 @@ function parse(argv) {
       spa: v.spa === true ? true : void 0,
       build: v.build === true ? true : void 0,
       tokenOnly: v["token-only"] === true ? true : void 0,
+      device: v.device === true ? true : void 0,
       off: v.off === true ? true : void 0,
       using: v.using,
       check: v.check,
@@ -182,7 +184,8 @@ USAGE
   nimbly <command> [options]
 
 GETTING STARTED
-  login                    Sign in with an access token from the dashboard
+  login                    Sign in through your browser; --device for another machine
+                           --token-only is the explicit pasted-PAT fallback
   init [name]              Create or explicitly choose a project for this repo
   describe                 Show what the linked project's backend can do
   architect [requirements] Inspect this repo and propose a reviewable architecture
@@ -370,19 +373,31 @@ function when(iso) {
 
 // src/api.ts
 var DEFAULT_API_URL = "https://api-uat.nimblybase.com";
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 function dashboardUrl(api) {
   const match = /^https:\/\/api(-[a-z0-9]+)?\.(.+)$/.exec(api);
   return match ? `https://app${match[1] ?? ""}.${match[2]}` : null;
 }
 function apiUrl(override) {
-  return (override ?? process.env.NIMBLYBASE_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, "");
+  const raw = override ?? process.env.NIMBLYBASE_API_URL ?? DEFAULT_API_URL;
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new CliError("Invalid API address.", EXIT.usage);
+  }
+  const loopback = ["127.0.0.1", "[::1]"].includes(parsed.hostname);
+  if (parsed.username || parsed.password || parsed.search || parsed.hash || !/^\/*$/.test(parsed.pathname) || parsed.protocol !== "https:" && !(parsed.protocol === "http:" && loopback)) {
+    throw new CliError("The API must be an HTTPS origin without credentials, path, query or fragment. HTTP is allowed only on a literal loopback address.", EXIT.usage);
+  }
+  return parsed.origin;
 }
 async function request(base, token, path, init2 = {}) {
   let res;
   try {
     res = await fetch(`${base}${path}`, {
       ...init2,
+      redirect: "error",
       headers: {
         authorization: `Bearer ${token}`,
         ...init2.body ? { "content-type": "application/json" } : {},
@@ -638,8 +653,9 @@ function pkcePair() {
   return { verifier, challenge: b64url(createHash("sha256").update(verifier).digest()) };
 }
 async function discover(issuer, fetchImpl = fetch) {
-  const url = new URL("/.well-known/oauth-authorization-server", issuer).toString();
-  const res = await fetchImpl(url);
+  const origin = apiUrl(issuer);
+  const url = new URL("/.well-known/oauth-authorization-server", origin).toString();
+  const res = await fetchImpl(url, { redirect: "error", signal: AbortSignal.timeout(3e4) });
   if (!res.ok) {
     throw new Error(`${issuer} does not advertise an authorization server (${res.status} from ${url})`);
   }
@@ -647,11 +663,23 @@ async function discover(issuer, fetchImpl = fetch) {
   if (!doc.authorization_endpoint || !doc.token_endpoint) {
     throw new Error("the authorization server metadata is missing an endpoint this flow needs");
   }
+  for (const endpoint of [doc.token_endpoint, doc.registration_endpoint, doc.device_authorization_endpoint].filter(Boolean)) {
+    const target = new URL(endpoint);
+    if (target.origin !== origin || target.username || target.password || target.hash) {
+      throw new Error("the authorization server advertises a credential endpoint outside its API origin");
+    }
+  }
+  const authorize = new URL(doc.authorization_endpoint);
+  if (authorize.username || authorize.password || authorize.hash || authorize.protocol !== "https:" && !(authorize.protocol === "http:" && ["127.0.0.1", "[::1]"].includes(authorize.hostname))) {
+    throw new Error("the authorization endpoint must use HTTPS, or literal loopback HTTP");
+  }
   return doc;
 }
 async function registerClient(registrationEndpoint, fetchImpl = fetch) {
   const res = await fetchImpl(registrationEndpoint, {
     method: "POST",
+    redirect: "error",
+    signal: AbortSignal.timeout(3e4),
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
       client_name: "NimblyBase CLI",
@@ -730,6 +758,8 @@ function openBrowser(url) {
 async function exchange(input, fetchImpl = fetch) {
   const res = await fetchImpl(input.tokenEndpoint, {
     method: "POST",
+    redirect: "error",
+    signal: AbortSignal.timeout(3e4),
     headers: { "content-type": "application/x-www-form-urlencoded" },
     body: new URLSearchParams({
       grant_type: "authorization_code",
@@ -741,19 +771,76 @@ async function exchange(input, fetchImpl = fetch) {
   });
   const body = await res.json();
   if (!res.ok) throw new Error(`the sign-in could not be completed (${body.error ?? res.status})`);
+  return grantResponse(body, input.clientId);
+}
+function grantResponse(body, clientId) {
+  if (typeof body.access_token !== "string" || !/^nb_oat_[A-Za-z0-9_-]+$/.test(body.access_token) || typeof body.refresh_token !== "string" || !/^nb_ort_[A-Za-z0-9_-]+$/.test(body.refresh_token) || typeof body.expires_in !== "number" || !Number.isInteger(body.expires_in) || body.expires_in < 1 || body.expires_in > 900 || body.token_type !== void 0 && body.token_type !== "Bearer" || body.scope !== void 0 && typeof body.scope !== "string") {
+    throw new Error("the authorization server returned an invalid credential response");
+  }
   return {
-    accessToken: String(body.access_token),
-    refreshToken: String(body.refresh_token),
-    // Ours, not theirs: a clock ahead of the server's shortens the
-    // window, which is the direction that fails safe.
-    expiresAt: Date.now() + Number(body.expires_in ?? 900) * 1e3,
-    clientId: input.clientId,
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    expiresAt: Date.now() + body.expires_in * 1e3,
+    clientId,
     scopes: String(body.scope ?? "").split(" ").filter(Boolean)
   };
 }
+async function deviceLogin(input, fetchImpl = fetch) {
+  const doc = await discover(input.issuer, fetchImpl);
+  if (!doc.device_authorization_endpoint || !doc.registration_endpoint) {
+    throw new Error("this server does not offer device sign-in and client registration");
+  }
+  const clientId = await registerClient(doc.registration_endpoint, fetchImpl);
+  const start = await fetchImpl(doc.device_authorization_endpoint, {
+    method: "POST",
+    redirect: "error",
+    signal: AbortSignal.timeout(3e4),
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ client_id: clientId }).toString()
+  });
+  if (!start.ok) throw new Error("device sign-in could not be started");
+  const device = await start.json();
+  if (typeof device.device_code !== "string" || !/^nb_oat_[A-Za-z0-9_-]+$/.test(device.device_code) || typeof device.user_code !== "string" || !/^[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(device.user_code) || typeof device.verification_uri !== "string" || typeof device.expires_in !== "number" || !Number.isInteger(device.expires_in) || device.expires_in < 1 || device.expires_in > 900 || device.interval !== void 0 && (!Number.isInteger(device.interval) || device.interval < 1 || device.interval > 60)) {
+    throw new Error("the server returned an invalid device authorization response");
+  }
+  const verification = new URL(device.verification_uri);
+  if (verification.origin !== new URL(doc.authorization_endpoint).origin || verification.username || verification.password || verification.search || verification.hash) {
+    throw new Error("the device verification page is outside the authorization origin");
+  }
+  const now = input.now ?? (() => performance.now());
+  const sleep = input.sleep ?? ((ms) => new Promise((resolve8) => setTimeout(resolve8, ms)));
+  const deadline = now() + device.expires_in * 1e3;
+  let interval = Math.max(5, device.interval ?? 5) * 1e3;
+  input.announce({ verificationUri: verification.toString(), userCode: device.user_code, expiresInSeconds: device.expires_in });
+  while (now() < deadline) {
+    await sleep(Math.min(interval, Math.max(0, deadline - now())));
+    const remaining = deadline - now();
+    if (remaining <= 0) break;
+    const poll = await fetchImpl(doc.token_endpoint, {
+      method: "POST",
+      redirect: "error",
+      signal: AbortSignal.timeout(Math.min(3e4, remaining)),
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:device_code", client_id: clientId, device_code: device.device_code }).toString()
+    });
+    const body = await poll.json();
+    if (poll.ok) return grantResponse(body, clientId);
+    if (body.error === "authorization_pending") continue;
+    if (body.error === "slow_down") {
+      interval += 5e3;
+      continue;
+    }
+    if (body.error === "access_denied") throw new Error("you declined device sign-in; your previous login was kept");
+    if (body.error === "expired_token") break;
+    throw new Error("device sign-in failed; your previous login was kept");
+  }
+  throw new Error("device sign-in expired; your previous login was kept");
+}
 async function refreshGrant(input, fetchImpl = fetch) {
   const res = await fetchImpl(input.tokenEndpoint, {
     method: "POST",
+    redirect: "error",
+    signal: AbortSignal.timeout(3e4),
     headers: { "content-type": "application/x-www-form-urlencoded" },
     body: new URLSearchParams({
       grant_type: "refresh_token",
@@ -763,13 +850,7 @@ async function refreshGrant(input, fetchImpl = fetch) {
   });
   const body = await res.json();
   if (!res.ok) throw new Error(String(body.error ?? res.status));
-  return {
-    accessToken: String(body.access_token),
-    refreshToken: String(body.refresh_token),
-    expiresAt: Date.now() + Number(body.expires_in ?? 900) * 1e3,
-    clientId: input.clientId,
-    scopes: String(body.scope ?? "").split(" ").filter(Boolean)
-  };
+  return grantResponse(body, input.clientId);
 }
 async function browserLogin(input) {
   const doc = await discover(input.issuer);
@@ -823,7 +904,8 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
-import { mkdir, readFile, writeFile, chmod, rm, stat } from "node:fs/promises";
+import { mkdir, readFile, writeFile, chmod, rm, stat, rename } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 var run = promisify(execFile);
 var SERVICE = "nimblybase-cli";
 var ACCOUNT = "access-token";
@@ -874,15 +956,16 @@ async function keychainDelete() {
     return false;
   }
 }
-function encodeSecret(value) {
-  return typeof value === "string" ? value : JSON.stringify(value);
+function encodeSecret(value, apiUrl2) {
+  return typeof value === "string" ? apiUrl2 ? JSON.stringify({ token: value, apiUrl: apiUrl2 }) : value : JSON.stringify(value);
 }
 function decodeSecret(raw) {
   const trimmed = raw.trim();
   if (!trimmed.startsWith("{")) return { token: trimmed };
   try {
     const parsed = JSON.parse(trimmed);
-    return parsed.refreshToken ? { grant: parsed } : {};
+    if (parsed.refreshToken) return { grant: parsed };
+    return typeof parsed.token === "string" && typeof parsed.apiUrl === "string" ? { token: parsed.token, apiUrl: parsed.apiUrl } : {};
   } catch {
     return {};
   }
@@ -894,18 +977,25 @@ async function fileRead() {
     return null;
   }
 }
-async function fileWrite(value) {
+async function fileWrite(value, apiUrl2) {
   const path = credentialsPath();
   await mkdir(dirname(path), { recursive: true, mode: 448 });
-  const body = typeof value === "string" ? { token: value } : { grant: value };
-  await writeFile(path, `${JSON.stringify(body, null, 2)}
-`, { mode: 384 });
-  await chmod(path, 384);
+  await chmod(dirname(path), 448);
+  const body = typeof value === "string" ? { token: value, ...apiUrl2 ? { apiUrl: apiUrl2 } : {} } : { grant: value };
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(body, null, 2)}
+`, { mode: 384, flag: "wx" });
+    await chmod(temporary, 384);
+    await rename(temporary, path);
+  } finally {
+    await rm(temporary, { force: true });
+  }
 }
 var credentials = {
-  async save(token) {
-    if (await keychainSet(token)) return "keychain";
-    await fileWrite(token);
+  async save(token, apiUrl2) {
+    if (await keychainSet(encodeSecret(token, apiUrl2))) return "keychain";
+    await fileWrite(token, apiUrl2);
     return "file";
   },
   async saveGrant(grant) {
@@ -918,19 +1008,21 @@ var credentials = {
     if (fromEnv) return { token: fromEnv, where: "environment" };
     const fromKeychain = await keychainGet();
     if (fromKeychain) {
-      const { token, grant } = decodeSecret(fromKeychain);
+      const { token, grant, apiUrl: apiUrl3 } = decodeSecret(fromKeychain);
       const value2 = token ?? grant?.accessToken;
-      if (value2) return { token: value2, where: "keychain" };
+      if (value2) return { token: value2, where: "keychain", ...apiUrl3 || grant?.issuer ? { apiUrl: apiUrl3 ?? grant.issuer } : {} };
     }
     const fromFile = await fileRead();
     const value = fromFile?.token ?? fromFile?.grant?.accessToken;
-    return value ? { token: value, where: "file" } : null;
+    const apiUrl2 = fromFile?.apiUrl ?? fromFile?.grant?.issuer;
+    return value ? { token: value, where: "file", ...apiUrl2 ? { apiUrl: apiUrl2 } : {} } : null;
   },
   async loadGrant() {
+    if (process.env.NIMBLYBASE_TOKEN?.trim()) return null;
     const fromKeychain = await keychainGet();
     if (fromKeychain) {
       const { grant } = decodeSecret(fromKeychain);
-      if (grant) return { grant, where: "keychain" };
+      return grant ? { grant, where: "keychain" } : null;
     }
     const fromFile = await fileRead();
     return fromFile?.grant ? { grant: fromFile.grant, where: "file" } : null;
@@ -1006,8 +1098,8 @@ async function confirm(question) {
 }
 
 // src/link.ts
-import { readFile as readFile2, rename, rm as rm2, writeFile as writeFile2, link as hardLink } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
+import { readFile as readFile2, rename as rename2, rm as rm2, writeFile as writeFile2, link as hardLink } from "node:fs/promises";
+import { randomUUID as randomUUID2 } from "node:crypto";
 import { dirname as dirname2, join as join2, parse as parse2, resolve } from "node:path";
 var LINK_FILE = "nimblybase.json";
 var BOOTSTRAP_FILE = ".nimblybase.bootstrap.json";
@@ -1089,11 +1181,11 @@ async function writeLink(dir, link2, options = {}) {
     slug: link2.slug
   };
   if (link2.apiUrl !== void 0) next.apiUrl = link2.apiUrl;
-  const temporary = join2(dirname2(path), `.${LINK_FILE}.${process.pid}.${randomUUID()}.tmp`);
+  const temporary = join2(dirname2(path), `.${LINK_FILE}.${process.pid}.${randomUUID2()}.tmp`);
   try {
     await writeFile2(temporary, `${JSON.stringify(next, null, 2)}
 `, { flag: "wx" });
-    await rename(temporary, path);
+    await rename2(temporary, path);
   } catch (err) {
     await rm2(temporary, { force: true });
     throw err;
@@ -1122,8 +1214,8 @@ async function readPendingBootstrap(dir) {
 }
 async function pendingBootstrap(dir, input) {
   const path = join2(dir, BOOTSTRAP_FILE);
-  const temporary = join2(dir, `.nimblybase.bootstrap.${process.pid}.${randomUUID()}.tmp`);
-  const pending = { schemaVersion: 2, requestId: randomUUID(), ...input };
+  const temporary = join2(dir, `.nimblybase.bootstrap.${process.pid}.${randomUUID2()}.tmp`);
+  const pending = { schemaVersion: 2, requestId: randomUUID2(), ...input };
   try {
     await writeFile2(temporary, `${JSON.stringify(pending, null, 2)}
 `, { flag: "wx", mode: 384 });
@@ -1147,8 +1239,24 @@ async function clearPendingBootstrap(dir) {
 // src/context.ts
 async function context(apiOverride) {
   const link2 = await findLink();
-  const base = apiUrl(apiOverride ?? process.env.NIMBLYBASE_API_URL ?? link2?.apiUrl);
+  const storedBeforeRefresh = await credentials.load();
+  const base = apiUrl(apiOverride ?? process.env.NIMBLYBASE_API_URL ?? link2?.apiUrl ?? (storedBeforeRefresh?.where !== "environment" ? storedBeforeRefresh?.apiUrl : void 0));
   const held = await credentials.loadGrant();
+  if (storedBeforeRefresh && storedBeforeRefresh.where !== "environment") {
+    const bound = apiUrl(storedBeforeRefresh.apiUrl ?? "https://api-uat.nimblybase.com");
+    if (base !== bound) throw new CliError(
+      "This credential belongs to a different API.",
+      EXIT.unauthenticated,
+      "Run `nimbly login --api <destination>` to authorize that API. Your stored login was kept."
+    );
+  }
+  if (storedBeforeRefresh?.where === "environment" && link2?.apiUrl && !apiOverride && !process.env.NIMBLYBASE_API_URL && base !== apiUrl(DEFAULT_API_URL)) {
+    throw new CliError(
+      "An environment token cannot be sent to an API selected only by a repository file.",
+      EXIT.usage,
+      "Set NIMBLYBASE_API_URL or pass --api explicitly for this automation identity."
+    );
+  }
   if (held && held.grant.expiresAt - Date.now() < 6e4) {
     try {
       const fresh = await refreshGrant({
@@ -1215,8 +1323,17 @@ var WHERE_SAID = {
 async function login(flags) {
   const base = apiUrl(flags.api);
   const given = flags.token ?? await readPipedInput();
+  if (flags.device && (given || flags.tokenOnly)) throw new CliError("Choose device sign-in or a pasted token, not both.", EXIT.usage);
   if (!given && !flags.tokenOnly) {
-    const grant = await browserLogin({
+    const grant = flags.device ? await deviceLogin({
+      issuer: base,
+      announce: ({ verificationUri, userCode, expiresInSeconds }) => {
+        note(`On another device, open:
+  ${verificationUri}
+Enter code: ${userCode}
+It expires in ${expiresInSeconds} seconds. Approve only the CLI request you started.`);
+      }
+    }) : await browserLogin({
       issuer: base,
       announce: (url) => {
         out("Opening your browser to sign in.");
@@ -1225,8 +1342,8 @@ async function login(flags) {
       },
       open: openBrowser
     });
-    const where2 = await credentials.saveGrant({ ...grant, issuer: base });
     const me2 = await createClient(base, grant.accessToken).me();
+    const where2 = await credentials.saveGrant({ ...grant, issuer: base });
     if (isJsonMode()) {
       json({ ok: true, storedIn: where2, organization: me2.organization, api: base, scopes: grant.scopes });
       return;
@@ -1246,7 +1363,7 @@ async function login(flags) {
     );
   }
   const me = await createClient(base, token).me();
-  const where = await credentials.save(token);
+  const where = await credentials.save(token, base);
   if (isJsonMode()) {
     json({ ok: true, storedIn: where, organization: me.organization, api: base });
     return;
@@ -7849,7 +7966,7 @@ async function mcp(flags, which) {
 }
 
 // src/commands/db.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
 import { dirname as dirname3, isAbsolute, join as join4, resolve as resolve5 } from "node:path";
 var DEFAULT_SCHEMA_FILE = "schema.json";
@@ -7886,7 +8003,7 @@ var lineageOf = (parsed) => {
   const raw = parsed?.lineage;
   return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : void 0;
 };
-var newLineage = () => `cli-${randomUUID2()}`;
+var newLineage = () => `cli-${randomUUID3()}`;
 async function ensureLineage(path, parsed) {
   const existing = lineageOf(parsed);
   if (existing) return existing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nimblybase",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "The NimblyBase command line - projects, keys and backends from a terminal.",
   "license": "UNLICENSED",
   "repository": {