@blocofy/cli 0.15.0 → 0.16.0

package/lib/secret-store.mjs

@@ -1,22 +1,35 @@
 import { spawnSync } from "node:child_process";
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { dirname } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 
 /**
  * CF-T1 (contract C1) — where credential SECRETS live. `credentials.json` only records which store holds a
- * context's secret (`secret: { store: "file" | "keychain" }`); the value itself is in one of:
+ * context's secret (`secret: { store: "file" | "keychain" | "dpapi" | "secret-service" }`); the value itself is in:
  *
- *   file      `~/.blocofy/secrets.json` (0600, atomic tmp+rename) `{ "<context>": { dev_token, api_key } }`.
- *   keychain  macOS Keychain via the `security` binary: service `blocofy-cli`, account `<context>:dev|api`.
- *             Opt-in only (`BLOCOFY_SECRET_STORE=keychain` or `login --keychain`); other platforms → error.
+ *   file      `~/.blocofy/secrets.json` (0600, atomic tmp+rename) `{ "<context>": { dev_token, api_key, oauth_tokens } }`.
+ *   keychain  macOS Keychain via the `security` binary: service `blocofy-cli`, account `<context>:dev|api|oauth`.
+ *             Opt-in for a pasted token (`BLOCOFY_SECRET_STORE=keychain` or `login --keychain`); other platforms → error.
  *
- * Both stores expose `get(context, kind)`, `set(context, kind, value)`, `remove(context)` with kind `dev|api`.
- * No method ever puts a secret into an error message.
+ * ADR-0014 §5.4 (wave P4) — the browser login's token set (kind `oauth`: one JSON string `{access_token,
+ * refresh_token, expires_at}`) lives in the OS secure store by default (`oauthSecretStore`):
+ *
+ *   macOS    keychain        (above)
+ *   Windows  dpapi           `%APPDATA%\blocofy\secrets.dpapi`: each value protected with DPAPI (user scope) by
+ *                            PowerShell `ConvertFrom-SecureString`; the secret goes in on stdin, never argv
+ *   Linux    secret-service  libsecret's `secret-tool` (stdin), when a DBus session is present
+ *   any      file            only when chosen explicitly (`--insecure-storage` / `BLOCOFY_SECRET_STORE=file`) and
+ *                            announced; an unavailable OS store is an error, never a silent plaintext downgrade
+ *
+ * Every store exposes `get(context, kind)`, `set(context, kind, value)`, `remove(context, kind?)` with kind
+ * `dev|api|oauth`. No method ever puts a secret into an error message.
  */
 
 export const KEYCHAIN_SERVICE = "blocofy-cli";
