@limecloud/cli 0.0.0-stage → 0.3.0

package/src/input.mjs

@@ -0,0 +1,91 @@
+import { readFile } from "node:fs/promises";
+import { requestSchema } from "./contract.mjs";
+import { CLIError } from "./protocol.mjs";
+
+const sensitive = new Set(["access_token", "refresh_token", "id_token", "device_code", "client_secret", "code", "code_verifier", "token"]);
+const fail = (message) => { throw new CLIError("invalid_arguments", message); };
+
+export async function readSource(path, limit = 1_048_576) {
+  if (path !== 0) {
+    const bytes = await readFile(path);
+    if (bytes.length > limit) fail("Input exceeds its byte limit");
+    return bytes;
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    const bytes = Buffer.from(chunk); size += bytes.length;
+    if (size > limit) fail("Input exceeds its byte limit");
+    chunks.push(bytes);
+  }
+  return Buffer.concat(chunks);
+}
+
+export async function jsonInput(input, readInput = async (path) => (await readSource(path)).toString("utf8")) {
+  const indirect = input === "-" || input.startsWith("@");
+  const source = indirect ? await readInput(input === "-" ? 0 : input.slice(1)) : input;
+  if (Buffer.byteLength(source) > 1_048_576) fail("JSON input exceeds 1 MiB");
+  let value;
+  try { value = JSON.parse(source); } catch { fail("Invalid JSON input"); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("JSON input must be an object");
+  return { value, indirect };
+}
+
+export async function parametersFor(parsed, env, method, readInput) {
+  const form = new URLSearchParams();
+  function append(name, value, privateInput) {
+    if (!/^[a-z][a-z0-9_]*$/.test(name)) fail("Invalid parameter name");
+    if (["access_token", "client_secret", "id_token"].includes(name)) fail("Use credential environment variables for authentication");
+    if (!privateInput && sensitive.has(name)) fail(`Use --param-env or --data @file for the sensitive field ${name}`);
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (!["string", "number", "boolean"].includes(typeof item)) fail(`Parameter ${name} must be a scalar or array of scalars`);
+      form.append(name, String(item));
+    }
+  }
+  for (const flag of ["params", "data"]) {
+    const input = parsed.get(flag);
+    if (input === undefined) continue;
+    if (flag === "data" && method === "GET") fail("GET accepts --params, not --data");
+    const { value, indirect } = await jsonInput(input, readInput);
+    if (flag === "params" && method !== "GET" && Object.keys(value).length) fail("OAuth POST fields belong in --data, not query --params");
+    for (const [name, item] of Object.entries(value)) append(name, item, indirect);
+  }
+  for (const flag of ["param", "param-env"]) for (const value of parsed.flags.get(flag) ?? []) {
+    const equal = value.indexOf("=");
+    if (equal < 1) fail(`--${flag} requires name=value`);
+    const name = value.slice(0, equal), input = value.slice(equal + 1);
+    if (flag === "param-env") {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(input) || !env[input]) fail(`--param-env ${name} requires a populated environment variable`);
+      append(name, env[input], true);
+    } else append(name, input, false);
+  }
+  return form;
+}
+
+export function validateParameters(contract, operation, form, basic, dryRun = false) {
+  const schema = requestSchema(contract, operation, form);
+  const properties = schema?.properties ?? Object.fromEntries((operation.parameters ?? []).map((p) => [p.name, p.schema]));
+  const required = schema?.required ?? (operation.parameters ?? []).filter((p) => p.required).map((p) => p.name);
+  for (const name of form.keys()) {
+    const property = properties[name];
+    if (!property) fail(`Unknown parameter ${name}; use schema ${operation.command ?? operation.operationId}`);
+    const values = form.getAll(name);
+    if (values.length > 1 && property.type !== "array") fail(`Parameter ${name} must occur once`);
+    for (const value of values) {
+      if (property.const !== undefined && value !== property.const || property.enum && !property.enum.includes(value) ||
+          property.minLength !== undefined && value.length < property.minLength ||
+          property.maxLength !== undefined && value.length > property.maxLength) fail(`Invalid value for ${name}`);
+    }
+    if (operation.method === "GET" && sensitive.has(name)) fail("Credential parameters cannot be sent in URLs");
+  }
+  for (const name of required) if (!form.get(name)) fail(`Required parameter: ${name}`);
+  if (!dryRun && !basic && ["/oauth/token", "/oauth/device/authorization", "/oauth/revoke"].includes(operation.path) && !form.get("client_id")) {
+    fail("Set --client-id or LIMECLOUD_CLIENT_ID for this public-client request");
+  }
+}
+
+export function scopeList(value) {
+  const scopes = value.trim().split(/[\s,]+/).filter(Boolean);
+  if (!scopes.length || scopes.some((scope) => !/^[A-Za-z0-9_:.\/-]{1,100}$/.test(scope)) || new Set(scopes).size !== scopes.length) fail("Provide a non-empty list of unique scopes");
+  return scopes;
+}

