@nextcommerce/campaigns-os 1.37.3 → 1.41.2

package/src/credential-store.mjs

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+const fail = () => new Error('Credential storage is unavailable or unsafe. Check your user credential directory/keychain; no credential was printed. For a broken keychain login, run campaigns-os logout --store <store> to clear its local selection.');
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const SERVICE = 'com.nextcommerce.campaigns-os';
+const MAX_BYTES = 65536;
+
+// No secret is placed in argv or the environment. security's interactive mode
+// accepts its command on a private pipe; hex encoding avoids its command parser.
+export function macKeychain({ run = spawnSync, platform = process.platform } = {}) {
+  const invoke = (args, input) => {
+    let result;
+    try { result = run('/usr/bin/security', args, { input, encoding: 'utf8', timeout: 5000, maxBuffer: MAX_BYTES * 3, stdio: ['pipe', 'pipe', 'pipe'] }); }
+    catch { throw fail(); }
+    if (result.error || result.signal) throw fail();
+    return result;
+  };
+  return {
+    available: platform === 'darwin' && fs.existsSync('/usr/bin/security'),
+    read(account) {
+      const result = invoke(['find-generic-password', '-s', SERVICE, '-a', account, '-w']);
+      if (result.status === 44) return null;
+      if (result.status !== 0) throw fail();
+      // Native security prints non-ASCII password bytes as lowercase hex.
+      // This provider stores JSON objects only: never guess how to decode an
+      // arbitrary password, and reject malformed UTF-8 rather than replacing it.
+      if (typeof result.stdout !== 'string' || Buffer.byteLength(result.stdout) > MAX_BYTES * 2 + 2) throw fail();
+      let value = result.stdout.trimEnd();
+      if (!value.startsWith('{')) {
+        if (!/^(?:[a-f0-9]{2})+$/.test(value) || !value.startsWith('7b') || !value.endsWith('7d')) throw fail();
+        try { value = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(value, 'hex')); }
+        catch { throw fail(); }
+      }
+      if (Buffer.byteLength(value) > MAX_BYTES) throw fail();
+      try {
+        const parsed = JSON.parse(value);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw fail();
+      } catch { throw fail(); }
+      return value;
+    },
+    write(account, value) {
+      // account is an internally generated SHA256, never user input.
+      if (!/^[a-f0-9]{64}$/.test(account)) throw fail();
+      const result = invoke(['-i'], `add-generic-password -U -s ${SERVICE} -a ${account} -X ${Buffer.from(value).toString('hex')}\n`);
+      if (result.status !== 0 || this.read(account) !== value) throw fail();
+    },
+    clear(account) {
+      const result = invoke(['delete-generic-password', '-s', SERVICE, '-a', account]);
+      if (result.status !== 0 && result.status !== 44) throw fail();
+    },
+  };
+}
+
+export function createCredentialStore({ home = os.homedir(), keychain = macKeychain(), uid = process.getuid?.(), lockTimeoutMs = 3000 } = {}) {
+  const root = path.resolve(home, '.campaigns-os');
+  const directory = path.join(root, 'credentials');
+  const inspect = (name, directoryExpected, create = false, privateLeaf = true) => {
+    if (create) { try { fs.mkdirSync(name, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw fail(); } }
+    let stat;
+    try { stat = fs.lstatSync(name); } catch (error) { if (!create && error.code === 'ENOENT') return null; throw fail(); }
+    if (stat.isSymbolicLink() || (directoryExpected ? !stat.isDirectory() : !stat.isFile()) || (uid !== undefined && stat.uid !== uid) || (privateLeaf ? (stat.mode & 0o777) !== (directoryExpected ? 0o700 : 0o600) : (stat.mode & 0o022)) || (!directoryExpected && (stat.nlink !== 1 || stat.size > MAX_BYTES))) throw fail();
+    return stat;
+  };
+  const prepare = () => {
+    // This fixed user-state path does not depend on cwd or project markers.
+    // A dotfiles repository at home must not turn it into campaign storage.
+    const h = fs.lstatSync(home);
+    if (!h.isDirectory() || h.isSymbolicLink() || (uid !== undefined && h.uid !== uid)) throw fail();
+    inspect(root, true, true, false); inspect(directory, true, true);
+  };
+  const identifier = binding => createHash('sha256').update(JSON.stringify([binding.gateway, binding.client_id, binding.store])).digest('hex');
+  return {
+    async transaction(binding, operation) {
+      try { prepare(); } catch { throw fail(); }
+      const id = identifier(binding), file = path.join(directory, id + '.json'), lock = path.join(directory, id + '.lock');
+      const deadline = Date.now() + lockTimeoutMs;
+      for (;;) {
+        try { fs.mkdirSync(lock, { mode: 0o700 }); break; }
+        catch (error) { if (error.code !== 'EEXIST') throw fail(); inspect(lock, true); if (Date.now() >= deadline) throw new Error('Credential storage is busy. Retry after the other login or refresh finishes. If a process was interrupted, confirm no campaigns-os process is running before removing its stale .lock directory in your user credential store.'); await wait(50); }
+      }
+      try {
+        const readFile = () => {
+          if (!inspect(file, false)) return null;
+          const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+          try {
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || (uid !== undefined && stat.uid !== uid) || (stat.mode & 0o777) !== 0o600 || stat.nlink !== 1 || stat.size > MAX_BYTES) throw fail();
+            return fs.readFileSync(fd, 'utf8');
+          } finally { fs.closeSync(fd); }
+        };
+        const parse = raw => {
+          if (typeof raw !== 'string' || Buffer.byteLength(raw) > MAX_BYTES) throw fail();
+          try { return JSON.parse(raw); } catch { throw fail(); }
+        };
+        let stored = readFile();
+        let pointer = stored === null ? null : parse(stored);
+        let keychainPointer = pointer?.backend === 'keychain';
+        if (keychainPointer && (!/^[a-f0-9]{64}$/.test(pointer.account) || !keychain.available)) throw fail();
+        // A private pointer commits a staged keychain item atomically. A failed
+        // keychain write never replaces the previously valid login. Existing
+        // file-backed records stay file-backed instead of silently migrating.
+        const useKeychain = keychainPointer || (pointer === null && keychain.available);
+        const read = () => {
+          const raw = keychainPointer ? keychain.read(pointer.account) : stored;
+          if (raw === null) { if (keychainPointer) throw fail(); return null; }
+          const record = parse(raw);
+          if (record.gateway !== binding.gateway || record.client_id !== binding.client_id || record.store !== binding.store) throw fail();
+          return record;
+        };
+        const atomicFile = value => {
+          inspect(file, false);
+          const temporary = path.join(directory, id + '.' + randomUUID() + '.tmp');
+          let fd;
+          try {
+            fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+            fs.writeFileSync(fd, value); fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+            fs.renameSync(temporary, file);
+          } finally { if (fd !== undefined) fs.closeSync(fd); if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
+        };
+        const write = record => {
+          if (record.gateway !== binding.gateway || record.client_id !== binding.client_id || record.store !== binding.store) throw fail();
+          const value = JSON.stringify(record);
+          if (Buffer.byteLength(value) > MAX_BYTES) throw fail();
+          if (!useKeychain) { atomicFile(value); stored = value; pointer = record; keychainPointer = false; return; }
+          const account = createHash('sha256').update(id + randomUUID()).digest('hex');
+          const oldAccount = keychainPointer ? pointer.account : null;
+          const nextPointer = { backend: 'keychain', account, ...binding };
+          try {
+            keychain.write(account, value);
+            atomicFile(JSON.stringify(nextPointer));
+            pointer = nextPointer; stored = JSON.stringify(nextPointer); keychainPointer = true;
+          } catch (error) { try { keychain.clear(account); } catch { /* staged item is never selected */ } throw error; }
+          if (oldAccount) { try { keychain.clear(oldAccount); } catch { /* old item is no longer selected */ } }
+        };
+        const clear = () => {
+          let keychainRemoved = true;
+          try { if (keychainPointer) keychain.clear(pointer.account); }
+          catch { keychainRemoved = false; }
+          if (inspect(file, false)) fs.unlinkSync(file);
+          stored = null; pointer = null; keychainPointer = false;
+          return { local_cleared: true, keychain_item_removed: keychainRemoved };
+        };
+        return await operation({ read, write, clear });
+      } catch (error) {
+        // Do not attach subprocess output or filesystem content to exceptions.
+        if (error instanceof Error && error.message.startsWith('Credential storage')) throw error;
+        throw fail();
+      } finally { try { fs.rmdirSync(lock); } catch { throw fail(); } }
+    },
+    async listBindings() {
+      try {
+        if (!inspect(root, true, false, false) || !inspect(directory, true)) return [];
+        const names = fs.readdirSync(directory).filter(name => /^[a-f0-9]{64}\.json$/.test(name));
+        if (names.length > 1024) throw fail();
+        const bindings = [];
+        for (const name of names) {
+          const file = path.join(directory, name); inspect(file, false);
+          const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+          let value;
+          try {
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || stat.size > MAX_BYTES || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || (uid !== undefined && stat.uid !== uid)) throw fail();
+            value = JSON.parse(fs.readFileSync(fd, 'utf8'));
+          } finally { fs.closeSync(fd); }
+          if (value?.backend === 'keychain' && !value.store) {
+            if (!keychain.available || !/^[a-f0-9]{64}$/.test(value.account)) throw fail();
+            value = JSON.parse(keychain.read(value.account));
+          }
+          if (!value || typeof value.gateway !== 'string' || typeof value.client_id !== 'string' || typeof value.store !== 'string') throw fail();
+          const binding = { gateway: value.gateway, client_id: value.client_id, store: value.store };
+          if (identifier(binding) + '.json' !== name) throw fail();
+          bindings.push(binding);
+        }
+        return bindings;
+      } catch { throw fail(); }
+    },
+    read(binding) { return this.transaction(binding, storage => storage.read()); },
+  };
+}