-const FIELD = { dev: "dev_token", api: "api_key" };
+const FIELD = { dev: "dev_token", api: "api_key", oauth: "oauth_tokens" };
+/** Every store name a context may record (`secret: { store }`). */
+export const STORE_NAMES = ["file", "keychain", "dpapi", "secret-service"];
 
 export class SecretStoreError extends Error {
   constructor(code, message) {
@@ -125,9 +138,163 @@ export function createKeychainSecretStore({ exec = defaultExec, platform = proce
   };
 }
 
+const storeAccount = (context, kind) => `${context}:${kind}`;
+
+/** Windows: the protect/unprotect scripts. The value travels on stdin both ways; argv carries only the script. */
+const PS_PROTECT =
+  "$s=[Console]::In.ReadToEnd(); $ss=ConvertTo-SecureString -String $s -AsPlainText -Force; [Console]::Out.Write((ConvertFrom-SecureString -SecureString $ss))";
+const PS_UNPROTECT =
+  "$e=[Console]::In.ReadToEnd().Trim(); $ss=ConvertTo-SecureString -String $e; $b=[Runtime.InteropServices.Marshal]::SecureStringToBSTR($ss); " +
+  "try { [Console]::Out.Write([Runtime.InteropServices.Marshal]::PtrToStringBSTR($b)) } finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($b) }";
+const powershell = (exec, script, input) => exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { input });
+
+/** The DPAPI file's default place: `%APPDATA%\blocofy\secrets.dpapi` (user scope). */
+export function dpapiPath(env = process.env) {
+  return join(env.APPDATA || join(homedir(), "AppData", "Roaming"), "blocofy", "secrets.dpapi");
+}
+
+/**
+ * Windows DPAPI adapter: the file maps `<context>:<kind>` to a DPAPI-protected blob (useless to another user or
+ * machine). An unreadable blob is an error (SECRET_STORE_FAILED), never "not logged in".
+ */
+export function createDpapiSecretStore({ exec = defaultExec, platform = process.platform, filePath = dpapiPath() } = {}) {
+  const ensure = () => {
+    if (platform !== "win32") throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", "The DPAPI secret store is only available on Windows.");
+  };
+  const readAll = () => {
+    let raw;
+    try {
+      raw = readFileSync(filePath, "utf8");
+    } catch (error) {
+      if (error?.code === "ENOENT") return {};
+      throw error;
+    }
+    try {
+      const data = JSON.parse(raw);
+      if (data && typeof data === "object" && !Array.isArray(data)) return data;
+    } catch {
+      /* fall through */
+    }
+    throw new SecretStoreError("CREDENTIALS_CORRUPT", `The protected secrets file is not valid JSON: ${filePath}. Nothing was written.`);
+  };
+  return {
+    name: "dpapi",
+    get(context, kind) {
+      ensure();
+      const blob = readAll()[storeAccount(context, kind)];
+      if (typeof blob !== "string" || !blob) return null;
+      const r = powershell(exec, PS_UNPROTECT, blob);
+      if (r.status !== 0 || r.error) throw new SecretStoreError("SECRET_STORE_FAILED", `Could not read the secret from the Windows protected store (${filePath}); it was not used.`);
+      return r.stdout || null;
+    },
+    set(context, kind, value) {
+      ensure();
+      const r = powershell(exec, PS_PROTECT, String(value));
+      const blob = String(r.stdout ?? "").trim();
+      if (r.status !== 0 || r.error || !blob) throw new SecretStoreError("SECRET_STORE_FAILED", "Could not protect the secret with Windows DPAPI. Nothing was saved.");
+      const data = readAll();
+      data[storeAccount(context, kind)] = blob;
+      writeJsonAtomic(filePath, data);
+    },
+    remove(context, kind = null) {
+      ensure();
+      const data = readAll();
+      let changed = false;
+      for (const k of kind ? [kind] : Object.keys(FIELD)) {
+        if (storeAccount(context, k) in data) {
+          delete data[storeAccount(context, k)];
+          changed = true;
+        }
+      }
+      if (changed) writeJsonAtomic(filePath, data);
+    },
+  };
+}
+
+/** Linux Secret Service (libsecret) adapter through `secret-tool`; the secret goes in on stdin. */
+export function createSecretServiceStore({ exec = defaultExec, platform = process.platform } = {}) {
+  const ensure = () => {
+    if (platform !== "linux") throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", "The Secret Service store is only used on Linux.");
+  };
+  const attrs = (context, kind) => ["service", KEYCHAIN_SERVICE, "account", storeAccount(context, kind)];
+  return {
+    name: "secret-service",
+    get(context, kind) {
+      ensure();
+      const r = exec("secret-tool", ["lookup", ...attrs(context, kind)]);
+      if (r.error && r.error.code === "ENOENT") throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", "`secret-tool` (libsecret) is not installed; the saved login cannot be read.");
+      if (r.status !== 0) return null;
+      const v = String(r.stdout ?? "").replace(/\r?\n$/, "");
+      return v || null;
+    },
+    set(context, kind, value) {
+      ensure();
+      const r = exec("secret-tool", ["store", `--label=Blocofy CLI (${context})`, ...attrs(context, kind)], { input: String(value) });
+      if (r.status !== 0 || r.error) throw new SecretStoreError("SECRET_STORE_FAILED", `Could not save the secret to the Secret Service (secret-tool exit ${r.status}). Nothing was saved.`);
+    },
+    remove(context, kind = null) {
+      ensure();
+      for (const k of kind ? [kind] : Object.keys(FIELD)) exec("secret-tool", ["clear", ...attrs(context, k)]);
+    },
+  };
+}
+
 /** `store` name → adapter. Unknown names are a usage error. */
-export function secretStoreFor(name, { filePath, exec, platform } = {}) {
+export function secretStoreFor(name, { filePath, exec, platform, dpapiPath: dpapiFile } = {}) {
   if (name === "file") return createFileSecretStore(filePath);
   if (name === "keychain") return createKeychainSecretStore({ exec, platform });
-  throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", `Unknown secret store "${name}" (use "file" or "keychain").`);
+  if (name === "dpapi") return createDpapiSecretStore({ exec, platform, ...(dpapiFile ? { filePath: dpapiFile } : {}) });
+  if (name === "secret-service") return createSecretServiceStore({ exec, platform });
+  throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", `Unknown secret store "${name}" (use ${STORE_NAMES.map((n) => `"${n}"`).join(", ")}).`);
+}
+
+/** Where a store keeps secrets, in words (login output names it). */
+export function storeLabel(name) {
+  switch (name) {
+    case "keychain":
+      return "macOS Keychain";
+    case "dpapi":
+      return "Windows DPAPI-protected file (OS protected file)";
+    case "secret-service":
+      return "Linux Secret Service (libsecret)";
+    case "file":
+      return "plain file ~/.blocofy/secrets.json (0600) — chosen explicitly";
+    default:
+      return String(name);
+  }
+}
+
+const OS_STORE = { darwin: "keychain", win32: "dpapi", linux: "secret-service" };
+
+/** Is the Secret Service usable here? A DBus session and an installed `secret-tool`. */
+function secretServiceAvailable(env, exec) {
+  if (!env.DBUS_SESSION_BUS_ADDRESS) return false;
+  const r = exec("secret-tool", ["--help"]);
+  return !(r.error && r.error.code === "ENOENT");
+}
+
+/**
+ * ADR-0014 §5.4 — the store for the browser login's tokens. `insecure` (`--insecure-storage`) or
+ * `BLOCOFY_SECRET_STORE=file` choose the 0600 file (`explicit: true`; the caller announces it); another
+ * `BLOCOFY_SECRET_STORE` value names an OS store, which must be this OS's. Otherwise this platform's OS store; none
+ * available → SECRET_STORE_UNAVAILABLE (never a silent plaintext downgrade).
+ */
+export function oauthSecretStore({ platform = process.platform, env = process.env, insecure = false, exec = defaultExec } = {}) {
+  const unavailable = (why) =>
+    new SecretStoreError(
+      "SECRET_STORE_UNAVAILABLE",
+      `${why} The CLI login is never saved in a plain file automatically. To keep it in ~/.blocofy/secrets.json (0600) instead, choose that explicitly: blocofy login --insecure-storage (or BLOCOFY_SECRET_STORE=file). Nothing was saved.`,
+    );
+  const requested = env.BLOCOFY_SECRET_STORE;
+  if (insecure || requested === "file") return { name: "file", explicit: true };
+  if (requested !== undefined && requested !== "") {
+    if (!STORE_NAMES.includes(requested)) throw unavailable(`BLOCOFY_SECRET_STORE="${requested}" is not a known store (${STORE_NAMES.join(", ")}).`);
+    if (OS_STORE[platform] !== requested) throw unavailable(`The "${requested}" store is not available on this operating system (${platform}).`);
+  }
+  const name = OS_STORE[platform];
+  if (!name) throw unavailable(`No OS secure store is supported on this operating system (${platform}).`);
+  if (name === "secret-service" && !secretServiceAvailable(env, exec)) {
+    throw unavailable("No Secret Service is available (it needs a desktop DBus session and `secret-tool` from libsecret).");
+  }
+  return { name, explicit: false };
 }

package/lib/target.mjs

@@ -3,7 +3,7 @@ import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync,
 import { dirname, join, resolve } from "node:path";
 
 import { fetchWithRetry } from "./http.mjs";
-import { API_KEY_PREFIX } from "./media-uses.mjs";
+import { API_KEY_PREFIX, isValidApiKey } from "./media-uses.mjs";
 
 /**
  * CF-T1/T2 (contract C2) — project binding + target resolution + remote identity verification.
@@ -108,7 +108,7 @@ function lstatOrNull(p) {
  * before the first write); each file is written to a fresh temp file in the same directory (`wx`, 0644) and
  * renamed into place. `staleLocal: true` (link) removes a `local.json` that an env-context binding does not own.
  */
-export function writeBinding(root, { site, platformOrigin, contextName, staleLocal = false }) {
+export function writeBinding(root, { site, platformOrigin, contextName, staleLocal = false, profile = null, ignore = ["local.json"] }) {
   const d = join(root, PROJECT_DIR);
   const refuse = (path, what) => {
     throw new TargetError("TARGET_BINDING_INVALID", `${path} ${what}; the project binding was not written.`, { binding: path });
@@ -122,10 +122,12 @@ export function writeBinding(root, { site, platformOrigin, contextName, staleLoc
     if (st.isSymbolicLink() || !st.isDirectory()) refuse(d, "is not a real directory");
   }
   const project = { schema_version: 1, site_id: site.id, site_slug: site.slug ?? null, platform_origin: origin(platformOrigin) };
+  // ADR-0014 §5.6 step 6 — additive: the profile the project was set up with (an older CLI ignores it; the server decides).
+  if (profile && typeof profile.id === "string") project.profile = { id: profile.id, version: profile.version ?? null };
   const writes = [["project.json", JSON.stringify(project, null, 2) + "\n"]];
   const ownsLocal = contextName && contextName !== ENV_CONTEXT;
   if (ownsLocal) writes.push(["local.json", JSON.stringify({ context: contextName }, null, 2) + "\n"]);
-  writes.push([".gitignore", "local.json\n"]);
+  writes.push([".gitignore", ignore.join("\n") + "\n"]);
   for (const name of ["project.json", "local.json", ".gitignore"]) {
     const f = lstatOrNull(join(d, name));
     if (f && (f.isSymbolicLink() || !f.isFile())) refuse(join(d, name), "is a symlink or not a regular file");
@@ -352,7 +354,7 @@ export function assertCredentialTypes({ resolved, secrets }) {
   const refuse = (kind, secret) => {
     const env = Boolean(resolved.env);
     const where = kind === "dev" ? (env ? "BLOCOFY_TOKEN" : `The dev token of context "${resolved.name}"`) : env ? "BLOCOFY_API_KEY" : `The API key of context "${resolved.name}"`;
-    const other = kind === "dev" ? secret.startsWith("blcf_") : secret.startsWith(DEV_TOKEN_PREFIX);
+    const other = kind === "dev" ? secret.startsWith("blcf_") : secret.startsWith(DEV_TOKEN_PREFIX) || secret.startsWith("bcf2_");
     const holds = kind === "dev" ? (other ? "holds a v1 API key (blcf_…)" : "is not a dev token") : other ? "holds a theme dev token (bcf_…)" : "is not a v1 API key";
     const expected = kind === "dev" ? `a theme dev token starts with ${DEV_TOKEN_PREFIX}` : `a v1 API key starts with ${API_KEY_PREFIX}`;
     const fix = env
@@ -369,8 +371,10 @@ export function assertCredentialTypes({ resolved, secrets }) {
       1,
     );
   };
-  if (resolved.context.dev && typeof secrets.devToken === "string" && !secrets.devToken.startsWith(DEV_TOKEN_PREFIX)) refuse("dev", secrets.devToken);
-  if (resolved.context.api && typeof secrets.apiKey === "string" && !(secrets.apiKey.startsWith(API_KEY_PREFIX) && secrets.apiKey.length > API_KEY_PREFIX.length)) refuse("api", secrets.apiKey);
+  // A CLI login's context carries its own short-lived token in both places; the refresh layer vouches for it.
+  if (resolved.oauth) return;
+  if (resolved.context.dev && typeof secrets.devToken === "string" && !(secrets.devToken.startsWith(DEV_TOKEN_PREFIX) || secrets.devToken.startsWith("bcf2_"))) refuse("dev", secrets.devToken);
+  if (resolved.context.api && typeof secrets.apiKey === "string" && !isValidApiKey(secrets.apiKey)) refuse("api", secrets.apiKey);
 }
 
 // ── remote identity ─────────────────────────────────────────────────────────────────────────────────────────
@@ -386,7 +390,17 @@ async function getJson(fetchImpl, url, secret, retry = {}) {
     return { error: `unreachable (${error?.name === "TimeoutError" ? "timeout" : "network error"})` };
   }
   const text = await res.text().catch(() => "");
-  if (!res.ok) return { error: `HTTP ${res.status}` };
+  if (!res.ok) {
+    // ADR-0014: keep the server's refusal code (v1 `{error:{code}}`, renderer `{error, code}`) — e.g. audience_mismatch.
+    let code = null;
+    try {
+      const j = JSON.parse(text);
+      code = typeof j?.error?.code === "string" ? j.error.code : typeof j?.code === "string" ? j.code : null;
+    } catch {
+      code = null;
+    }
+    return { error: `HTTP ${res.status}${code ? ` ${code}` : ""}`, serverCode: code };
+  }
   try {
     return { body: JSON.parse(text) };
   } catch {
@@ -394,15 +408,15 @@ async function getJson(fetchImpl, url, secret, retry = {}) {
   }
 }
 
-function unverified(what, url, reason) {
-  return new TargetError("TARGET_UNVERIFIED", `Could not verify the target site via ${what} (${reason}). Nothing was sent or written.`, { endpoint: url, reason });
+function unverified(what, url, reason, serverCode = null) {
+  return new TargetError("TARGET_UNVERIFIED", `Could not verify the target site via ${what} (${reason}). Nothing was sent or written.`, { endpoint: url, reason, ...(serverCode ? { server_code: serverCode } : {}) });
 }
 
 /** `GET {url}/api/dev/whoami` → `{ site, platformOrigin, liveThemeId }` or TARGET_UNVERIFIED. */
 export async function verifyDev({ url, token, fetchImpl = globalThis.fetch, retry = {} }) {
   const endpoint = `${url.replace(/\/+$/, "")}/api/dev/whoami`;
   const r = await getJson(fetchImpl, endpoint, token, retry);
-  if (r.error) throw unverified("/api/dev/whoami", endpoint, r.error);
+  if (r.error) throw unverified("/api/dev/whoami", endpoint, r.error, r.serverCode);
   const site = r.body?.site;
   if (!isObj(site) || !(typeof site.id === "string" || Number.isFinite(site.id)) || typeof site.slug !== "string") {
     throw unverified("/api/dev/whoami", endpoint, "malformed response (no site id/slug)");
@@ -414,7 +428,7 @@ export async function verifyDev({ url, token, fetchImpl = globalThis.fetch, retr
 export async function verifyApi({ url, apiKey, fetchImpl = globalThis.fetch, retry = {} }) {
   const endpoint = `${url.replace(/\/+$/, "")}/api/v1/ping`;
   const r = await getJson(fetchImpl, endpoint, apiKey, retry);
-  if (r.error) throw unverified("/api/v1/ping", endpoint, r.error);
+  if (r.error) throw unverified("/api/v1/ping", endpoint, r.error, r.serverCode);
   const site = r.body?.site;
   if (!isObj(site) || !(typeof site.id === "string" || Number.isFinite(site.id))) {
     throw unverified("/api/v1/ping", endpoint, "malformed response (no site id)");

package/lib/theme-sync.mjs

@@ -73,6 +73,8 @@ async function responseError(res) {
   // `{ error: "<sentence>", code }` (e.g. dev/publish `work_not_publishable`): the code sits beside the sentence.
   else if (typeof body?.code === "string" && /^[a-z][a-z0-9_]*$/.test(body.code)) err.code = body.code;
   else if (typeof detail === "string" && /^[a-z][a-z0-9_]*$/.test(detail)) err.code = detail;
+  // ADR-0014: a credential refusal's details (e.g. credential_reapproval_required's due date) for the CLI's words.
+  if (body && typeof body.details === "object" && body.details !== null) err.serverDetails = body.details;
   return err;
 }
 

package/lib/validate.mjs

@@ -13,6 +13,9 @@ export function isValidUrl(u) {
   return /^https?:\/\/.+/i.test(u);
 }
 
+/** A theme dev token: `bcf_` (legacy) or `bcf2_` (profiled, ADR-0014 §3.2: needs CLI >= 0.16.0). */
+export const DEV_TOKEN_PREFIXES = ["bcf_", "bcf2_"];
+
 export function isValidToken(t) {
-  return typeof t === "string" && t.startsWith("bcf_") && t.length >= 24;
+  return typeof t === "string" && DEV_TOKEN_PREFIXES.some((p) => t.startsWith(p)) && t.length >= 24;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocofy/cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Develop your Blocofy theme locally against live data with instant preview — login, theme dev, pull, push.",
   "type": "module",
   "license": "MIT",