package/src/management.mjs

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { resolveSchema } from "./contract.mjs";
+import { jsonInput, readSource } from "./input.mjs";
+import { CLIError } from "./protocol.mjs";
+
+export const flagName = (field) => field.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").replaceAll("_", "-").toLowerCase();
+const fail = (message) => { throw new CLIError("invalid_arguments", message); };
+const sensitive = new Set(["password", "secret", "client_secret", "signing_key", "access_token", "refresh_token", "id_token", "device_code", "code_verifier", "token", "totp_secret", "recovery_codes"]);
+
+function noInlineSecrets(value) {
+  if (!value || typeof value !== "object") return;
+  for (const [key, item] of Object.entries(value)) {
+    if (sensitive.has(key) && item != null && item !== "") fail("Sensitive JSON fields require --data @file, stdin, or --param-env");
+    noInlineSecrets(item);
+  }
+}
+
+export function validateJSON(contract, input, value, label = "data", depth = 0) {
+  if (!input || depth > 32) return;
+  const schema = resolveSchema(contract, input);
+  for (const kind of ["oneOf", "anyOf"]) if (schema[kind]) {
+    const accepted = schema[kind].filter((variant) => { try { validateJSON(contract, variant, value, label, depth + 1); return true; } catch { return false; } });
+    if (!accepted.length || kind === "oneOf" && accepted.length !== 1) fail(`${label} does not match its public schema`);
+    return;
+  }
+  for (const variant of schema.allOf ?? []) validateJSON(contract, variant, value, label, depth + 1);
+  if (schema.const !== undefined && value !== schema.const || schema.enum && !schema.enum.includes(value)) fail(`${label} has an unsupported value`);
+  const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+  if (types.length && !types.some((type) => type === "null" ? value === null : type === "array" ? Array.isArray(value) : type === "object" ? value && typeof value === "object" && !Array.isArray(value) :
+    type === "integer" ? Number.isInteger(value) : type === "number" ? typeof value === "number" && Number.isFinite(value) : typeof value === type)) fail(`${label} has the wrong type`);
+  if (typeof value === "string" && (schema.minLength !== undefined && value.length < schema.minLength || schema.maxLength !== undefined && value.length > schema.maxLength || schema.pattern && !new RegExp(schema.pattern).test(value))) fail(`${label} has an invalid string value`);
+  if (typeof value === "number" && (schema.minimum !== undefined && value < schema.minimum || schema.maximum !== undefined && value > schema.maximum)) fail(`${label} is outside the allowed range`);
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems || schema.maxItems !== undefined && value.length > schema.maxItems) fail(`${label} has an invalid number of items`);
+    value.forEach((item, index) => validateJSON(contract, schema.items, item, `${label}[${index}]`, depth + 1));
+  } else if (value && typeof value === "object") {
+    for (const required of schema.required ?? []) if (!Object.hasOwn(value, required)) fail(`${label}.${required} is required`);
+    for (const [name, item] of Object.entries(value)) {
+      if (schema.additionalProperties === false && !Object.hasOwn(schema.properties ?? {}, name)) fail(`${label}.${name} is not a declared field`);
+      validateJSON(contract, schema.properties?.[name], item, `${label}.${name}`, depth + 1);
+    }
+  }
+}
+
+export function matchHTTP(catalogue, method, path) {
+  if (!path?.startsWith("/") || path.startsWith("//") || /[?#\\\x00-\x1f]/.test(path)) return null;
+  for (const operation of catalogue.filter((item) => item.method === method)) {
+    const pattern = operation.path.split("/"), actual = path.split("/");
+    if (pattern.length !== actual.length) continue;
+    const bindings = {};
+    let matches = true;
+    for (let index = 0; index < pattern.length; index++) {
+      const name = pattern[index].match(/^\{([^}]+)\}$/)?.[1];
+      if (!name && pattern[index] !== actual[index]) { matches = false; break; }
+      if (name) {
+        try { bindings[name] = decodeURIComponent(actual[index]); } catch { matches = false; break; }
+        if (!bindings[name] || /[/\\?#\x00-\x1f]/.test(bindings[name])) { matches = false; break; }
+      }
+    }
+    if (matches) return { operation, bindings };
+  }
+  return null;
+}
+
+function cast(raw, schema) {
+  if (schema?.type === "integer" || schema?.type === "number") {
+    if (String(raw).trim() === "" || !Number.isFinite(Number(raw))) fail("Expected a numeric parameter");
+    return Number(raw);
+  }
+  if (schema?.type === "boolean") {
+    if (raw !== "true" && raw !== "false" && typeof raw !== "boolean") fail("Expected true or false");
+    return raw === true || raw === "true";
+  }
+  if (["object", "array"].includes(schema?.type) && typeof raw === "string") {
+    try { return JSON.parse(raw); } catch { fail("Structured typed fields require a JSON value"); }
+  }
+  return raw;
+}
+
+export async function prepareManagement(contract, operation, parsed, env, readInput, rawBindings = {}, readBinary = readSource) {
+  const declarations = operation.parameters ?? [];
+  const inputSchema = resolveSchema(contract, operation.requestBody?.content?.["application/json"]?.schema);
+  const values = {}, body = {};
+  let bodyProvided = false;
+  const binaryType = Object.keys(operation.requestBody?.content ?? {}).find((type) => type === "image/png");
+  let binaryBody;
+  if (parsed.get("file")) {
+    if (!binaryType) fail("This public method does not accept --file");
+    if (parsed.get("data")) fail("Use --file alone for a binary request body");
+    binaryBody = Buffer.from(await readBinary(parsed.get("file") === "-" ? 0 : parsed.get("file"), 320 << 10));
+    if (binaryBody.length > 320 << 10 || binaryBody.length < 33 || !binaryBody.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ||
+        binaryBody.toString("ascii", 12, 16) !== "IHDR" || binaryBody.readUInt32BE(16) !== 256 || binaryBody.readUInt32BE(20) !== 256) fail("Choose a cropped 256 by 256 PNG no larger than 320 KiB");
+    bodyProvided = true;
+  }
+  if (parsed.get("params")) {
+    const { value, indirect } = await jsonInput(parsed.get("params"), readInput);
+    if (!indirect) noInlineSecrets(value);
+    Object.assign(values, value);
+  }
+  if (parsed.get("data")) {
+    if (!inputSchema) fail("This public method does not accept --data");
+    const input = await jsonInput(parsed.get("data"), readInput);
+    if (!input.indirect) noInlineSecrets(input.value);
+    Object.assign(body, input.value); bodyProvided = true;
+  }
+  const declaration = (name) => declarations.find((item) => item.name === name || item.in === "header" && item.name.toLowerCase() === name.toLowerCase());
+  function apply(name, raw, privateInput) {
+    if (!privateInput && sensitive.has(name)) fail("Sensitive fields require --param-env or private JSON input");
+    const parameter = declaration(name);
+    const property = inputSchema?.properties?.[name];
+    if (!parameter && !property) fail(`Unknown parameter ${name}`);
+    if (parameter) values[parameter.name] = cast(raw, parameter.schema);
+    else { body[name] = cast(raw, resolveSchema(contract, property)); bodyProvided = true; }
+  }
+  for (const kind of ["param", "param-env", "header"]) for (const pair of parsed.flags.get(kind) ?? []) {
+    const index = pair.indexOf("=");
+    if (index < 1) fail(`--${kind} requires name=value`);
+    const name = pair.slice(0, index), raw = pair.slice(index + 1);
+    if (kind === "header" && !declarations.some((item) => item.in === "header" && item.name.toLowerCase() === name.toLowerCase())) fail("Only contract-declared HTTP headers can be set");
+    if (kind === "param-env") {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(raw) || !env[raw]) fail(`--param-env ${name} needs a populated environment variable`);
+      apply(name, env[raw], true);
+    } else apply(name, raw, false);
+  }
+  for (const name of [...declarations.map((item) => item.name), ...Object.keys(inputSchema?.properties ?? {})]) {
+    if (parsed.get(flagName(name)) !== undefined) {
+      const field = declaration(name)?.schema ?? resolveSchema(contract, inputSchema.properties[name]);
+      const items = parsed.flags.get(flagName(name));
+      apply(name, field?.type === "array" && items.length > 1 ? items : items[0], false);
+    }
+  }
+  for (const key of Object.keys(values)) if (!declaration(key)) fail(`Unknown path/query/header parameter ${key}`);
+  const query = new URLSearchParams(), headers = {}, bindings = { ...rawBindings };
+  for (const parameter of declarations) {
+    let value = values[parameter.name];
+    if (parameter.in === "path" && rawBindings[parameter.name] !== undefined) {
+      if (value !== undefined && String(value) !== rawBindings[parameter.name]) fail(`Path parameter ${parameter.name} conflicts with the raw HTTP path`);
+      value = rawBindings[parameter.name];
+    }
+    if (value === undefined) { if (parameter.required) fail(`Required ${parameter.in} parameter: ${parameter.name}`); continue; }
+    value = cast(value, parameter.schema);
+    validateJSON(contract, parameter.schema, value, parameter.name);
+    if (parameter.in === "path") {
+      if (typeof value !== "string" || !value || value === "." || value === ".." || /[/\\?#\x00-\x1f]/.test(value)) fail(`Invalid path parameter ${parameter.name}`);
+      bindings[parameter.name] = value;
+    } else if (parameter.in === "header") {
+      if (["authorization", "cookie", "host", "content-type"].includes(parameter.name.toLowerCase()) || /[\r\n\0]/.test(String(value))) fail("Unsafe or reserved request header");
+      headers[parameter.name] = String(value);
+    } else if (parameter.in === "query") for (const item of Array.isArray(value) ? value : [value]) query.append(parameter.name, String(item));
+  }
+  const path = operation.path.replace(/\{([^}]+)\}/g, (_match, key) => {
+    if (bindings[key] === undefined) fail(`Required path parameter: ${key}`);
+    return encodeURIComponent(bindings[key]);
+  });
+  if (operation.requestBody?.required && !bodyProvided) fail(binaryType ? "This public method requires --file PNG_PATH (or --file - for stdin)" : "This public method requires --data JSON");
+  if (bodyProvided && !binaryBody) validateJSON(contract, inputSchema, body);
+  return { path, query, extraHeaders: headers, ...(binaryBody ? { binaryBody, binaryType,
+    binarySummary: { media_type: binaryType, bytes: binaryBody.length, width: 256, height: 256, sha256: createHash("sha256").update(binaryBody).digest("hex") } } :
+    bodyProvided ? { jsonBody: body } : {}) };
+}

package/src/output.mjs

@@ -0,0 +1,55 @@
+import { CLIError, redact } from "./protocol.mjs";
+
+export const formats = ["json", "ndjson", "table", "csv"];
+
+export function outputOptions(parsed) {
+  const format = parsed.get("json") ? "json" : parsed.get("format") ?? "json";
+  if (!formats.includes(format)) throw new CLIError("invalid_arguments", "--format must be json, ndjson, table or csv");
+  if (parsed.get("json") && parsed.get("format") && parsed.get("format") !== "json") throw new CLIError("invalid_arguments", "--json conflicts with --format");
+  const fields = parsed.get("fields")?.split(",").map((value) => value.trim());
+  if (fields?.some((value) => !/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(value) || value.split(".").some((part) => ["__proto__", "prototype", "constructor"].includes(part)))) {
+    throw new CLIError("invalid_arguments", "--fields must be comma-separated field paths");
+  }
+  return { format, fields };
+}
+
+function select(value, fields) {
+  if (!fields) return value;
+  if (Array.isArray(value)) return value.map((row) => select(row, fields));
+  return Object.fromEntries(fields.map((field) => [field, field.split(".").reduce((current, key) =>
+    current && typeof current === "object" && Object.hasOwn(current, key) ? current[key] : null, value)]));
+}
+
+function text(value) {
+  const result = value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+  return result.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
+}
+
+export function success(io, value, { format = "json", fields, identity = "public", raw = false, meta = {} } = {}) {
+  const data = select(raw ? value : redact(value), fields);
+  const rows = (Array.isArray(data) ? data : [data]).map((row) => row && typeof row === "object" && !Array.isArray(row) ? row : { value: row });
+  if (format === "json") {
+    io.stdout.write(`${JSON.stringify({ ok: true, identity, data, meta: { ...meta, ...(Array.isArray(data) ? { count: data.length } : {}) } }, null, 2)}\n`);
+  } else if (format === "ndjson") {
+    for (const row of rows) io.stdout.write(`${JSON.stringify({ ok: true, identity, data: row })}\n`);
+  } else {
+    const keys = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+    if (format === "csv") {
+      const quote = (item) => `"${String(item ?? "").replaceAll('"', '""')}"`;
+      io.stdout.write(`${[keys, ...rows.map((row) => keys.map((key) => typeof row[key] === "object" && row[key] !== null ? JSON.stringify(row[key]) : row[key]))].map((row) => row.map(quote).join(",")).join("\n")}\n`);
+    } else {
+      const cells = [keys, ...rows.map((row) => keys.map((key) => text(row[key])))];
+      const widths = keys.map((_key, index) => Math.min(80, Math.max(...cells.map((row) => row[index].length))));
+      io.stdout.write(`${cells.map((row) => row.map((cell, index) => text(cell).slice(0, widths[index]).padEnd(widths[index])).join("  ").trimEnd()).join("\n")}\n`);
+    }
+  }
+}
+
+export function errorEnvelope(error, cancelled) {
+  const known = error instanceof CLIError;
+  const code = cancelled ? "cancelled" : known ? error.code : "cli_error";
+  const type = error?.status ? "api" : ["login_required", "token_expired", "missing_scopes"].includes(code) ? "auth" :
+    code === "request_failed" ? "transport" : code === "invalid_arguments" || code === "invalid_issuer" ? "validation" : "cli";
+  return { ok: false, error: { type, ...(type === "validation" ? { subtype: "invalid_argument" } : {}), code, message: cancelled ? "Command cancelled" : known ? error.message : "Command failed; check local configuration and retry",
+    ...(known && error.status ? { status: error.status } : {}), ...(known && error.retryAfter ? { retry_after: error.retryAfter } : {}) } };
+}

package/src/protocol.mjs

@@ -0,0 +1,147 @@
+export class CLIError extends Error {
+  constructor(code, message, status, retryAfter) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+}
+
+export function issuerOrigin(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new CLIError("invalid_issuer", "Issuer must be an absolute HTTPS origin"); }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) || url.username || url.password ||
+      url.pathname !== "/" || url.search || url.hash) {
+    throw new CLIError("invalid_issuer", "Issuer must be an HTTPS origin; HTTP is allowed only on loopback");
+  }
+  return url.origin;
+}
+
+export function verificationURI(value, issuer) {
+  let url;
+  try { url = new URL(value); } catch { throw new CLIError("invalid_response", "Invalid device verification URI"); }
+  if (url.origin !== issuer || url.username || url.password || url.pathname !== "/auth/device") {
+    throw new CLIError("invalid_response", "Device verification URI does not match this issuer");
+  }
+  return url.href;
+}
+
+const secretKeys = new Set(["access_token", "refresh_token", "id_token", "device_code", "client_secret", "secret", "password", "signing_key", "totp_secret", "recovery_codes", "code", "code_verifier", "token"]);
+export function redact(value) {
+  if (Array.isArray(value)) return value.map(redact);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, secretKeys.has(key) ? "[REDACTED]" : redact(item)]));
+}
+
+export async function protocolRequest({ issuer, origin = issuer, path, method = "GET", parameters, query, jsonBody, binaryBody, binaryType, extraHeaders = {}, accessToken, clientID, clientSecret, fetcher = fetch, signal }) {
+  const targetOrigin = issuerOrigin(origin);
+  const url = new URL(path, targetOrigin);
+  if (url.origin !== targetOrigin || !path.startsWith("/") || path.startsWith("//") || url.pathname !== path || url.hash || url.search) {
+    throw new CLIError("invalid_endpoint", "Endpoint must be a contract path on this issuer");
+  }
+  const headers = { ...extraHeaders, Accept: "application/json" };
+  const form = new URLSearchParams(parameters);
+  if (clientSecret) {
+    if (!clientID) throw new CLIError("client_id_required", "Set LIMECLOUD_CLIENT_ID with LIMECLOUD_CLIENT_SECRET");
+    // OAuth Basic credentials use form encoding before Base64 encoding.
+    const encode = (value) => new URLSearchParams({ v: value }).toString().slice(2);
+    headers.Authorization = `Basic ${Buffer.from(`${encode(clientID)}:${encode(clientSecret)}`).toString("base64")}`;
+    form.delete("client_id");
+  } else if (accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  const management = path.startsWith("/api/v1/");
+  if (management) {
+    url.search = new URLSearchParams(query).toString();
+    if (binaryBody !== undefined) headers["Content-Type"] = binaryType;
+    else if (jsonBody !== undefined) headers["Content-Type"] = "application/json";
+  } else if (method === "GET") url.search = form.toString();
+  else headers["Content-Type"] = "application/x-www-form-urlencoded";
+  let response;
+  try {
+    response = await fetcher(url, {
+      method, headers, body: management ? binaryBody ?? (jsonBody === undefined ? undefined : JSON.stringify(jsonBody)) : method === "GET" ? undefined : form,
+      redirect: "manual", signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+    });
+  } catch {
+    throw new CLIError("request_failed", "Request failed or timed out; a token exchange may have completed. Do not replay an uncertain token exchange");
+  }
+  if (response.status >= 300 && response.status < 400) {
+    throw new CLIError("redirect_refused", "Endpoint returned a redirect; no follow-up request was sent", response.status);
+  }
+  let data;
+  const body = await response.text();
+  if (!body) data = null;
+  else {
+    try { data = JSON.parse(body); } catch {
+      throw new CLIError("invalid_response", "Endpoint returned a non-JSON response", response.status);
+    }
+  }
+  if (!response.ok) {
+    const errorCode = typeof data?.error === "string" ? data.error : data?.error?.code;
+    const code = typeof errorCode === "string" && /^[A-Za-z0-9_.:-]{1,80}$/.test(errorCode) ? errorCode : "http_error";
+    // Do not echo error descriptions: a server may include submitted secrets in them.
+    const retry = Number(response.headers.get("Retry-After"));
+    throw new CLIError(code, `API request failed: ${code} (HTTP ${response.status})`, response.status,
+      Number.isFinite(retry) && retry > 0 ? retry : undefined);
+  }
+  return data;
+}
+
+export function tokenRecord(tokens, context, now = Date.now()) {
+  if (!tokens || typeof tokens.access_token !== "string" || !tokens.access_token ||
+      !/^bearer$/i.test(tokens.token_type) || !Number.isFinite(tokens.expires_in) || tokens.expires_in <= 0 || tokens.expires_in > 31_536_000 ||
+      (tokens.scope !== undefined && typeof tokens.scope !== "string") ||
+      (tokens.refresh_token !== undefined && (typeof tokens.refresh_token !== "string" || !tokens.refresh_token))) {
+    throw new CLIError("invalid_response", "Invalid OAuth token response; start a new login");
+  }
+  return { issuer: context.issuer, ...(context.apiOrigin ? { api_origin: context.apiOrigin } : {}), client_id: context.clientID, access_token: tokens.access_token,
+    refresh_token: tokens.refresh_token, scope: tokens.scope ?? "", expires_at: new Date(now + tokens.expires_in * 1000).toISOString() };
+}
+
+export async function startDevice({ context, request = protocolRequest, now = Date.now, parameters = new URLSearchParams() }) {
+  const input = new URLSearchParams(parameters);
+  input.set("client_id", context.clientID);
+  const device = await request({ ...context, path: "/oauth/device/authorization", method: "POST", parameters: input });
+  if (!device || typeof device.device_code !== "string" || !device.device_code || typeof device.user_code !== "string" ||
+      !/^[A-Z2-7]{4}-[A-Z2-7]{4}$/.test(device.user_code) || !Number.isInteger(device.interval) || device.interval <= 0 ||
+      !Number.isInteger(device.expires_in) || device.expires_in <= 0 || device.expires_in > 3600) {
+    throw new CLIError("invalid_response", "Invalid device authorization response");
+  }
+  return { issuer: context.issuer, ...(context.apiOrigin ? { api_origin: context.apiOrigin } : {}), client_id: context.clientID, device_code: device.device_code, user_code: device.user_code,
+    verification_uri: verificationURI(device.verification_uri_complete ?? device.verification_uri, context.issuer),
+    expires_at: new Date(now() + device.expires_in * 1000).toISOString(), interval: device.interval, next_poll_at: now() + device.interval * 1000 };
+}
+
+export async function pollDevice({ pending, request = protocolRequest, wait, now = Date.now, persist = async () => {} }) {
+  if (pending.exchange_pending) throw new CLIError("login_required", "The previous device token exchange has an unknown result; start a new auth login");
+  const deadline = Date.parse(pending.expires_at);
+  const context = { issuer: pending.issuer, apiOrigin: pending.api_origin, clientID: pending.client_id };
+  if (!Number.isFinite(deadline) || !Number.isFinite(pending.next_poll_at) || !Number.isInteger(pending.interval) || pending.interval <= 0 ||
+      typeof pending.device_code !== "string" || !pending.device_code || !context.clientID) throw new CLIError("invalid_credentials", "Invalid pending device authorization");
+  const state = { ...pending };
+  const form = new URLSearchParams({ client_id: context.clientID, grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: state.device_code });
+  while (now() < deadline) {
+    if (state.next_poll_at >= deadline) break;
+    await wait(Math.max(0, state.next_poll_at - now()));
+    if (now() >= deadline) break;
+    state.exchange_pending = true;
+    await persist(state);
+    try {
+      const tokens = await request({ ...context, path: "/oauth/token", method: "POST", parameters: form });
+      return tokenRecord(tokens, context, now());
+    } catch (error) {
+      if (error.code === "slow_down") state.interval += 5;
+      else if (error.code !== "authorization_pending") throw error;
+      state.exchange_pending = false;
+      state.next_poll_at = now() + state.interval * 1000;
+      await persist(state);
+    }
+  }
+  throw new CLIError("expired_token", "Device authorization expired; start auth login again");
+}
+
+export async function deviceLogin({ context, request = protocolRequest, notify, wait, now = Date.now, parameters = new URLSearchParams() }) {
+  const pending = await startDevice({ context, request, now, parameters });
+  notify({ verification_uri: pending.verification_uri, user_code: pending.user_code, expires_in: Math.ceil((Date.parse(pending.expires_at) - now()) / 1000) });
+  return pollDevice({ pending, request, wait, now });
+}

package/src/storage.mjs

@@ -0,0 +1,95 @@
+import { constants } from "node:fs";
+import { mkdir, open, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { CLIError, issuerOrigin } from "./protocol.mjs";
+import { scopeList } from "./input.mjs";
+
+export function credentialsPath(env = process.env) {
+  return env.LIMECLOUD_CONFIG || join(homedir(), ".config", "limecloud", "credentials.json");
+}
+export function settingsPath(env = process.env) {
+  return env.LIMECLOUD_SETTINGS || join(dirname(credentialsPath(env)), "config.json");
+}
+
+function checkPrivate(stat) {
+  if (!stat.isFile() || (process.platform !== "win32" && ((stat.mode & 0o077) || stat.uid !== process.getuid()))) {
+    throw new CLIError("unsafe_credentials", "Local configuration must be a regular file owned by this user with mode 0600");
+  }
+}
+
+export class PrivateJSONStore {
+  constructor(path) { this.path = path; }
+  async read() {
+    let file;
+    try {
+      file = await open(this.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+      checkPrivate(await file.stat());
+      const data = JSON.parse(await file.readFile("utf8"));
+      if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error("Invalid record");
+      return data;
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      if (error instanceof CLIError) throw error;
+      throw new CLIError("invalid_credentials", "Unable to read private local configuration; check the file or select another path");
+    } finally { await file?.close(); }
+  }
+  async write(record) {
+    await this.read();
+    const temp = `${this.path}.${randomUUID()}.new`;
+    const file = await open(temp, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    try { await file.writeFile(`${JSON.stringify(record)}\n`); await file.sync(); }
+    finally { await file.close(); }
+    await rename(temp, this.path);
+  }
+  async withLock(callback) {
+    await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+    const lockPath = `${this.path}.lock`;
+    let lock;
+    try { lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600); }
+    catch (error) {
+      if (error.code === "EEXIST") throw new CLIError("credentials_busy", "Another command holds this configuration lock; finish it before retrying");
+      throw error;
+    }
+    try { await lock.writeFile(`${process.pid}\n`); return await callback(); }
+    finally { await lock.close(); await unlink(lockPath); }
+  }
+}
+
+export class CredentialStore extends PrivateJSONStore {
+  async read() {
+    const data = await super.read();
+    if (!data?.access_token) return null;
+    issuerOrigin(data.issuer);
+    if (data.api_origin !== undefined) issuerOrigin(data.api_origin);
+    if (typeof data.client_id !== "string" || !data.client_id || typeof data.access_token !== "string" ||
+        !Number.isFinite(Date.parse(data.expires_at)) ||
+        (data.refresh_token !== undefined && typeof data.refresh_token !== "string")) {
+      throw new CLIError("invalid_credentials", "Invalid saved credentials; use a separate LIMECLOUD_CONFIG and sign in again");
+    }
+    return data;
+  }
+}
+
+export function validateSettings(value) {
+  if (Object.keys(value).some((key) => !["issuer", "api_origin", "client_id", "scope"].includes(key))) throw new CLIError("invalid_arguments", "Supported config keys: issuer, api_origin, client_id, scope");
+  const result = {};
+  if (value.issuer !== undefined) result.issuer = issuerOrigin(value.issuer);
+  if (value.api_origin !== undefined) result.api_origin = issuerOrigin(value.api_origin);
+  if (value.client_id !== undefined) {
+    if (typeof value.client_id !== "string" || !value.client_id || value.client_id.length > 200 || /[\x00-\x20\x7f]/.test(value.client_id)) {
+      throw new CLIError("invalid_arguments", "client_id must be a registered public client ID");
+    }
+    result.client_id = value.client_id;
+  }
+  if (value.scope !== undefined) {
+    if (typeof value.scope !== "string") throw new CLIError("invalid_arguments", "scope must be a space-separated string");
+    result.scope = scopeList(value.scope).join(" ");
+  }
+  return result;
+}
+
+export class SettingsStore extends PrivateJSONStore {
+  async read() { const value = await super.read(); return value ? validateSettings(value) : {}; }
+}