package/src/deviation.mjs

@@ -30,13 +30,14 @@ const EXPECTED_COMMANDS_BY_STAGE = Object.freeze({
 });
 
 // The command word of a produced command line, whichever install prefix it
-// was spelled with (bare `campaigns-os`, `npx campaigns-os`, `npm run
+// was spelled with (bare `campaigns-os`, `npx --no-install campaigns-os`, the
+// `npx campaigns-os` that versions before 1.41.2 printed, `npm run
 // campaigns-os --`, or `npx --yes <git-spec>` from an npx cache).
 export function commandWord(command) {
   if (typeof command !== "string") return null;
   const stripped = command
     .replace(/^npx\s+--yes\s+\S+\s+/, "campaigns-os ")
-    .replace(/^npx\s+campaigns-os\s+/, "campaigns-os ")
+    .replace(/^npx\s+(?:--no-install\s+)?campaigns-os\s+/, "campaigns-os ")
     .replace(/^npm\s+run\s+campaigns-os\s+--\s+/, "campaigns-os ");
   return stripped.match(/^campaigns-os\s+([a-z-]+)/)?.[1] || null;
 }

package/src/diagnostic.mjs

@@ -1,7 +1,10 @@
 // A projection, never a scrubber: source objects and free text never enter
 // the export. Unknown producer values have fixed, non-actionable markers.
 const MODES = new Set(["checkout", "node_modules", "global", "npx_cache", "package_directory"]);
