@nomac/cli 0.2.4 → 0.3.0-beta.1

package/src/store-upload.mjs

@@ -0,0 +1,127 @@
+// Shared by the hosted upload endpoint and the published CLI (copied by the
+// schema generator). Provider upload URLs come only from an authenticated,
+// app-scoped read_store response; Nomac credentials never go to those URLs.
+import { createHash, randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { Readable } from 'node:stream';
+
+function unwrap(schema, components) {
+  if (schema?.$ref) return unwrap(components.schemas[schema.$ref.split('/').at(-1)], components);
+  if (schema?.anyOf) return unwrap(schema.anyOf.find(s => s.type !== 'null'), components);
+  return schema;
+}
+function fields(detail) {
+  const root = unwrap(detail.operation.body, detail.operation.components);
+  return unwrap(unwrap(root.properties.data, detail.operation.components).properties.attributes, detail.operation.components)?.properties ?? {};
+}
+const digest = (name, bytes) => createHash(name).update(bytes).digest('hex');
+
+export async function uploadStoreAsset(args, call) {
+  const requestKey = args.request_key ?? `store-upload-${randomUUID()}`;
+  let handle, current, source, md5, sha256, size, filename, reservation;
+  let stage = 'prepare';
+  try {
+    if (Boolean(args.file_path) === Boolean(args.data_base64)) throw new Error('Supply exactly one local file_path (CLI) or data_base64 (hosted).');
+    if (!args.operation?.endsWith('_createInstance')) throw new Error('Choose an asset createInstance operation from get_store_capabilities.');
+    if (args.file_path) {
+      handle = await open(args.file_path, 'r');
+      current = await handle.stat({ bigint: true });
+      if (!current.isFile() || current.size < 1n || current.size > 500n * 1024n * 1024n) throw new Error('Upload a regular file between 1 byte and 500 MiB. Apple may impose a smaller asset-specific limit.');
+      size = Number(current.size); filename = basename(args.file_path);
+      const range = async function* (offset, length) {
+        for (let position = offset; position < offset + length;) {
+          const buffer = Buffer.allocUnsafe(Math.min(1024 * 1024, offset + length - position));
+          const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+          if (!bytesRead) throw new Error('The source file was truncated during upload.');
+          position += bytesRead;
+          yield buffer.subarray(0, bytesRead);
+        }
+      };
+      const sha = createHash('sha256'), checksum = createHash('md5');
+      for await (const bytes of range(0, size)) { sha.update(bytes); checksum.update(bytes); }
+      sha256 = sha.digest('hex'); md5 = checksum.digest('hex');
+      source = async (offset, length) => {
+        const latest = await handle.stat({ bigint: true });
+        if (['size', 'mtimeNs', 'ctimeNs', 'ino'].some(k => latest[k] !== current[k])) throw new Error('The source file changed. Resume with the original bytes or start a new upload.');
+        return Readable.from(range(offset, length));
+      };
+    } else {
+      if (typeof args.data_base64 !== 'string' || args.data_base64.length > 3 * 1024 * 1024 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(args.data_base64)) throw new Error('Provide canonical base64 for a file up to 2 MiB; use the CLI for larger files.');
+      const bytes = Buffer.from(args.data_base64, 'base64');
+      size = bytes.length;
+      if (!size || size > 2 * 1024 * 1024) throw new Error('Hosted inline uploads support files between 1 byte and 2 MiB. Use the CLI for larger files.');
+      md5 = digest('md5', bytes); sha256 = digest('sha256', bytes); filename = 'asset.bin';
+      source = async (offset, length) => bytes.subarray(offset, offset + length);
+    }
+    const detail = await call('GET', `/api/v1/store-capabilities?operation=${encodeURIComponent(args.operation)}`);
+    const createFields = fields(detail);
+    if (!createFields.fileName || !createFields.fileSize) throw new Error('This operation does not create an uploadable Apple file.');
+    const commitOperation = args.operation.replace(/_createInstance$/, '_updateInstance');
+    const commitDetail = await call('GET', `/api/v1/store-capabilities?operation=${encodeURIComponent(commitOperation)}`);
+    const commitFields = fields(commitDetail);
+    if (!commitFields.uploaded) throw new Error('This asset does not support the standard Apple upload commit operation.');
+    const body = structuredClone(args.body ?? {});
+    if (!body.data || !body.data.relationships) throw new Error('Supply the asset JSON:API body and its parent relationship from get_store_capabilities.');
+    body.data.attributes ??= {};
+    if (body.data.attributes.fileSize !== undefined && body.data.attributes.fileSize !== size) throw new Error('The declared fileSize does not match the source file.');
+    filename = basename(body.data.attributes.fileName || filename).normalize('NFC').replace(/[\r\n]/g, '_');
+    const tag = digest('sha256', `${args.project_id}\n${requestKey}\n${args.operation}\n${sha256}`).slice(0, 32);
+    body.data.attributes.fileName = `nomac-${tag}-${filename}`;
+    body.data.attributes.fileSize = size;
+    const base = `/api/v1/projects/${encodeURIComponent(args.project_id)}/store`;
+    const write = (payload, key) => call('POST', `${base}/write`, { body: payload, idempotencyKey: key });
+    stage = 'reserve';
+    reservation = await write({ operation: args.operation, scope: args.scope, references: args.references, body, ...(args.confirm ? { asset_sha256: sha256 } : {}), confirm: Boolean(args.confirm) }, args.confirm ? requestKey : `${requestKey}:preview`);
+    if (!args.confirm || reservation.state === 'pending') return { ...reservation, request_key: requestKey, stage: 'reserve', file_size: size, sha256 };
+    if (!reservation.resource?.id || !reservation.scope) throw new Error('Apple has not returned an app-owned file reservation. Resume this request key; do not create another file.');
+    const read = async () => call('POST', `${base}/read`, { body: { operation: args.operation.replace(/_createInstance$/, '_getInstance'), scope: reservation.scope } });
+    let state = await read();
+    let attributes = state.data?.attributes;
+    if (!attributes || attributes.fileSize !== size || attributes.fileName !== body.data.attributes.fileName) throw new Error('The reserved Apple file does not match this upload.');
+    stage = 'upload';
+    const completed = ['UPLOAD_COMPLETE', 'COMPLETE', 'FAILED'].includes(attributes.assetDeliveryState?.state);
+    if (!completed) {
+      const operations = attributes.uploadOperations;
+      if (!Array.isArray(operations) || !operations.length) throw new Error('Apple has not exposed upload operations yet. Retry this same upload.');
+      let end = 0;
+      for (const op of [...operations].sort((a, b) => a.offset - b.offset)) {
+        if (op.method !== 'PUT' || !Number.isSafeInteger(op.offset) || !Number.isSafeInteger(op.length) || op.length < 1 || op.offset !== end || op.offset + op.length > size) throw new Error('Apple returned invalid or incomplete upload byte ranges.');
+        const url = new URL(op.url);
+        if (url.protocol !== 'https:' || url.username || url.password || !['apple.com', 'icloud.com', 'mzstatic.com', 'amazonaws.com'].some(domain => url.hostname === domain || url.hostname.endsWith(`.${domain}`))) throw new Error('Apple returned an unexpected upload destination.');
+        end += op.length;
+      }
+      if (end !== size) throw new Error('Apple upload operations do not cover the complete source file.');
+      for (const op of operations) {
+        const headers = new Headers();
+        for (const header of op.requestHeaders ?? []) {
+          if (typeof header.name !== 'string' || typeof header.value !== 'string') throw new Error('Apple returned invalid upload headers.');
+          headers.set(header.name, header.value);
+        }
+        if (headers.has('content-length') && headers.get('content-length') !== String(op.length)) throw new Error('Apple returned a Content-Length that does not match the upload byte range.');
+        // A Readable body otherwise uses chunked transfer encoding, which
+        // Apple's fixed-length upload destinations may reject.
+        headers.set('content-length', String(op.length));
+        const part = await source(op.offset, op.length);
+        try {
+          const response = await fetch(op.url, { method: 'PUT', headers, body: part, duplex: 'half', redirect: 'error', signal: AbortSignal.timeout(120_000) });
+          if (!response.ok) throw new Error(`Apple asset upload returned HTTP ${response.status}. Retry with this same request key to refresh its upload URLs.`);
+          await response.body?.cancel();
+        } finally { if (typeof part.destroy === 'function') part.destroy(); }
+      }
+    }
+    if (handle) {
+      const latest = await handle.stat({ bigint: true });
+      if (['size', 'mtimeNs', 'ctimeNs', 'ino'].some(k => latest[k] !== current[k])) throw new Error('The source file changed during upload; it was not committed.');
+    }
+    stage = 'commit';
+    const committed = await write({ operation: commitOperation, scope: reservation.scope, body: { data: { type: reservation.resource.type, id: reservation.resource.id, attributes: { uploaded: true, ...(commitFields.sourceFileChecksum ? { sourceFileChecksum: md5 } : {}) } } }, confirm: true }, `${requestKey}:commit`);
+    if (committed.state === 'pending') return { ...committed, request_key: requestKey, commit_request_key: `${requestKey}:commit`, stage, resource: reservation.resource, scope: reservation.scope };
+    stage = 'processing';
+    state = await read(); attributes = state.data?.attributes;
+    const deliveryState = attributes?.assetDeliveryState?.state;
+    return { request_key: requestKey, resource: reservation.resource, scope: reservation.scope, file_size: size, sha256, uploaded: true, ready: deliveryState === 'COMPLETE', state: deliveryState === 'COMPLETE' ? 'complete' : deliveryState === 'FAILED' ? 'failed' : 'processing', asset_delivery_state: attributes?.assetDeliveryState, next_steps: 'Poll read_store with this scope until assetDeliveryState is COMPLETE. A committed upload may still be processing or rejected by Apple. This uploaded a new file; existing assets were not replaced.' };
+  } catch (error) {
+    return { state: reservation?.resource ? 'needs_attention' : 'failed', stage, request_key: requestKey, ...(reservation?.resource ? { resource: reservation.resource, scope: reservation.scope } : {}), error: { code: error.code ?? 'store_upload_failed', message: error.friendly ?? error.message }, next_steps: 'Keep the original file and request_key to resume. Completed reservation/commit requests are replayed; upload PUTs may repeat the identical byte ranges. Do not start another reservation for an unconfirmed request.' };
+  } finally { await handle?.close(); }
+}

package/src/transport-command.mjs

@@ -0,0 +1,91 @@
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync, statSync, writeFileSync, linkSync, unlinkSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { CliError } from "./api.mjs";
+import { macRequest, sessionId } from "./mac-transport.mjs";
+
+const HELP = `Nomac 2.0 transport probe (an operator-configured SSH target; no allocation or billing)
+
+Set NOMAC_GATEWAY_URL and NOMAC_SESSION_TOKEN outside the project.
+  nomac tunnel <session>                          SSH ProxyCommand byte stream
+  nomac transport status <session>                connection capabilities
+  nomac transport exec <session> --request-key KEY [--timeout SECONDS] -- command args...
+  nomac transport job <session> <job>              inspect the existing job
+  nomac transport output <session> <job> [--cursor N] [--stream stdout|stderr]
+  nomac transport put <session> <file>             upload a checksummed probe blob (up to 8 MiB)
+  nomac transport get <session> <sha256> <file>     download a probe blob without overwriting
+
+Results are JSON. Output chunks are base64 with byte cursors, so binary output is lossless.
+Reuse the same request key after a lost response. Commands are never automatically rerun.
+Probe blobs do not yet implement project sync; ordinary SSH/rsync remains available.`;
+
+function parsed(args, allowed) {
+  const values = {};
+  for (let index = 0; index < args.length; index++) {
+    const flag = args[index];
+    if (flag === "--json") continue;
+    if (!allowed.includes(flag) || index + 1 >= args.length || values[flag] !== undefined) throw new CliError(`Unexpected transport option: ${flag}`);
+    values[flag] = args[++index];
+  }
+  return values;
+}
+
+export async function transportCommand(args, { request = macRequest, print = console.log } = {}) {
+  if (!args.length || ["help", "--help"].includes(args[0])) return print(HELP);
+  const [command, value, ...rest] = args;
+  const id = sessionId(value);
+  const base = `/api/v1/mac/sessions/${id}`;
+  let result;
+  if (command === "status") {
+    parsed(rest, []); result = await request("GET", base);
+  } else if (command === "exec") {
+    const separator = rest.indexOf("--");
+    if (separator === -1 || separator === rest.length - 1) throw new CliError("Use -- before the command and its arguments.");
+    const options = parsed(rest.slice(0, separator), ["--request-key", "--timeout"]);
+    if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(options["--request-key"] ?? "")) throw new CliError("Supply a stable --request-key of 8 to 128 safe characters.");
+    const timeout = Number(options["--timeout"] ?? 60);
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 600) throw new CliError("--timeout must be 1 to 600 seconds.");
+    result = await request("POST", `${base}/jobs`, { requestKey: options["--request-key"], body: { argv: rest.slice(separator + 1), timeout_seconds: timeout } });
+  } else if (command === "job" || command === "output") {
+    const [job, ...flags] = rest;
+    if (!/^job_[a-f0-9]{40}$/.test(job ?? "")) throw new CliError("Invalid job ID.");
+    const options = parsed(flags, command === "output" ? ["--cursor", "--stream"] : []);
+    const cursor = options["--cursor"] ?? "0", stream = options["--stream"] ?? "stdout";
+    if (!/^\d{1,16}$/.test(cursor) || !Number.isSafeInteger(Number(cursor)) || !["stdout", "stderr"].includes(stream)) throw new CliError("Invalid output stream or cursor.");
+    result = await request("GET", `${base}/jobs/${job}${command === "output" ? `/output?cursor=${cursor}&stream=${stream}` : ""}`);
+  } else if (command === "put") {
+    const [file, ...flags] = rest; parsed(flags, []);
+    if (!file) throw new CliError("Supply the file to upload.");
+    const info = statSync(file);
+    if (!info.isFile() || info.size > 8 * 1024 * 1024) throw new CliError("The probe accepts regular files up to 8 MiB.");
+    const data = readFileSync(file);
+    if (data.length > 8 * 1024 * 1024) throw new CliError("The file exceeded the probe limit.");
+    const digest = createHash("sha256").update(data).digest("hex");
+    let offset = 0;
+    do {
+      result = await request("PUT", `${base}/blobs/${digest}?size=${data.length}&offset=${offset}`, { raw: data.subarray(offset, offset + 256 * 1024) });
+      offset += 256 * 1024;
+    } while (offset < data.length && !result.complete);
+    if (!result.complete || result.id !== digest) throw new CliError("The upload was not confirmed. Retry the same file to resume.", undefined, undefined, "transfer_unconfirmed");
+  } else if (command === "get") {
+    const [digest, file, ...flags] = rest; parsed(flags, []);
+    if (!/^[a-f0-9]{64}$/.test(digest ?? "") || !file) throw new CliError("Supply the blob SHA-256 and destination file.");
+    const chunks = []; let cursor = 0, size;
+    for (;;) {
+      const chunk = await request("GET", `${base}/blobs/${digest}?cursor=${cursor}`);
+      const data = Buffer.from(chunk.data_base64 ?? "", "base64");
+      size ??= chunk.size;
+      if (chunk.id !== digest || !Number.isSafeInteger(size) || size < 0 || size > 8 * 1024 * 1024 || chunk.size !== size || chunk.cursor !== cursor || chunk.next_cursor !== cursor + data.length || chunk.next_cursor > size || (!data.length && !chunk.eof)) throw new CliError("Invalid file transfer response.", undefined, undefined, "transfer_unconfirmed");
+      chunks.push(data); cursor = chunk.next_cursor;
+      if (chunk.eof) break;
+    }
+    const data = Buffer.concat(chunks);
+    if (data.length !== size || createHash("sha256").update(data).digest("hex") !== digest) throw new CliError("Download checksum mismatch. No destination file was written.", undefined, undefined, "checksum_mismatch");
+    const destination = resolve(file), temporary = join(dirname(destination), `.nomac-download-${randomBytes(12).toString("hex")}`);
+    writeFileSync(temporary, data, { flag: "wx", mode: 0o600 });
+    try { linkSync(temporary, destination); } finally { unlinkSync(temporary); }
+    result = { id: digest, size: data.length, file: destination, complete: true };
+  } else throw new CliError(`Unknown transport command: ${command}`);
+  print(JSON.stringify(result));
+  return result;
+}

package/src/upload.mjs

@@ -9,7 +9,7 @@ export async function uploadSourceSnapshot(projectId, tarball) {
   } catch (error) {
     // Older servers have no grant route. Outages and authorization failures
     // should remain actionable, not silently retry through another transport.
-    if (!(error instanceof CliError) || error.status !== 404 || error.code) throw error;
+    if (!(error instanceof CliError) || error.status !== 404 || (error.code && error.code !== "bad_response")) throw error;
     if (tarball.length > 4 * 1024 * 1024) {
       throw new CliError("direct uploads unavailable", "This server does not support direct source uploads. Update the server or reduce the compressed archive to 4 MiB.");
     }