stoaken 0.5.0 → 0.5.1

package/README.md

@@ -10,13 +10,13 @@ npx stoaken init
 
 Run it in the root of the project you want connected to a Stoaken Brand. It will:
 
-1. Ask how you'd like to sign in -- open your browser for a real OAuth 2.1 login, or let you paste an API key you've already created at `/settings/api-keys`.
+1. Ask how you'd like to sign in -- in your browser (OAuth 2.1), or by pasting an API key you've already created in Settings › API keys.
 2. List the real Brands your account can see, and let you pick one.
 3. Write `stoaken.config.json` (which Brand, which server -- safe to commit, holds no secret) and `.stoaken/credentials.json` (your bearer credential, `chmod 600`, automatically added to `.gitignore`).
 4. Ask which AI tool to connect (or take `--client`) and write that tool's MCP config.
 5. Generate `.stoaken/SKILL.md` -- a short brief for AI coding agents explaining how this project connects to Stoaken's MCP server and what its tools do.
 
-Run `stoaken init` again in an already-configured directory to continue with the same Brand, switch to a different one, or re-authenticate.
+Run `stoaken init` again in an already-configured directory to continue with the same Brand, switch to a different one, or sign in again.
 
 ## Connect an AI tool
 
@@ -59,8 +59,15 @@ left alone and you're told. No secret goes into these files, so they are safe to
 
 Two paths, both landing on the same bearer credential:
 
-- **Log in with browser** -- a real OAuth 2.1 Authorization Code + PKCE flow. The CLI discovers Stoaken's Authorization Server automatically (via its `/.well-known/oauth-protected-resource` metadata), registers itself as an OAuth client on first run, and opens your browser to sign in.
-- **Paste an API key** -- for CI, scripts, or anywhere a browser isn't available. Create one at `/settings/api-keys` in the Stoaken app.
+- **Sign in with browser** -- a real OAuth 2.1 Authorization Code + PKCE flow. The CLI discovers Stoaken's Authorization Server automatically (via its `/.well-known/oauth-protected-resource` metadata) and opens your browser. You sign in as you do on the web, then a consent screen asks whether **Stoaken CLI** may use your account: check the name, then allow it. The terminal then says `Signed in as you@example.com.`
+  - From 0.5.1 the CLI identifies itself with a Client ID Metadata Document (`https://www.stoaken.com/oauth/cli-client.json`), so nothing is registered; if the server doesn't support that, it registers itself once (Dynamic Client Registration) and reuses that registration. Its redirect is `http://127.0.0.1:51820/callback`.
+  - It asks for a token for `https://www.stoaken.com/mcp` with `offline_access`, and saves the refresh token (with the server it came from) in `.stoaken/credentials.json`, `chmod 600`. `stoaken export` renews an expired sign-in itself; when that's no longer possible it says "Your Stoaken sign-in ended." Run `stoaken init` to sign in again.
+  - Browser sign-in has to be switched on for Stoaken's sign-in service. Until it is, use an API key.
+- **Paste an API key** -- for CI, scripts, or anywhere a browser isn't available. Create one in Settings › API keys in the Stoaken app.
+
+## Changes
+
+- **0.5.1** -- Browser sign-in uses a Client ID Metadata Document (Dynamic Client Registration as the fallback), asks for the /mcp resource and a refresh token, and renews itself. "Sign in" wording throughout.
 
 ## Export your tokens as code
 

package/dist/index.js

@@ -14,7 +14,7 @@ import open from "open";
 
 // src/config.ts
 import { existsSync } from "fs";