-const PLATFORMS = new Set(["claude", "codex", "agents", "all"]);
+// The export's platform allowlist. `installed` is a scope label, not a
+// platform: no --platform was given and status checked only the platforms
+// with Campaigns OS skills installed. It is never a --platform value.
+const PLATFORMS = new Set(["claude", "codex", "agents", "all", "installed"]);
 const STAGES = new Set(["prepare-build", "doctor-blocked", "setup", "build", "polish", "deploy", "qa", "done"]);
 const STATUSES = new Set(["ready", "attention_required", "ready_with_warnings", "ready_with_waivers", "blocked"]);
 const REASONS = new Set([

package/src/gate-actions.mjs

@@ -95,8 +95,8 @@ export function requiredActionText(action, { packetPath = null, reportPath = nul
     command = `${command} --report ${shellToken(reportPath)}`;
   }
   // Registry commands are stored bare; the printed text is spelled for the
-  // install this package runs from (bare from a checkout, `npx campaigns-os`
-  // from a campaign folder), once, here.
+  // install this package runs from (bare from a checkout,
+  // `npx --no-install campaigns-os` from a campaign folder), once, here.
   if (command && command.startsWith("campaigns-os ")) {
     return `${invocationPrefixFor(PACKAGE_ROOT)} ${command.slice("campaigns-os ".length)}`;
   }

package/src/install-mode.mjs

@@ -17,6 +17,13 @@ const PACKAGE_INSTALL_MODE_LABELS = Object.freeze({
 
 const PUBLIC_GIT_SOURCE = "github:NextCommerceCo/campaigns-os";
 
+// How a consumer install is spelled. `campaigns-os` is only the bin name of
+// @nextcommerce/campaigns-os: where no installed copy is found, a plain
+// `npx campaigns-os` looks the bin name up as a registry package and, with no
+// terminal to ask, installs whatever answers. `--no-install` makes npx run the
+// project's copy or fail.
+export const LOCAL_INVOCATION_PREFIX = "npx --no-install campaigns-os";
+
 function realpathOrSelf(path) {
   try {
     return realpathSync(path);
@@ -216,13 +223,13 @@ function runCommand(command, args) {
 
 // How a command should be spelled so it runs THIS install: the checkout
 // script from a checkout; `npx --yes <spec>` from an npx cache (nothing is on
-// PATH); `npx campaigns-os` from a consumer install (the toolkit pinned as a
-// devDependency of the campaign folder) — always, because `npx` itself puts
-// node_modules/.bin on PATH for the duration of the command, so a PATH match
-// seen here says nothing about the operator's shell, and a bare command they
-// paste there would not resolve; the bare binary from a plain package
-// directory. The PATH comparison is still reported so a shadowing install is
-// visible.
+// PATH); `npx --no-install campaigns-os` from a consumer install (the toolkit
+// pinned as a devDependency of the campaign folder) — always, because `npx`
+// itself puts node_modules/.bin on PATH for the duration of the command, so a
+// PATH match seen here says nothing about the operator's shell, and a bare
+// command they paste there would not resolve; the bare binary from a plain
+// package directory. The PATH comparison is still reported so a shadowing
+// install is visible.
 export function resolveInvocation(root, pkg = {}, install = localInstallStatus(root, pkg)) {
   const binRel = pkg.bin && typeof pkg.bin === "object"
     ? pkg.bin["campaigns-os"]
@@ -237,7 +244,7 @@ export function resolveInvocation(root, pkg = {}, install = localInstallStatus(r
   let prefix;
   if (install.mode === "checkout") prefix = "npm run campaigns-os --";
   else if (install.mode === "npx_cache") prefix = install.pinned?.spec ? `npx --yes ${install.pinned.spec}` : "campaigns-os";
-  else if (install.mode === "node_modules") prefix = "npx campaigns-os";
+  else if (install.mode === "node_modules") prefix = LOCAL_INVOCATION_PREFIX;
   else if (install.mode === "global") prefix = matches ? "campaigns-os" : `node ${shellToken(localBin)}`;
   else prefix = "campaigns-os";
   return {
@@ -281,4 +288,5 @@ export function invocationPrefixFor(root, pkg = null) {
 // registries, tests) keeps the canonical spelling; only what is printed or
 // emitted for an operator or agent to copy is rewritten. Skill names such as
 // next-campaigns-os-setup, file names (campaigns-os.mjs), and already-prefixed
-// forms (`npx campaigns-os`, `npm run campaigns-os --`) are left alone.
+// forms (`npx --no-install campaigns-os`, `npm run campaigns-os --`) are left
+// alone.

package/src/lifecycle.mjs

@@ -13,12 +13,107 @@
 // so the CLI exit code is unchanged, and lifecycle persistence is opt-in and
 // non-fatal. No network, no credentials.
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 
 export const LIFECYCLE_SCHEMA = "campaigns-os-command-lifecycle/v0";
 export const LIFECYCLE_JOURNAL_REL_PATH = ".campaign-runtime/command-lifecycle.jsonl";
 
+// A refusal raised BEFORE the command's handler ran: an unknown top-level
+// command, an unknown subcommand, or a flag the command refuses up front.
+// Every such throw site builds its error here so the lifecycle journal can
+// recognize a refusal from ONE place (the CLI's persist step) instead of
+// matching messages — a typo must not materialize a file under the target.
+// Only the tag is added: the message is passed through and the exit code is
+// untouched, because bin/campaigns-os.mjs special-cases filesystem errno codes
+// only and falls through to the same `campaigns-os: <message>` / exit 1 path.
+// One mechanism, read two ways. The tag travels on the thrown error for the
+// usual path (onFinish is handed the error), and `refusalSeen()` records the
+// same verdict for the paths that CATCH a refusal to render it — the CLI's
+// `waiveOrRefuse` prints the `{ ok: false, error }` body under --json and
+// returns, so onFinish gets no `thrown` at all.
+//
+// That caught-refusal verdict is per INVOCATION, not per module. main() runs
+// its body inside `runWithRefusalScope`, which puts a fresh `{ seen: false }`
+// in an AsyncLocalStorage store; `refused()` marks the store that is active
+// where the refusal is raised and `refusalSeen()` reads the store active where
+// persistence runs. A module-global flag was wrong: two in-process main() calls
+// interleave (the second one's reset cleared the first one's verdict before its
+// onFinish ran, and the refused invocation journaled an entry). AsyncLocalStorage
+// follows the await chain, so each invocation sees only its own verdict without
+// threading a holder through every throw site. Outside any scope — a command
+// module calling `refused()` directly in a unit test — there is no store and
+// `refusalSeen()` is false; the error tag is added either way.
+//
+// LIMITATION, stated so it is not mistaken for a bug: AsyncLocalStorage
+// propagates the store into callbacks scheduled inside the scope (a
+// setImmediate/setTimeout/unawaited callback still sees it), so a deferred
+// `refused()` does mark the store — but it may do so AFTER the invocation's
+// persistence step has already run and read `refusalSeen()` as false, so the
+// journal entry would already be written while the error carries the tag.
+// This is not defended against, because refusals are synchronous BY CONTRACT:
+// they are raised up front, before the handler runs, on the same tick as the
+// argv check that rejects the invocation. A refusal that needs to be deferred
+// is not an up-front refusal and should be a handler failure instead — which is
+// journaled, as it should be.
+//
+// This lives here, not in the CLI, because refusals are raised in command
+// modules too (`qa`'s unknown subcommand) and those modules are imported BY
+// cli.mjs: importing the factory back out of cli.mjs would be circular, and
+// re-listing the subcommands anywhere else would be a second command list.
+// lifecycle.mjs imports nothing from this repository, so it is safe to import
+// from anywhere.
+export const REFUSED_INVOCATION = "refused_invocation";
+const refusalScope = new AsyncLocalStorage();
+
+/** Run `fn` with its own refusal verdict. Returns whatever `fn` returns. */
+export function runWithRefusalScope(fn) {
+  return refusalScope.run({ seen: false }, fn);
+}
+
+/**
+ * Build a tagged refusal. INVARIANT: a refusal must be thrown or rendered —
+ * never built and swallowed. The scope is marked HERE, at construction, not at
+ * the throw, because the paths that catch a refusal to render it (waiveOrRefuse)
+ * hand onFinish no error to inspect. The cost of marking early is that a
+ * `refused()` built inside a `try` that discards it would suppress the journal
+ * entry for an invocation whose handler did run. No call site does that today
+ * (no `requireArg` sits inside a `try`), and none may: if you need to probe
+ * whether an argument is present, test for it — do not construct a refusal
+ * speculatively.
+ */
+export function refused(message) {
+  const store = refusalScope.getStore();
+  if (store) store.seen = true;
+  const error = new Error(message);
+  error.code = REFUSED_INVOCATION;
+  return error;
+}
+
+export function refusalSeen() {
+  return refusalScope.getStore()?.seen === true;
+}
+
+/**
+ * Run `fn()` and re-throw anything it throws as a tagged refusal, message
+ * byte-identical. The contract it encodes: THE TAG IS APPLIED AT THE UP-FRONT
+ * CALL SITE, NOT INSIDE THE VALIDATOR. The validators this wraps are shared —
+ * `assertSecureProxyBase` also runs mid-handler on the remit rail, and the
+ * order-creation limit is re-checked after a browser has launched — and a throw
+ * from those positions is a handler failure, the most valuable lifecycle entry
+ * there is. Only the caller knows it is checking argv before anything has been
+ * resolved, read, written, or launched, so only the caller may say "refusal".
+ * Wrap the up-front call; leave the shared validator untagged.
+ */
+export function refusing(fn) {
+  try {
+    return fn();
+  } catch (error) {
+    throw refused(error.message);
+  }
+}
+
 function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }

package/src/login.mjs

@@ -0,0 +1,152 @@
+import { createCredentialStore } from './credential-store.mjs';
+
+export const GATEWAY = 'https://mcp.nextcommerce.com';
+export const CLIENT_ID = 'campaigns-os-owned-store-pilot';
+export const RESOURCE = GATEWAY + '/campaigns';
+export const SCOPE = 'campaigns:read';
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const safeString = (value, max = 8192) => typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/u.test(value);
+class GatewayError extends Error {
+  constructor(code, status = 0) { super('Gateway request failed.'); this.code = code; this.status = status; }
+}
+export function canonicalLoginStore(value) {
+  if (typeof value !== 'string') throw new Error('Provide --store <subdomain> or --store <subdomain.29next.store>.');
+  const host = value.trim().toLowerCase();
+  const label = host.endsWith('.29next.store') ? host.slice(0, -13) : host;
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) throw new Error('Provide --store <subdomain> or --store <subdomain.29next.store>.');
+  return label + '.29next.store';
+}
+export function authenticationArguments(argv) {
+  const command = argv[0];
+  if (!['login', 'logout'].includes(command) || !(argv.length === 1 || (argv.length === 3 && argv[1] === '--store'))) {
+    throw new Error('Use: campaigns-os login [--store <subdomain>], or campaigns-os logout [--store <subdomain>]. No token arguments are accepted.');
+  }
+  return { command, store: argv.length === 3 ? canonicalLoginStore(argv[2]) : null };
+}
+async function askStore() {
+  const { createInterface } = await import('node:readline/promises');
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  try { return await prompt.question('Store subdomain (or network domain): '); }
+  finally { prompt.close(); }
+}
+const bindingFor = store => ({ gateway: GATEWAY, client_id: CLIENT_ID, store });
+
+// Deliberately no configurable origin/discovery and no response-body errors.
+export async function gatewayRequest(route, { form, accessToken, fetchImpl = globalThis.fetch, timeoutMs = 15000 } = {}) {
+  if (!['/device/authorize', '/token', '/revoke'].includes(route)) throw new GatewayError('invalid_request');
+  const controller = new AbortController();
+  let reader, timer;
+  const work = async () => {
+    const headers = { Accept: 'application/json' };
+    if (form) headers['Content-Type'] = 'application/x-www-form-urlencoded';
+    if (accessToken) headers.Authorization = `Bearer ${accessToken}`;
+    const response = await fetchImpl(GATEWAY + route, { method: 'POST', headers, body: form ? new URLSearchParams(form).toString() : undefined, redirect: 'error', signal: controller.signal });
+    if (response.redirected || (response.url && response.url !== GATEWAY + route)) throw new GatewayError('invalid_response');
+    if (response.headers.get('content-type')?.split(';')[0] !== 'application/json') throw new GatewayError('invalid_response', response.status);
+    reader = response.body?.getReader();
+    if (!reader) throw new GatewayError('invalid_response', response.status);
+    const chunks = []; let bytes = 0;
+    for (;;) {
+      const { value, done } = await reader.read(); if (done) break;
+      bytes += value.byteLength; if (bytes > 32768) throw new GatewayError('invalid_response'); chunks.push(value);
+    }
+    let data;
+    try { data = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw new GatewayError('invalid_response', response.status); }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new GatewayError('invalid_response', response.status);
+    if (!response.ok) {
+      const code = ['authorization_pending', 'slow_down', 'access_denied', 'expired_token', 'invalid_grant', 'invalid_token', 'invalid_request', 'temporarily_unavailable'].includes(data.error) ? data.error : 'request_refused';
+      throw new GatewayError(code, response.status);
+    }
+    return data;
+  };
+  try {
+    return await Promise.race([work(), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new GatewayError('unavailable')); }, Math.max(1, Math.min(timeoutMs, 15000))); })]);
+  } catch (error) { throw error instanceof GatewayError ? error : new GatewayError('unavailable'); }
+  finally { clearTimeout(timer); controller.abort(); void reader?.cancel().catch(() => {}); }
+}
+export function credentialFromResponse(data, store, receivedAt) {
+  if (!safeString(data.access_token) || !safeString(data.refresh_token) || data.access_token === data.refresh_token || data.token_type !== 'Bearer' || data.resource !== RESOURCE || data.scope !== SCOPE || !Number.isInteger(data.expires_in) || data.expires_in <= 0 || data.expires_in > 3600 || !safeString(data.grant_id, 256) || !safeString(data.gateway_version, 128)) throw new GatewayError('invalid_response');
+  return { schema_version: 1, ...bindingFor(store), resource: RESOURCE, scope: SCOPE, token_type: 'Bearer', access_token: data.access_token, refresh_token: data.refresh_token, access_expires_at: receivedAt + data.expires_in * 1000, received_at: receivedAt, grant_id: data.grant_id, gateway_version: data.gateway_version };
+}
+function validateStored(record) {
+  if (record.schema_version !== 1 || record.resource !== RESOURCE || record.scope !== SCOPE || record.token_type !== 'Bearer' || !safeString(record.access_token) || !safeString(record.refresh_token) || !Number.isFinite(record.access_expires_at)) throw new GatewayError('invalid_response');
+}
+function loginFailure(error) {
+  if (error?.status === 401) return new Error('Gateway refused authorization. No new credentials were saved. Run campaigns-os login again.');
+  if (error?.code === 'access_denied') return new Error('Connection declined. No new credentials were saved.');
+  if (error?.code === 'expired_token') return new Error('Connection code expired. Run campaigns-os login again.');
+  if (error?.code === 'invalid_request') return new Error('Gateway refused this store or client. Check the network-domain store and gateway availability.');
+  return new Error('Could not complete gateway login. Check gateway availability and retry; no new credentials were saved.');
+}
+export async function runAuthentication(argv, { fetchImpl = globalThis.fetch, credentials = createCredentialStore(), now = Date.now, pause = sleep, output = console.log, interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY), promptStore = askStore } = {}) {
+  const args = authenticationArguments(argv);
+  if (!args.store && !interactive) throw new Error("Use --store <subdomain> for noninteractive login or logout. No network request was made.");
+  const command = args.command;
+  const store = args.store ?? canonicalLoginStore(await promptStore());
+  const binding = bindingFor(store);
+  if (command === 'logout') {
+    let remote = 'no_local_grant', localIssue = false;
+    let cleanup = { local_cleared: false, keychain_item_removed: true };
+    await credentials.transaction(binding, async storage => {
+      try {
+        let record;
+        try { record = storage.read(); if (record) validateStored(record); }
+        catch { localIssue = true; remote = 'not_attempted'; return; }
+        if (!record) return;
+        try {
+          // Include network/clock skew in the decision; never retry a consumed
+          // refresh blindly after an uncertain response.
+          if (!record.refresh_pending && record.access_expires_at <= now() + 60000) {
+            const { rotateLockedCredential } = await import('./admin-transport.mjs');
+            record = await rotateLockedCredential(storage, record, { fetchImpl, now });
+          }
+          // Pending refresh means its outcome is unknown. Try access revocation
+          // once, never replay that refresh, then clear the local selection.
+          const result = await gatewayRequest('/revoke', { fetchImpl, accessToken: record.access_token });
+          if (result.revoked !== true) throw new GatewayError('invalid_response');
+          remote = 'revoked';
+        } catch (error) { remote = error?.status === 401 || error?.httpStatus === 401 ? 'unrecognized' : 'unconfirmed'; }
+      } finally { cleanup = storage.clear(); }
+    });
+    output(localIssue ? 'Local login selection cleared. Local credentials could not be read; remote revocation was not attempted.' : remote === 'revoked' ? 'Logged out. Gateway grant revoked and local login selection cleared.' : remote === 'unrecognized' ? 'Local login selection cleared. Gateway no longer recognizes this grant; remote revocation was not confirmed.' : remote === 'unconfirmed' ? 'Local login selection cleared. Remote revocation was not confirmed because the gateway request failed.' : 'No local login for this store.');
+    if (!cleanup.keychain_item_removed) output('An unselected keychain item could not be deleted. Check the com.nextcommerce.campaigns-os items in Keychain Access.');
+    return { ok: true, store, remote_revocation: remote, ...cleanup };
+  }
+  // Capture existing pair before network activity. Recheck under lock on save
+  // so another process's successful login/refresh/logout cannot be overwritten.
+  const previous = await credentials.read(binding);
+  let record;
+  try {
+    const started = now();
+    const device = await gatewayRequest('/device/authorize', { fetchImpl, form: { client_id: CLIENT_ID, resource: RESOURCE, scope: SCOPE, store } });
+    if (!safeString(device.device_code) || !/^[A-F0-9]{12}$/.test(device.user_code) || device.verification_uri !== GATEWAY + '/device' || !Number.isInteger(device.expires_in) || device.expires_in <= 0 || device.expires_in > 600 || !Number.isInteger(device.interval) || device.interval < 5 || device.interval > 60) throw new GatewayError('invalid_response');
+    output(`Open ${GATEWAY}/device in one browser tab and enter code ${device.user_code}.`);
+    output(`Keep using that browser: if needed, use its Install Campaigns link (${GATEWAY}/install), then sign in to ${store}'s dashboard and launch Campaigns. Match the code and explicitly allow reads. Return here afterward. Never paste a dashboard token into the CLI.`);
+    const deadline = started + device.expires_in * 1000; let interval = device.interval * 1000;
+    for (let attempt = 0; attempt < 120; attempt++) {
+      if (now() + interval >= deadline) throw new GatewayError('expired_token');
+      await pause(interval);
+      const polledAt = now(); if (polledAt >= deadline) throw new GatewayError('expired_token');
+      try {
+        const data = await gatewayRequest('/token', { fetchImpl, timeoutMs: deadline - polledAt, form: { grant_type: DEVICE_GRANT, client_id: CLIENT_ID, resource: RESOURCE, device_code: device.device_code } });
+        // A successful response means the authority issued this grant. Do not
+        // abandon it merely because local time crossed the device deadline.
+        record = credentialFromResponse(data, store, polledAt); break;
+      } catch (error) {
+        if (error.status === 401) throw error;
+        if (error.code === 'authorization_pending') continue;
+        if (error.code === 'slow_down') { interval = Math.min(60000, interval + 5000); continue; }
+        throw error;
+      }
+    }
+    if (!record) throw new GatewayError('expired_token');
+  } catch (error) { throw loginFailure(error); }
+  await credentials.transaction(binding, storage => {
+    const current = storage.read();
+    if (JSON.stringify(current) !== JSON.stringify(previous)) throw new Error('Credential storage changed during login. The existing login was preserved; retry.');
+    storage.write(record);
+  });
+  output(`Logged in for ${store}. Gateway credentials saved to your user credential store.`);
+  return { ok: true, store, access_expires_at: record.access_expires_at };
+}

package/src/package-install-fixture.mjs

@@ -1,7 +1,8 @@
 // Test fixture: a REAL package install of this checkout, staged under a
 // temporary install root, so a test can run the CLI the way a consumer's
-// `npx campaigns-os …` does (install mode detected from the enclosing
-// node_modules, pinned commit read from the lockfile npm would have written).
+// `npx --no-install campaigns-os …` does (install mode detected from the
+// enclosing node_modules, pinned commit read from the lockfile npm would have
+// written).
 // Shared by the tooling-status and page-kit sync suites; not part of the
 // supported surface.
 import { cpSync, mkdirSync, symlinkSync, writeFileSync } from "node:fs";