@vincentt-xr/cli 0.21.0 → 0.22.0

package/dist/preview/command.js

@@ -338,6 +338,8 @@ export function endingLines(reason, orgName, refusal = {}) {
             return previewTooOldLines(refusal);
         case "auth_expired":
             return copy.endedAuthExpired();
+        case "protocol_violation":
+            return copy.endedProtocolViolation();
         case "egress_cap":
             return copy.egressHard();
         case "stopped":

package/dist/preview/copy.d.ts

@@ -219,6 +219,11 @@ export declare function endedAuthExpired(): string[];
  * link, and a silent re-mint would break every link already shared.
  */
 export declare function endedAuthzLapsed(): string[];
+/**
+ * The edge broke the agreed tunnel wire. Only an edge bug causes it, so the
+ * remedy is a newer CLI or a later attempt, never anything in the project.
+ */
+export declare function endedProtocolViolation(): string[];
 /**
  * e. Abandoned — this machine stopped checking in (the 30-minute heartbeat-
  * silence flip, `D-Abandoned-sessions-are-judged-on-heartbeat-silence-alone`).

package/dist/preview/copy.js

@@ -18,6 +18,7 @@
 // product, so f1's "a token is never printed" extends to it verbatim.
 /** Flow L13 — the start block. */
 import { escapeControl, terminalSafe } from "../lib/terminalText.js";
+import { INSTALL_COMMAND } from "../shared/upgradeError.js";
 export function startBlock(i) {
     const out = [
         "",
@@ -477,6 +478,20 @@ export function endedAuthzLapsed() {
         "",
     ];
 }
+/**
+ * The edge broke the agreed tunnel wire. Only an edge bug causes it, so the
+ * remedy is a newer CLI or a later attempt, never anything in the project.
+ */
+export function endedProtocolViolation() {
+    return [
+        "",
+        "✗ Preview stopped: the preview server sent an invalid reply. Update the CLI or try again later.",
+        "",
+        `  Upgrade:  ${INSTALL_COMMAND}`,
+        "  Then try again:  vincentt preview",
+        "",
+    ];
+}
 /**
  * e. Abandoned — this machine stopped checking in (the 30-minute heartbeat-
  * silence flip, `D-Abandoned-sessions-are-judged-on-heartbeat-silence-alone`).

package/dist/preview/runner.d.ts

@@ -45,6 +45,12 @@ export type PreviewEndReason = "stopped"
  * both. No further platform call is made, the DELETE included.
  */
  | "upgrade_required"
+/**
+ * The edge broke the agreed tunnel wire (a malformed 101 caps header, a
+ * CONTROL frame this connection cannot read, or a fatal OPEN). Final: a redial reaches the
+ * same edge, so the tunnel client has already stopped dialling.
+ */
+ | "protocol_violation"
 /**
  * The 30-minute heartbeat-silence flip. NEVER reported as `hard_max`: a
  * session ended at minute 30 has not reached its 12-hour ceiling, and saying

package/dist/preview/runner.js

@@ -256,6 +256,7 @@ export async function startPreview(opts) {
                 if (reason !== null)
                     ended(reason);
             },
+            onProtocolViolation: () => ended("protocol_violation"),
             onRefused: (_reason, minimum, declared) => ended("upgrade_required", {
                 minimum: parseMinimum(minimum),
                 declared: parseDeclared(declared),

package/dist/publish/command.js

@@ -15,7 +15,7 @@ import { buildManifest, ManifestError } from "./manifest.js";
 import { checkBounds } from "./bounds.js";
 import { classifyDist } from "./classify.js";
 import { createProgress } from "./progress.js";
-import { UploadExpired, UploadFailed, UploadTargetRejected, uploadAll, } from "./upload.js";
+import { UploadExpired, UploadFailed, UploadTargetRejected, UploadChecksumMismatch, uploadAll, } from "./upload.js";
 import { escapeTerminal } from "../lib/terminalText.js";
 /** Re-opens after an expired upload link, per publish, before giving up. */
 export const MAX_REOPENS = 2;
@@ -342,7 +342,8 @@ async function runUpload(deps, cfg, i) {
         }
         const failedPath = err instanceof UploadFailed ||
             err instanceof UploadExpired ||
-            err instanceof UploadTargetRejected
+            err instanceof UploadTargetRejected ||
+            err instanceof UploadChecksumMismatch
             ? escapeTerminal(err.path)
             : "a file";
         deps.print("");
@@ -563,6 +564,8 @@ function outputRefusal(err, output, buildCommand) {
     switch (err.reason) {
         case "secret_path":
             return copy.secretFiles(err.paths, output);
+        case "path_escaped":
+            return copy.escapedFiles(err.paths, output);
         case "credential_file":
             return copy.credentialFiles(err.paths, output);
         case "file_unreadable":

package/dist/publish/copy.d.ts

@@ -176,6 +176,12 @@ export declare function outputOutside(shown: string): string[];
 export declare function outputInHidden(shown: string, hidden: string): string[];
 /** Flow U1 — hidden names or symlinks that would leak. After the header and reading line. */
 export declare function secretFiles(paths: Offender[], output?: OutputLabel): string[];
+/**
+ * Flow U1 — files whose folder resolved outside the output after the walk: a
+ * folder was swapped for a link while publish read it. The whole publish is
+ * refused, never just the file. After the header and reading line.
+ */
+export declare function escapedFiles(paths: Offender[], output?: OutputLabel): string[];
 /** Flow U1 — credential files, from the early checks or the hash step. After the header and reading line. */
 export declare function credentialFiles(paths: Offender[], output?: OutputLabel): string[];
 /** Flow U1 — a file that changed, became a link, or could not be read while checked or hashed. */

package/dist/publish/copy.js

@@ -404,7 +404,7 @@ export function tooLarge(v) {
             "",
             "✗ One file is too large to publish.",
             "",
-            ...alignedPair([v.path ?? "", formatBytes(v.observed)], ["the per-file limit", formatLimit(v.limit)]),
+            ...alignedPair([escapeTerminal(v.path ?? ""), formatBytes(v.observed)], ["the per-file limit", formatLimit(v.limit)]),
             "",
             "  Compress or externalise it, rebuild, then publish again.",
             "",
@@ -453,9 +453,10 @@ function alignedPair(a, b) {
     ];
 }
 function largestBlock(v) {
-    const width = Math.max(0, ...v.largest.map((f) => f.path.length));
-    const sizeWidth = Math.max(0, ...v.largest.map((f) => formatBytes(f.size).length));
-    return v.largest.map((f) => `    ${f.path.padEnd(width)}  ${formatBytes(f.size).padStart(sizeWidth)}`);
+    const largest = v.largest.map((f) => ({ path: escapeTerminal(f.path), size: f.size }));
+    const width = Math.max(0, ...largest.map((f) => f.path.length));
+    const sizeWidth = Math.max(0, ...largest.map((f) => formatBytes(f.size).length));
+    return largest.map((f) => `    ${f.path.padEnd(width)}  ${formatBytes(f.size).padStart(sizeWidth)}`);
 }
 /** No dist at all, or no index.html at its root. Zero network calls. */
 /**
@@ -532,7 +533,7 @@ export function outputOutside(shown) {
 export function outputInHidden(shown, hidden) {
     return [
         "",
-        `✗ The build output ${escapeTerminal(shown)} is inside ${hidden}/, not a build.`,
+        `✗ The build output ${escapeTerminal(shown)} is inside ${escapeTerminal(hidden)}/, not a build.`,
         "",
         "  Publishing it would put your repository's history or its Vincentt link at a",
         "  public address. Set --dist, or build.output in vincentt.json, to the folder",
@@ -585,6 +586,26 @@ export function secretFiles(paths, output = DEFAULT_OUTPUT) {
         "",
     ];
 }
+/**
+ * Flow U1 — files whose folder resolved outside the output after the walk: a
+ * folder was swapped for a link while publish read it. The whole publish is
+ * refused, never just the file. After the header and reading line.
+ */
+export function escapedFiles(paths, output = DEFAULT_OUTPUT) {
+    return [
+        "",
+        `✗ These files resolved outside ${escapeTerminal(output.folder)} while publish was reading them.`,
+        "",
+        ...offenderList(paths, output.folder),
+        "",
+        "  A folder in the build output became a link to somewhere else, so publish",
+        "  cannot vouch for what it would upload. Let your build finish, then publish",
+        "  again.",
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
 /** Flow U1 — credential files, from the early checks or the hash step. After the header and reading line. */
 export function credentialFiles(paths, output = DEFAULT_OUTPUT) {
     return [
@@ -914,7 +935,7 @@ export function publishIncomplete(address, counts, liveVersion) {
 export function badDigest(filePath, address, liveVersion) {
     return [
         "",
-        `✗ ${filePath} changed while uploading. Rebuild and publish again.`,
+        `✗ ${escapeTerminal(filePath)} changed while uploading. Rebuild and publish again.`,
         "",
         ...unchangedLines(address, liveVersion),
         "",

package/dist/publish/manifest.d.ts

@@ -11,7 +11,7 @@ export interface Manifest {
     files: ManifestEntry[];
     totalBytes: number;
 }
-export type ManifestReason = PathRejection | "no_dist" | "output_is_repo_root" | "output_outside_repo" | "output_in_hidden" | "secret_path" | "credential_file" | "lfs_pointer" | "file_unreadable";
+export type ManifestReason = PathRejection | "no_dist" | "output_is_repo_root" | "output_outside_repo" | "output_in_hidden" | "secret_path" | "path_escaped" | "credential_file" | "lfs_pointer" | "file_unreadable";
 export type CredentialWhy = "name" | "private_key" | CredentialJsonType;
 /** An output-relative path the leak, credential or LFS check refused. */
 export interface Offender {
@@ -64,6 +64,15 @@ export interface BuildManifestOptions {
      * change a checked file. Never set by the command.
      */
     beforeHash?: (files: readonly WalkedFile[]) => Promise<void> | void;
+    /**
+     * Test-only: runs before the walk reads each folder, so a test can swap a
+     * folder mid-walk. Never set by the command.
+     */
+    beforeReadDir?: (dir: string) => Promise<void> | void;
+}
+/** Test-only hooks into the checks. */
+export interface CheckOutputHooks {
+    beforeReadDir?: (dir: string) => Promise<void> | void;
 }
 /** A Git LFS pointer file: at most 1 KB, the spec's exact first line, and an oid line. */
 export declare function isLfsPointer(head: Uint8Array, size: number): boolean;
@@ -77,7 +86,7 @@ export declare function readHead(file: WalkedFile): Promise<Buffer>;
  * or sent. Returns the file list the checks passed, which is exactly the list
  * the manifest is built from: what is checked is what is uploaded.
  */
-export declare function checkOutput(distDir: string, repoRoot: string): Promise<WalkedFile[]>;
+export declare function checkOutput(distDir: string, repoRoot: string, hooks?: CheckOutputHooks): Promise<WalkedFile[]>;
 export interface HashResult {
     /** base64 std, the exact form `x-amz-checksum-sha256` wants. */
     sha256: string;

package/dist/publish/manifest.js

@@ -55,15 +55,23 @@ function isJsonName(rel) {
  * symlink is resolved and judged against the real repo root, and a name on the
  * credential list is recorded apart (a folder once, never descended).
  */
-async function walkOutput(outReal, rootReal) {
+async function walkOutput(outReal, rootReal, hooks) {
     const walk = { files: [], offenders: [], credentialNames: [] };
     let seq = 0;
+    const relOf = (full) => path.relative(outReal, full).split(path.sep).join("/");
+    // A read error's message carries the raw absolute path. It becomes a refusal
+    // naming the output-relative path, which the copy escapes.
+    const unreadable = (rel) => new ManifestError("file_unreadable", rel, "a path could not be read");
     const visit = async (dir) => {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
+        await hooks.beforeReadDir?.(dir);
+        const dirRel = dir === outReal ? "" : `${relOf(dir)}/`;
+        const entries = await fs
+            .readdir(dir, { withFileTypes: true })
+            .catch(() => Promise.reject(unreadable(dirRel)));
         entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
         for (const entry of entries) {
             const full = path.join(dir, entry.name);
-            const rel = path.relative(outReal, full).split(path.sep).join("/");
+            const rel = relOf(full);
             const atRoot = dir === outReal;
             const lower = entry.name.toLowerCase();
             if (entry.name.startsWith(".")) {
@@ -101,7 +109,7 @@ async function walkOutput(outReal, rootReal) {
                 await visit(full);
             }
             else if (entry.isFile()) {
-                const stat = await fs.lstat(full);
+                const stat = await fs.lstat(full).catch(() => Promise.reject(unreadable(rel)));
                 const at = seq++;
                 if (nameMatched) {
                     walk.credentialNames.push({ seq: at, offender: { path: rel, why: "name" } });
@@ -121,6 +129,25 @@ async function walkOutput(outReal, rootReal) {
     await visit(outReal);
     return walk;
 }
+/**
+ * Files whose real parent folder is not inside the real output. The walk reads
+ * a folder by path, so a folder swapped for a symlink mid-walk is walked through
+ * the link; this catches it after the fact. A parent that cannot be resolved
+ * counts as escaped: it is never assumed inside.
+ */
+async function escapedFiles(files, outReal) {
+    const parents = new Map();
+    const inside = (dir) => {
+        let p = parents.get(dir);
+        if (p === undefined) {
+            p = fs.realpath(dir).then((real) => real === outReal || isInside(real, outReal), () => false);
+            parents.set(dir, p);
+        }
+        return p;
+    };
+    const verdicts = await mapLimit(files, READ_CONCURRENCY, (f) => inside(path.dirname(f.abs)));
+    return files.filter((_, i) => !verdicts[i]).map((f) => ({ path: f.rel }));
+}
 /** Where a symlink lands: its realpath, or its lexical target when it dangles. */
 async function symlinkTarget(link) {
     try {
@@ -235,7 +262,7 @@ function forbiddenSegmentIn(rel) {
  * or sent. Returns the file list the checks passed, which is exactly the list
  * the manifest is built from: what is checked is what is uploaded.
  */
-export async function checkOutput(distDir, repoRoot) {
+export async function checkOutput(distDir, repoRoot, hooks = {}) {
     const rootReal = await fs.realpath(repoRoot).catch(() => path.resolve(repoRoot));
     const lexical = path.resolve(distDir);
     const lexicalRoot = path.resolve(repoRoot);
@@ -253,7 +280,7 @@ export async function checkOutput(distDir, repoRoot) {
         if (err.code === "ENOENT") {
             throw new ManifestError("no_dist", distDir, `no dist at ${distDir}`);
         }
-        throw err;
+        throw new ManifestError("file_unreadable", "", "the output could not be read");
     }
     if (outReal === rootReal) {
         throw new ManifestError("output_is_repo_root", distDir, `${distDir} resolves to the repo root`);
@@ -266,14 +293,21 @@ export async function checkOutput(distDir, repoRoot) {
     if (hiddenParent !== undefined) {
         throw new ManifestError("output_in_hidden", hiddenParent, `${distDir} is inside ${hiddenParent}`);
     }
-    if (!(await fs.stat(outReal)).isDirectory()) {
+    const outStat = await fs.stat(outReal).catch(() => {
+        throw new ManifestError("file_unreadable", "", "the output could not be read");
+    });
+    if (!outStat.isDirectory()) {
         throw new ManifestError("no_dist", distDir, `no dist at ${distDir}`);
     }
-    const walk = await walkOutput(outReal, rootReal);
+    const walk = await walkOutput(outReal, rootReal, hooks);
     const stats = {
         files: walk.files.length,
         bytes: walk.files.reduce((n, f) => n + f.size, 0),
     };
+    const escaped = await escapedFiles(walk.files, outReal);
+    if (escaped.length > 0) {
+        throw new ManifestError("path_escaped", escaped[0].path, "files resolved outside the output", { paths: escaped, stats });
+    }
     if (walk.offenders.length > 0) {
         throw new ManifestError("secret_path", walk.offenders[0].path, "hidden paths in the output", {
             paths: walk.offenders,
@@ -385,7 +419,9 @@ export async function hashAndScan(absPath, walked) {
 export async function buildManifest(distDir, opts) {
     // The list the checks passed IS the upload list. A second walk could see a
     // file created after the checks ran.
-    const walked = await checkOutput(distDir, opts.repoRoot);
+    const walked = await checkOutput(distDir, opts.repoRoot, {
+        beforeReadDir: opts.beforeReadDir,
+    });
     const normalized = [];
     for (const file of walked) {
         const result = normalizePath(file.rel);

package/dist/publish/upload.d.ts

@@ -30,6 +30,16 @@ export declare class UploadTargetRejected extends Error {
     readonly path: string;
     constructor(path: string);
 }
+/**
+ * A target's signed checksum is not the one this run's manifest holds for that
+ * path. The PUT reopens the file by path, so the signed checksum is what makes
+ * "checked is uploaded" hold; a target that would sign anything else is refused
+ * before any byte is sent.
+ */
+export declare class UploadChecksumMismatch extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
 export interface UploadProgress {
     filesDone: number;
     filesTotal: number;

package/dist/publish/upload.js

@@ -58,6 +58,25 @@ export class UploadTargetRejected extends Error {
         this.name = "UploadTargetRejected";
     }
 }
+/**
+ * A target's signed checksum is not the one this run's manifest holds for that
+ * path. The PUT reopens the file by path, so the signed checksum is what makes
+ * "checked is uploaded" hold; a target that would sign anything else is refused
+ * before any byte is sent.
+ */
+export class UploadChecksumMismatch extends Error {
+    path;
+    constructor(path) {
+        super(`the upload target ${path} does not carry this build's checksum`);
+        this.path = path;
+        this.name = "UploadChecksumMismatch";
+    }
+}
+const CHECKSUM_HEADER = "x-amz-checksum-sha256";
+function signedChecksum(headers) {
+    const key = Object.keys(headers).find((k) => k.toLowerCase() === CHECKSUM_HEADER);
+    return key === undefined ? undefined : headers[key];
+}
 const DEFAULT_CONCURRENCY = 6;
 const DEFAULT_MAX_ATTEMPTS = 5;
 const BACKOFF_BASE_MS = 500;
@@ -114,6 +133,10 @@ export async function uploadAll(opts) {
     const foreign = opts.targets.find((t) => !sizes.has(t.path));
     if (foreign !== undefined)
         throw new UploadTargetRejected(foreign.path);
+    const sums = new Map(opts.manifest.map((f) => [f.path, f.sha256]));
+    const mismatched = opts.targets.find((t) => signedChecksum(t.headers) !== sums.get(t.path));
+    if (mismatched !== undefined)
+        throw new UploadChecksumMismatch(mismatched.path);
     const bytesTotal = opts.targets.reduce((n, t) => n + (sizes.get(t.path) ?? 0), 0);
     const queue = [...opts.targets];
     const retry = {

package/dist/shared/config.d.ts

@@ -8,14 +8,14 @@ export interface MachineConfig {
     /** Org slug commands act in when no --org flag or VINCENTT_ORG env is given. */
     activeOrg: string;
     /**
-     * Durable authorization for unattended `dx --send`. Written only by
-     * `vincentt dx enable`, which requires a TTY. Cleared by `disable` and by `logout`.
+     * This machine's copy of the account's unattended-send grant. Written by
+     * `vincentt dx enable` only after the account grant succeeded, on either path.
+     * Authorizes a send on its own ONLY when GET /me cannot be read. Cleared by
+     * `disable`, by `logout`, and by any /me answer that is not a grant.
      */
     dxSendEnabled?: boolean;
-    /**
-     * ISO8601 UTC, when enablement was granted. Its AGE is the mitigation for having
-     * no expiry, so an unparseable value fails closed rather than printing.
-     */
+    /** ISO8601 UTC: the account's dxReportsConsentAt on the terminal path; the CLI's
+     *  clock on the browser path, whose callback carries no date. */
     dxSendEnabledAt?: string;
 }
 /**

package/dist/tunnel/client.d.ts

@@ -157,6 +157,13 @@ export interface TunnelClientOptions {
      * this preview, 410 the session is gone. They map to different creator actions.
      */
     readonly onReconnectRefused?: (status: number) => void;
+    /**
+     * The edge broke the agreed wire: a malformed 101 caps header, a CONTROL
+     * frame this connection cannot read, or a fatal OPEN. Only an edge bug causes
+     * it, and a redial
+     * reaches the same edge, so the client makes no further dial after this.
+     */
+    readonly onProtocolViolation?: () => void;
     /** Injectable for tests; never a real socket in a unit test. */
     readonly connect?: (url: string, headers: Record<string, string>) => WebSocket;
 }
@@ -232,10 +239,11 @@ export declare class TunnelClient {
     private open;
     private onClosed;
     /**
-     * Close this connection for a violation the edge alone could cause. The
-     * ordinary close path then decides whether to redial.
+     * End the preview for a violation the edge alone could cause. A redial reaches
+     * the same edge and gets the same answer: before this was terminal, a
+     * persistently malformed 101 redialled every 8 seconds indefinitely.
      */
-    private protocolViolation;
+    private fatalViolation;
     private startPing;
     private stopPing;
     private send;

package/dist/tunnel/client.js

@@ -281,10 +281,10 @@ export class TunnelClient {
             // The agreed set fixes this connection's grammar. Absent is the base
             // protocol (an edge that predates negotiation); a malformed answer, or
             // one naming a token this client did not offer, is the edge
-            // misbehaving and closes the connection.
+            // misbehaving and ends the preview.
             const agreed = parseAgreedCaps(res.headers[CAPS_HEADER], res.rawHeaders);
             if (agreed === null) {
-                this.protocolViolation(ws);
+                this.fatalViolation(ws);
                 return;
             }
             this.caps = agreed;
@@ -382,12 +382,15 @@ export class TunnelClient {
         }, delay);
     }
     /**
-     * Close this connection for a violation the edge alone could cause. The
-     * ordinary close path then decides whether to redial.
+     * End the preview for a violation the edge alone could cause. A redial reaches
+     * the same edge and gets the same answer: before this was terminal, a
+     * persistently malformed 101 redialled every 8 seconds indefinitely.
      */
-    protocolViolation(ws) {
-        if (this.ws !== ws)
+    fatalViolation(ws) {
+        if (ws === null || this.ws !== ws || this.closed)
             return;
+        this.closed = true;
+        this.opts.onProtocolViolation?.();
         ws.close();
     }
     startPing() {
@@ -453,7 +456,7 @@ export class TunnelClient {
                 catch {
                     // A CONTROL this connection cannot read (malformed, unknown, or a
                     // kind it did not agree) is fatal: only the edge writes stream 0.
-                    this.ws?.close();
+                    this.fatalViolation(this.ws);
                     return;
                 }
                 if (ctrl.kind === "viewer_gone") {
@@ -478,7 +481,7 @@ export class TunnelClient {
                 }
                 catch (err) {
                     if (err instanceof ProtocolError && err.fatal) {
-                        this.ws?.close();
+                        this.fatalViolation(this.ws);
                         return;
                     }
                     this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",