-import { appendFile, mkdir, readFile, writeFile } from "fs/promises";
+import { appendFile, chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
 import { join } from "path";
 var CONFIG_FILE = "stoaken.config.json";
 var STOAKEN_DIR = ".stoaken";
@@ -40,9 +40,14 @@ async function ensureStoakenDir(cwd) {
 }
 async function writeCredentials(cwd, credentials) {
   await ensureStoakenDir(cwd);
-  const path = join(cwd, CREDENTIALS_FILE);
-  await writeFile(path, `${JSON.stringify(credentials, null, 2)}
-`, { encoding: "utf8", mode: 384 });
+  await writePrivate(join(cwd, CREDENTIALS_FILE), `${JSON.stringify(credentials, null, 2)}
+`);
+}
+async function writePrivate(path, text) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  await writeFile(tmp, text, { encoding: "utf8", mode: 384, flag: "wx" });
+  await chmod(tmp, 384);
+  await rename(tmp, path);
 }
 async function readCredentials(cwd) {
   try {
@@ -52,18 +57,23 @@ async function readCredentials(cwd) {
     return null;
   }
 }
-async function readOAuthClient(cwd) {
+async function readOAuthClient(cwd, authServer) {
   try {
     const raw = await readFile(join(cwd, OAUTH_CLIENT_FILE), "utf8");
-    return JSON.parse(raw);
+    const client = JSON.parse(raw);
+    return client.clientId && sameServer(client.authServer, authServer) ? client : null;
   } catch {
     return null;
   }
 }
 async function writeOAuthClient(cwd, client) {
   await ensureStoakenDir(cwd);
-  await writeFile(join(cwd, OAUTH_CLIENT_FILE), `${JSON.stringify(client, null, 2)}
-`, "utf8");
+  await writePrivate(join(cwd, OAUTH_CLIENT_FILE), `${JSON.stringify(client, null, 2)}
+`);
+}
+function sameServer(a, b) {
+  const norm = (u) => (u ?? "").trim().replace(/\/+$/, "").toLowerCase();
+  return Boolean(norm(a)) && norm(a) === norm(b);
 }
 async function writeSkillFile(cwd, content) {
   await ensureStoakenDir(cwd);
@@ -86,9 +96,18 @@ async function ensureGitignored(cwd) {
 `, "utf8");
 }
 
-// src/auth.ts
+// src/oauth-client.ts
 var CALLBACK_PORT = 51820;
 var REDIRECT_URI = `http://127.0.0.1:${CALLBACK_PORT}/callback`;
+var CLIENT_METADATA_PATH = "/oauth/cli-client.json";
+function cimdClientId(origin) {
+  return `${new URL(origin).origin}${CLIENT_METADATA_PATH}`;
+}
+var OAUTH_SCOPE = "openid offline_access";
+
+// src/auth.ts
+var SIGN_IN_ENDED = 'Your Stoaken sign-in ended. Run "stoaken init" to sign in again, or set STOAKEN_TOKEN to an API key.';
+var CALLBACK_TIMEOUT_MS = 5 * 60 * 1e3;
 async function discoverAuthorizationServer(serverUrl) {
   const metadataUrl = new URL("/.well-known/oauth-protected-resource", serverUrl);
   const response = await fetch(metadataUrl);
@@ -96,26 +115,44 @@ async function discoverAuthorizationServer(serverUrl) {
     throw new Error(`Failed to discover the authorization server (${response.status}) at ${metadataUrl}`);
   }
   const metadata = await response.json();
-  const authServer = metadata.authorization_servers?.[0];
-  if (!authServer) {
+  const issuer = metadata.authorization_servers?.[0]?.replace(/\/+$/, "");
+  if (!issuer) {
     throw new Error(`${metadataUrl} did not name an authorization server`);
   }
-  return authServer;
+  const as = await authServerMetadata(issuer);
+  return {
+    issuer,
+    resource: metadata.resource || new URL("/mcp", serverUrl).toString(),
+    authorize: as.authorization_endpoint ?? `${issuer}/oauth2/authorize`,
+    token: as.token_endpoint ?? `${issuer}/oauth2/token`,
+    register: as.registration_endpoint ?? `${issuer}/oauth2/register`,
+    cimd: as.client_id_metadata_document_supported
+  };
+}
+async function authServerMetadata(issuer) {
+  try {
+    const response = await fetch(`${issuer}/.well-known/oauth-authorization-server`);
+    return response.ok ? await response.json() : {};
+  } catch {
+    return {};
+  }
 }
-async function registerOAuthClient(authServer) {
-  const response = await fetch(`${authServer}/oauth2/register`, {
+var RegistrationRefused = class extends Error {
+};
+async function registerOAuthClient(server) {
+  const response = await fetch(server.register, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       client_name: "Stoaken CLI",
       redirect_uris: [REDIRECT_URI],
-      grant_types: ["authorization_code"],
+      grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
       token_endpoint_auth_method: "none"
     })
   });
   if (!response.ok) {
-    throw new Error(`Dynamic Client Registration failed (${response.status}): ${await response.text()}`);
+    throw new RegistrationRefused(`Dynamic Client Registration failed (${response.status}): ${await response.text()}`);
   }
   const data = await response.json();
   return data.client_id;
@@ -128,8 +165,15 @@ function generatePkce() {
   const challenge = base64url(createHash("sha256").update(verifier).digest());
   return { verifier, challenge };
 }
-function waitForCallback() {
+var ClientRefused = class extends Error {
+};
+var CLIENT_ERRORS = /* @__PURE__ */ new Set(["invalid_client", "unauthorized_client"]);
+function waitForCallback(state) {
   return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error('Sign-in timed out. Run "stoaken init" to try again.'));
+    }, CALLBACK_TIMEOUT_MS);
     const server = createServer((req, res) => {
       const url = new URL(req.url ?? "/", REDIRECT_URI);
       if (url.pathname !== "/callback") {
@@ -138,64 +182,148 @@ function waitForCallback() {
       }
       const code = url.searchParams.get("code");
       const error = url.searchParams.get("error");
+      if (url.searchParams.get("state") !== state) {
+        res.writeHead(400, { "Content-Type": "text/html" }).end("<p>That isn't the answer to this sign-in.</p>");
+        return;
+      }
       res.writeHead(200, { "Content-Type": "text/html" });
       res.end(
-        error ? "<p>Login failed. You can close this tab and return to the terminal.</p>" : "<p>Login complete -- you can close this tab and return to the terminal.</p>"
+        error || !code ? "<p>Sign-in failed. You can close this tab and return to the terminal.</p>" : "<p>Signed in. You can close this tab and return to the terminal.</p>"
       );
+      clearTimeout(timer);
       server.close();
       if (error) {
-        reject(new Error(`WorkOS returned an error: ${error}`));
+        const why = `WorkOS returned an error: ${error}`;
+        reject(CLIENT_ERRORS.has(error) ? new ClientRefused(why) : new Error(why));
       } else if (!code) {
         reject(new Error("No authorization code in the callback"));
       } else {
         resolve2(code);
       }
     });
-    server.on("error", reject);
+    server.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
     server.listen(CALLBACK_PORT, "127.0.0.1");
   });
 }
-async function exchangeCodeForToken(authServer, clientId, code, verifier) {
-  const response = await fetch(`${authServer}/oauth2/token`, {
+async function tokenRequest(server, params) {
+  const response = await fetch(server.token, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body: new URLSearchParams({
-      grant_type: "authorization_code",
-      code,
-      redirect_uri: REDIRECT_URI,
-      client_id: clientId,
-      code_verifier: verifier
-    })
+    body: new URLSearchParams({ ...params, resource: server.resource })
   });
   if (!response.ok) {
-    throw new Error(`Token exchange failed (${response.status}): ${await response.text()}`);
+    const text = await response.text();
+    const why = `Token exchange failed (${response.status}): ${text}`;
+    throw CLIENT_ERRORS.has(errorCode(text)) ? new ClientRefused(why) : new Error(why);
   }
-  const data = await response.json();
-  return data.access_token;
+  return await response.json();
 }
-async function loginWithBrowser(cwd, serverUrl) {
-  const authServer = await discoverAuthorizationServer(serverUrl);
-  let clientId = (await readOAuthClient(cwd))?.clientId;
-  if (!clientId) {
-    clientId = await registerOAuthClient(authServer);
-    await writeOAuthClient(cwd, { clientId });
+function errorCode(text) {
+  try {
+    return String(JSON.parse(text).error ?? "");
+  } catch {
+    return "";
   }
+}
+function credentialsFrom(data, server, clientId, serverUrl, now = Date.now()) {
+  return {
+    kind: "oauth",
+    token: data.access_token,
+    ...data.refresh_token ? { refreshToken: data.refresh_token } : {},
+    ...typeof data.expires_in === "number" ? { expiresAt: now + data.expires_in * 1e3 } : {},
+    authServer: server.issuer,
+    clientId,
+    serverUrl
+  };
+}
+function tokenEmail(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+    return typeof payload.email === "string" ? payload.email : null;
+  } catch {
+    return null;
+  }
+}
+async function authorizeWith(server, clientId) {
   const { verifier, challenge } = generatePkce();
-  const authorizeUrl = new URL("/oauth2/authorize", authServer);
+  const state = base64url(randomBytes(16));
+  const authorizeUrl = new URL(server.authorize);
   authorizeUrl.searchParams.set("client_id", clientId);
   authorizeUrl.searchParams.set("redirect_uri", REDIRECT_URI);
   authorizeUrl.searchParams.set("response_type", "code");
   authorizeUrl.searchParams.set("code_challenge", challenge);
   authorizeUrl.searchParams.set("code_challenge_method", "S256");
-  const callbackPromise = waitForCallback();
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("scope", OAUTH_SCOPE);
+  authorizeUrl.searchParams.set("resource", server.resource);
+  const callbackPromise = waitForCallback(state);
   await open(authorizeUrl.toString());
-  p.log.info(`Opened your browser to sign in. Waiting for you to finish...`);
-  const code = await callbackPromise;
-  return exchangeCodeForToken(authServer, clientId, code, verifier);
+  return { code: await callbackPromise, verifier };
+}
+async function dcrClient(cwd, server) {
+  const cached = await readOAuthClient(cwd, server.issuer);
+  if (cached) return cached.clientId;
+  let clientId;
+  try {
+    clientId = await registerOAuthClient(server);
+  } catch (error) {
+    if (error instanceof RegistrationRefused) {
+      throw new Error("Browser sign-in isn't switched on for this Stoaken server yet. Paste an API key instead (Settings \u203A API keys).");
+    }
+    throw error;
+  }
+  await writeOAuthClient(cwd, { clientId, authServer: server.issuer });
+  return clientId;
+}
+async function loginWithBrowser(cwd, serverUrl) {
+  const server = await discoverAuthorizationServer(serverUrl);
+  const signIn = async (clientId) => {
+    const { code, verifier } = await authorizeWith(server, clientId);
+    const data = await tokenRequest(server, { grant_type: "authorization_code", code, redirect_uri: REDIRECT_URI, client_id: clientId, code_verifier: verifier });
+    return credentialsFrom(data, server, clientId, serverUrl);
+  };
+  let credentials;
+  if (server.cimd) {
+    try {
+      credentials = await signIn(cimdClientId(new URL(server.resource).origin));
+    } catch (error) {
+      if (!(error instanceof ClientRefused)) throw error;
+      p.log.info("Stoaken's sign-in didn't accept the CLI's published client. Trying again with a registered one...");
+      credentials = await signIn(await dcrClient(cwd, server));
+    }
+  } else {
+    credentials = await signIn(await dcrClient(cwd, server));
+  }
+  return { credentials, email: tokenEmail(credentials.token) };
+}
+function needsRefresh(credentials, now = Date.now()) {
+  return credentials.kind === "oauth" && typeof credentials.expiresAt === "number" && now >= credentials.expiresAt - 6e4;
+}
+async function freshCredentials(cwd, serverUrl) {
+  const saved = await readCredentials(cwd);
+  if (!saved || saved.kind !== "oauth") return saved;
+  if (saved.serverUrl && !sameServer(saved.serverUrl, serverUrl)) {
+    throw new Error(`Your saved sign-in is for ${saved.serverUrl}, not ${serverUrl}. Run "stoaken init" to sign in again, or set STOAKEN_TOKEN to an API key.`);
+  }
+  if (!needsRefresh(saved)) return saved;
+  if (!saved.refreshToken || !saved.authServer || !saved.clientId) throw new Error(SIGN_IN_ENDED);
+  try {
+    const server = await discoverAuthorizationServer(saved.serverUrl ?? serverUrl);
+    if (!sameServer(server.issuer, saved.authServer)) throw new Error("authorization server changed");
+    const data = await tokenRequest(server, { grant_type: "refresh_token", refresh_token: saved.refreshToken, client_id: saved.clientId });
+    const next = credentialsFrom({ refresh_token: saved.refreshToken, ...data }, server, saved.clientId, saved.serverUrl ?? serverUrl);
+    await writeCredentials(cwd, next);
+    return next;
+  } catch {
+    throw new Error(SIGN_IN_ENDED);
+  }
 }
 async function promptForApiKey() {
   const key = await p.password({
-    message: "Paste your Stoaken API key (from /settings/api-keys):",
+    message: "Paste your Stoaken API key (Settings \u203A API keys):",
     validate: (value) => {
       if (!value?.startsWith("stk_") && !value?.startsWith("twk_")) {
         return "That doesn't look like a Stoaken API key (should start with stk_)";
@@ -214,7 +342,7 @@ async function listBrands(serverUrl, credential) {
   const transport = new StreamableHTTPClientTransport(new URL("/mcp", serverUrl), {
     requestInit: { headers: { Authorization: `Bearer ${credential}` } }
   });
-  const client = new Client({ name: "stoaken-cli", version: "0.5.0" });
+  const client = new Client({ name: "stoaken-cli", version: "0.5.1" });
   await client.connect(transport);
   try {
     const result = await client.callTool({ name: "list_brands", arguments: {} });
@@ -588,7 +716,7 @@ async function runInit(options) {
       options: [
         { value: "continue", label: `Continue with ${existing.brandName}` },
         { value: "switch", label: "Switch Brand" },
-        { value: "reauth", label: "Re-authenticate" }
+        { value: "reauth", label: "Sign in again" }
       ]
     });
     if (p2.isCancel(choice)) {
@@ -599,13 +727,12 @@ async function runInit(options) {
       skipToWrite = { brandId: existing.brandId, brandName: existing.brandName };
     }
   }
-  let credential;
-  let credentialKind;
+  let saved;
   if (!skipToWrite) {
     const authChoice = await p2.select({
       message: "How would you like to sign in?",
       options: [
-        { value: "browser", label: "Log in with browser" },
+        { value: "browser", label: "Sign in with browser" },
         { value: "key", label: "Paste an API key" }
       ]
     });
@@ -614,12 +741,13 @@ async function runInit(options) {
       return;
     }
     if (authChoice === "browser") {
+      p2.log.info("Opening your browser to sign in to Stoaken. It will ask whether Stoaken CLI may use your account. Check the name, then allow it.");
       const s2 = p2.spinner();
       s2.start("Waiting for you to finish signing in...");
       try {
-        credential = await loginWithBrowser(cwd, serverUrl);
-        credentialKind = "oauth";
-        s2.stop("Signed in.");
+        const { credentials, email } = await loginWithBrowser(cwd, serverUrl);
+        saved = credentials;
+        s2.stop(email ? `Signed in as ${email}.` : "Signed in.");
       } catch (error) {
         s2.stop("Sign-in failed.");
         p2.log.error(error instanceof Error ? error.message : String(error));
@@ -631,14 +759,13 @@ async function runInit(options) {
         p2.cancel("Cancelled.");
         return;
       }
-      credential = key;
-      credentialKind = "api_key";
+      saved = { kind: "api_key", token: key };
     }
     const s = p2.spinner();
     s.start("Fetching your Brands...");
     let brands;
     try {
-      brands = await listBrands(serverUrl, credential);
+      brands = await listBrands(serverUrl, saved.token);
     } catch (error) {
       s.stop("Failed to reach Stoaken.");
       p2.log.error(error instanceof Error ? error.message : String(error));
@@ -658,7 +785,7 @@ async function runInit(options) {
       return;
     }
     const brand = brands.find((b) => b.id === brandChoice);
-    await writeCredentials(cwd, { kind: credentialKind, token: credential });
+    await writeCredentials(cwd, saved);
     skipToWrite = { brandId: brand.id, brandName: brand.name };
   }
   const keepExports = existing?.brandId === skipToWrite.brandId && existing.exports !== void 0;
@@ -728,7 +855,7 @@ async function call(serverUrl, token, path) {
   let response;
   try {
     response = await fetch(new URL(path, serverUrl), {
-      headers: { Authorization: `Bearer ${token}`, "User-Agent": "stoaken-cli/0.5.0" }
+      headers: { Authorization: `Bearer ${token}`, "User-Agent": "stoaken-cli/0.5.1" }
     });
   } catch (error) {
     throw new Error(`Couldn't reach ${serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
@@ -933,7 +1060,7 @@ async function runExport(argv) {
     if (!config) throw new ExportUsageError('No stoaken.config.json here. Run "stoaken init" in your project first.');
     const serverUrl = args.server ?? config.serverUrl;
     const envToken = process.env.STOAKEN_TOKEN?.trim();
-    const token = envToken || (await readCredentials(cwd))?.token;
+    const token = envToken || (await freshCredentials(cwd, serverUrl))?.token;
     if (!token) throw new ExportUsageError('No credentials. Run "stoaken init", or set STOAKEN_TOKEN to an API key.');
     const targets = args.target ? [args.target] : readSavedTargets(config.exports);
     if (targets.length === 0) targets.push({ format: "css" });
@@ -1039,7 +1166,7 @@ switch (command) {
         "",
         "Usage:",
         "  stoaken init [--server <url>] [--client <name>]",
-        "                                  Authenticate, pick a Brand, and connect an AI tool",
+        "                                  Sign in, pick a Brand, and connect an AI tool",
         `                                  (${CLIENTS.join(", ")})`,
         "  stoaken export [options]        Write your tokens as code (stoaken export --help)"
       ].join("\n")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stoaken",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Stoaken CLI -- set up a project for MCP/API access, and export your design tokens as code.",
   "license": "UNLICENSED",
   "type": "module",
@@ -39,13 +39,16 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.0",
-    "open": "^11.0.2",
-    "@modelcontextprotocol/client": "^2.4.0"
+    "@modelcontextprotocol/client": "^2.4.0",
+    "open": "^11.0.2"
   },
   "devDependencies": {
     "@types/node": "^26.5.0",
-    "tsup": "^8.5.1",
+    "tsup": "^9.0.0",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2"
+  },
+  "overrides": {
+    "esbuild": "0.28.2"
   }
 }