@shipvo/cli 0.1.5 → 0.1.6

package/dist/qr.js

@@ -0,0 +1,213 @@
+// A small QR code encoder: byte mode, error correction level L, versions 1 to 6 (up to 134 bytes). No dependencies.
+// Enough for a LAN URL. `qrMatrix` returns the modules; `qrToTerminal` draws them with half-block characters.
+const SIZES = [
+    [19, 7, 1], [34, 10, 1], [55, 15, 1], [80, 20, 1], [108, 26, 1], [136, 18, 2],
+];
+const ALIGN = [[], [6, 18], [6, 22], [6, 26], [6, 30], [6, 34]];
+export const QR_MAX_BYTES = 134;
+const EXP = new Uint8Array(512);
+const LOG = new Uint8Array(256);
+for (let i = 0, x = 1; i < 255; i++) {
+    EXP[i] = x;
+    LOG[x] = i;
+    x <<= 1;
+    if (x & 256)
+        x ^= 0x11d;
+}
+for (let i = 255; i < 512; i++)
+    EXP[i] = EXP[i - 255];
+const mul = (a, b) => (a && b ? EXP[LOG[a] + LOG[b]] : 0);
+/** Reed-Solomon error codewords for `data`. */
+export function rsRemainder(data, degree) {
+    let gen = [1];
+    for (let i = 0; i < degree; i++) {
+        const next = new Array(gen.length + 1).fill(0);
+        gen.forEach((c, j) => { next[j] ^= c; next[j + 1] ^= mul(c, EXP[i]); });
+        gen = next;
+    }
+    const rem = new Array(degree).fill(0);
+    for (const b of data) {
+        const f = b ^ rem.shift();
+        rem.push(0);
+        for (let i = 0; i < degree; i++)
+            rem[i] ^= mul(gen[i + 1], f);
+    }
+    return rem;
+}
+function codewordsFor(bytes, version) {
+    const [total, ecc, blocks] = SIZES[version - 1];
+    const bits = [];
+    const put = (v, n) => { for (let i = n - 1; i >= 0; i--)
+        bits.push((v >>> i) & 1); };
+    put(4, 4);
+    put(bytes.length, 8);
+    for (const b of bytes)
+        put(b, 8);
+    put(0, Math.min(4, total * 8 - bits.length));
+    while (bits.length % 8)
+        bits.push(0);
+    const data = [];
+    for (let i = 0; i < bits.length; i += 8)
+        data.push(parseInt(bits.slice(i, i + 8).join(""), 2));
+    for (let pad = 0xec; data.length < total; pad ^= 0xec ^ 0x11)
+        data.push(pad);
+    const per = total / blocks;
+    const dataBlocks = Array.from({ length: blocks }, (_, i) => data.slice(i * per, (i + 1) * per));
+    const eccBlocks = dataBlocks.map((b) => rsRemainder(b, ecc));
+    const out = [];
+    for (let i = 0; i < per; i++)
+        for (const b of dataBlocks)
+            out.push(b[i]);
+    for (let i = 0; i < ecc; i++)
+        for (const b of eccBlocks)
+            out.push(b[i]);
+    return out;
+}
+const MASKS = [
+    (x, y) => (x + y) % 2 === 0, (_x, y) => y % 2 === 0, (x) => x % 3 === 0, (x, y) => (x + y) % 3 === 0,
+    (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0, (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,
+    (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0, (x, y) => ((((x + y) % 2) + ((x * y) % 3)) % 2) === 0,
+];
+/** The 15 format bits for level L and a mask number. */
+export function formatBits(mask) {
+    const data = (1 << 3) | mask; // level L is 01
+    let rem = data;
+    for (let i = 0; i < 10; i++)
+        rem = (rem << 1) ^ ((rem >>> 9) * 0x537);
+    return ((data << 10) | rem) ^ 0x5412;
+}
+function penalty(m) {
+    const n = m.length;
+    let score = 0;
+    let dark = 0;
+    const line = (get) => {
+        let run = 1;
+        for (let i = 1; i <= n; i++) {
+            if (i < n && get(i) === get(i - 1))
+                run++;
+            else {
+                if (run >= 5)
+                    score += run - 2;
+                run = 1;
+            }
+        }
+        const s = Array.from({ length: n }, (_, i) => (get(i) ? 1 : 0)).join("");
+        for (const p of ["10111010000", "00001011101"])
+            for (let i = s.indexOf(p); i >= 0; i = s.indexOf(p, i + 1))
+                score += 40;
+    };
+    for (let a = 0; a < n; a++) {
+        line((i) => m[a][i]);
+        line((i) => m[i][a]);
+    }
+    for (let y = 0; y < n; y++)
+        for (let x = 0; x < n; x++) {
+            if (m[y][x])
+                dark++;
+            if (x + 1 < n && y + 1 < n && m[y][x] === m[y][x + 1] && m[y][x] === m[y + 1][x] && m[y][x] === m[y + 1][x + 1])
+                score += 3;
+        }
+    return score + (Math.ceil(Math.abs(dark * 20 - n * n * 10) / (n * n)) - 1) * 10;
+}
+/** Encodes text as a QR code. Returns rows of modules, true for dark. Throws when the text is over 134 bytes. */
+export function qrMatrix(text) {
+    const bytes = new TextEncoder().encode(text);
+    const version = SIZES.findIndex(([total]) => bytes.length <= total - 2) + 1;
+    if (!version)
+        throw new Error(`QR code input is ${bytes.length} bytes; the limit is ${QR_MAX_BYTES}.`);
+    const size = 17 + 4 * version;
+    const codewords = codewordsFor(bytes, version);
+    const base = Array.from({ length: size }, () => new Array(size).fill(false));
+    const fn = Array.from({ length: size }, () => new Array(size).fill(false));
+    const set = (x, y, dark) => { if (x >= 0 && y >= 0 && x < size && y < size) {
+        base[y][x] = dark;
+        fn[y][x] = true;
+    } };
+    for (const [cx, cy] of [[3, 3], [size - 4, 3], [3, size - 4]]) {
+        for (let dy = -4; dy <= 4; dy++)
+            for (let dx = -4; dx <= 4; dx++) {
+                const d = Math.max(Math.abs(dx), Math.abs(dy));
+                set(cx + dx, cy + dy, d !== 4 && d !== 2);
+            }
+    }
+    for (let i = 8; i < size - 8; i++) {
+        set(i, 6, i % 2 === 0);
+        set(6, i, i % 2 === 0);
+    }
+    const pos = ALIGN[version - 1];
+    for (const cy of pos)
+        for (const cx of pos) {
+            if ((cx === 6 && cy === 6) || (cx === 6 && cy === size - 7) || (cx === size - 7 && cy === 6))
+                continue;
+            for (let dy = -2; dy <= 2; dy++)
+                for (let dx = -2; dx <= 2; dx++)
+                    set(cx + dx, cy + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);
+        }
+    const format = (mask) => {
+        const f = formatBits(mask);
+        const bit = (i) => ((f >>> i) & 1) === 1;
+        for (let i = 0; i <= 5; i++)
+            set(8, i, bit(i));
+        set(8, 7, bit(6));
+        set(8, 8, bit(7));
+        set(7, 8, bit(8));
+        for (let i = 9; i < 15; i++)
+            set(14 - i, 8, bit(i));
+        for (let i = 0; i < 8; i++)
+            set(size - 1 - i, 8, bit(i));
+        for (let i = 8; i < 15; i++)
+            set(8, size - 15 + i, bit(i));
+        set(8, size - 8, true);
+    };
+    format(0); // reserves the areas; redone below with the chosen mask
+    let k = 0;
+    for (let right = size - 1; right >= 1; right -= 2) {
+        if (right === 6)
+            right = 5;
+        for (let v = 0; v < size; v++)
+            for (let j = 0; j < 2; j++) {
+                const x = right - j;
+                const y = ((right + 1) & 2) === 0 ? size - 1 - v : v;
+                if (!fn[y][x] && k < codewords.length * 8) {
+                    base[y][x] = ((codewords[k >> 3] >>> (7 - (k & 7))) & 1) === 1;
+                    k++;
+                }
+            }
+    }
+    let best;
+    let bestScore = Infinity;
+    for (let mask = 0; mask < 8; mask++) {
+        const m = base.map((row) => row.slice());
+        for (let y = 0; y < size; y++)
+            for (let x = 0; x < size; x++)
+                if (!fn[y][x] && MASKS[mask](x, y))
+                    m[y][x] = !m[y][x];
+        const saveBase = base.map((r) => r.slice());
+        for (let y = 0; y < size; y++)
+            base[y] = m[y];
+        format(mask);
+        const s = penalty(base);
+        if (s < bestScore) {
+            bestScore = s;
+            best = base.map((r) => r.slice());
+        }
+        for (let y = 0; y < size; y++)
+            base[y] = saveBase[y];
+    }
+    return best;
+}
+/** Draws the matrix for a terminal: black on white with ANSI colours, two rows per line, a 2 module quiet zone. */
+export function qrToTerminal(matrix, quiet = 2) {
+    const n = matrix.length + quiet * 2;
+    const at = (x, y) => matrix[y - quiet]?.[x - quiet] === true;
+    const lines = [];
+    for (let y = 0; y < n; y += 2) {
+        let s = "\x1b[30;47m";
+        for (let x = 0; x < n; x++) {
+            const t = at(x, y), b = y + 1 < n && at(x, y + 1);
+            s += t && b ? "█" : t ? "▀" : b ? "▄" : " ";
+        }
+        lines.push(s + "\x1b[0m");
+    }
+    return lines.join("\n");
+}

package/dist/report-md.d.ts

@@ -22,5 +22,6 @@ export type TestReport = {
     parityLimits?: string[];
     flows?: Flow[];
 };
+export declare function stepText(s: Step): string;
 export declare function renderReportMarkdown(report: TestReport): string;
 export {};

package/dist/report-md.js

@@ -5,7 +5,7 @@ function code(s) {
     const fence = "`".repeat(Math.max(0, ...[...t.matchAll(/`+/g)].map((m) => m[0].length)) + 1);
     return `${fence}${t.startsWith("`") || t.endsWith("`") ? ` ${t} ` : t}${fence}`;
 }
-function stepText(s) {
+export function stepText(s) {
     const kind = s.kind ?? "step";
     if (kind === "tap")
         return `tap "${s.target ?? ""}"`;

package/dist/rotation.d.ts

@@ -0,0 +1,57 @@
+export type RotationEnvelope = {
+    body: string;
+    signature: string;
+};
+export type RotationStatement = {
+    type: "key-rotation";
+    appId: string;
+    sequence: number;
+    newKey: string;
+    validFrom: string;
+};
+export type RotationFailure = "bad_envelope" | "bad_signature" | "bad_body" | "wrong_type" | "wrong_app" | "bad_sequence" | "replay" | "too_far" | "bad_key";
+export type RotationResult = {
+    ok: true;
+    statement: RotationStatement;
+} | {
+    ok: false;
+    reason: RotationFailure;
+};
+export declare const MAX_BODY_BYTES = 1024;
+export declare const MAX_PENDING_DAYS = 90;
+/** The body string. Key order is fixed; the signer keeps these exact bytes. */
+export declare function buildStatementBody(s: {
+    appId: string;
+    sequence: number;
+    newKey: string;
+    validFrom: string;
+}): string;
+/** Sign the exact UTF-8 bytes of `body` with the root seed. */
+export declare function signStatement(s: {
+    appId: string;
+    sequence: number;
+    newKey: string;
+    validFrom: string;
+}, rootSeedB64: string): RotationEnvelope;
+/**
+ * Check one envelope in the order of design section 8, then section 3.
+ * `effectiveSequence` is max(stored sequence, build minimum). `now` is the runtime clock.
+ */
+export declare function verifyStatement(env: unknown, rootPublicKeyB64: string, ctx: {
+    appId: string;
+    effectiveSequence: number;
+    now: Date;
+}): RotationResult;
+export declare class RotateError extends Error {
+}
+type Cfg = {
+    appId: string;
+    controlPlane: string;
+};
+export declare const ROTATE_HELP = "Usage:\n  shipvo keys rotate sign --root-seed-file <file> --new-key <public key> --sequence <n> [--valid-from <ISO time>] [--json]\n  shipvo keys rotate upload <envelope.json> [--json]\n\nsign works offline. It reads the ROOT seed from a file (never the release seed) and prints the signed envelope.\n--valid-from defaults to now (an emergency rotation). It may be at most 90 days ahead.\nPick a sequence above every statement you signed before. To override a planned statement, use a higher one.\nupload needs a signed-in owner session (shipvo login). Tokens are refused by the control plane.\n";
+/** Runs `shipvo keys rotate ...`. Throws RotateError for user mistakes; the caller prints it and exits 1. */
+export declare function rotate(argv: string[], cfg: Cfg, deps?: {
+    fetchFn?: typeof fetch;
+    now?: () => Date;
+}): Promise<void>;
+export {};

package/dist/rotation.js

@@ -0,0 +1,157 @@
+// Root-signed key rotation statements (docs/design/key-rotation.md, sections 3, 6 and 8).
+// `signStatement` and `verifyStatement` follow the wire format that the Android and iOS runtimes will check.
+import * as ed from "@noble/ed25519";
+import { readFileSync } from "node:fs";
+import { b64, keyFromSeed, unb64 } from "./index.js";
+import { args } from "./config.js";
+import { savedCreds } from "./login.js";
+export const MAX_BODY_BYTES = 1024;
+export const MAX_PENDING_DAYS = 90;
+const enc = new TextEncoder();
+/** The body string. Key order is fixed; the signer keeps these exact bytes. */
+export function buildStatementBody(s) {
+    if (!Number.isSafeInteger(s.sequence) || s.sequence < 1)
+        throw new Error("sequence must be an integer, at least 1 and at most 9007199254740991");
+    if (unb64(s.newKey).length !== 32)
+        throw new Error("the new release key must be a 32-byte Ed25519 public key (base64)");
+    const t = Date.parse(s.validFrom);
+    if (Number.isNaN(t))
+        throw new Error("validFrom must be an ISO 8601 UTC time");
+    return JSON.stringify({ type: "key-rotation", appId: s.appId, sequence: s.sequence, newKey: s.newKey, validFrom: new Date(t).toISOString() });
+}
+/** Sign the exact UTF-8 bytes of `body` with the root seed. */
+export function signStatement(s, rootSeedB64) {
+    const body = buildStatementBody(s);
+    const { seed } = keyFromSeed(rootSeedB64);
+    return { body, signature: b64(ed.sign(enc.encode(body), seed)) };
+}
+/**
+ * Check one envelope in the order of design section 8, then section 3.
+ * `effectiveSequence` is max(stored sequence, build minimum). `now` is the runtime clock.
+ */
+export function verifyStatement(env, rootPublicKeyB64, ctx) {
+    const e = env;
+    if (!e || typeof e.body !== "string" || typeof e.signature !== "string" || enc.encode(e.body).length > MAX_BODY_BYTES)
+        return { ok: false, reason: "bad_envelope" };
+    let good = false;
+    try {
+        good = ed.verify(unb64(e.signature), enc.encode(e.body), unb64(rootPublicKeyB64));
+    }
+    catch {
+        good = false;
+    }
+    if (!good)
+        return { ok: false, reason: "bad_signature" };
+    let s;
+    try {
+        s = JSON.parse(e.body);
+    }
+    catch {
+        return { ok: false, reason: "bad_body" };
+    }
+    if (!s || typeof s !== "object" || Array.isArray(s))
+        return { ok: false, reason: "bad_body" };
+    if (s.type !== "key-rotation")
+        return { ok: false, reason: "wrong_type" };
+    if (s.appId !== ctx.appId)
+        return { ok: false, reason: "wrong_app" };
+    if (!Number.isSafeInteger(s.sequence) || s.sequence < 1)
+        return { ok: false, reason: "bad_sequence" };
+    if (s.sequence <= ctx.effectiveSequence)
+        return { ok: false, reason: "replay" };
+    const from = typeof s.validFrom === "string" ? Date.parse(s.validFrom) : NaN;
+    if (Number.isNaN(from))
+        return { ok: false, reason: "bad_body" };
+    if (from > ctx.now.getTime() + MAX_PENDING_DAYS * 86_400_000)
+        return { ok: false, reason: "too_far" };
+    if (typeof s.newKey !== "string" || unb64(s.newKey).length !== 32)
+        return { ok: false, reason: "bad_key" };
+    return { ok: true, statement: s };
+}
+export class RotateError extends Error {
+}
+export const ROTATE_HELP = `Usage:
+  shipvo keys rotate sign --root-seed-file <file> --new-key <public key> --sequence <n> [--valid-from <ISO time>] [--json]
+  shipvo keys rotate upload <envelope.json> [--json]
+
+sign works offline. It reads the ROOT seed from a file (never the release seed) and prints the signed envelope.
+--valid-from defaults to now (an emergency rotation). It may be at most ${MAX_PENDING_DAYS} days ahead.
+Pick a sequence above every statement you signed before. To override a planned statement, use a higher one.
+upload needs a signed-in owner session (shipvo login). Tokens are refused by the control plane.
+`;
+/** Runs `shipvo keys rotate ...`. Throws RotateError for user mistakes; the caller prints it and exits 1. */
+export async function rotate(argv, cfg, deps = {}) {
+    const [sub, ...rest] = argv, a = args(rest), json = a.json === "true";
+    const now = (deps.now ?? (() => new Date()))();
+    if (sub === "sign") {
+        const file = a["root-seed-file"], newKey = a["new-key"], seq = a.sequence;
+        if (!file || file === "true" || !newKey || newKey === "true" || !seq || seq === "true")
+            throw new RotateError(ROTATE_HELP);
+        let rootSeed;
+        try {
+            rootSeed = readFileSync(file, "utf8").trim();
+        }
+        catch {
+            throw new RotateError(`Cannot read the root seed file ${file}.`);
+        }
+        try {
+            keyFromSeed(rootSeed);
+        }
+        catch {
+            throw new RotateError("The root seed is not valid: it must be a 32-byte value in base64.");
+        }
+        if (!/^\d+$/.test(seq) || !Number.isSafeInteger(Number(seq)) || Number(seq) < 1)
+            throw new RotateError("--sequence must be a whole number from 1 to 9007199254740991.");
+        const validFrom = a["valid-from"] && a["valid-from"] !== "true" ? a["valid-from"] : now.toISOString();
+        const t = Date.parse(validFrom);
+        if (Number.isNaN(t))
+            throw new RotateError("--valid-from must be an ISO 8601 UTC time, such as 2026-11-06T00:00:00Z.");
+        if (t > now.getTime() + MAX_PENDING_DAYS * 86_400_000)
+            throw new RotateError(`--valid-from is more than ${MAX_PENDING_DAYS} days ahead. Phones would reject it.`);
+        let env;
+        try {
+            env = signStatement({ appId: cfg.appId, sequence: Number(seq), newKey, validFrom }, rootSeed);
+        }
+        catch (e) {
+            throw new RotateError(e instanceof Error ? e.message : String(e));
+        }
+        console.log(JSON.stringify(env, null, json ? 0 : 2));
+        if (!json)
+            console.error(`Signed rotation statement ${seq} for "${cfg.appId}". Confirm ${seq} is above every statement you signed before; this offline tool cannot check. Then run: shipvo keys rotate upload <file>`);
+        return;
+    }
+    if (sub === "upload") {
+        const file = rest.find((x) => !x.startsWith("--"));
+        if (!file)
+            throw new RotateError(ROTATE_HELP);
+        let env;
+        try {
+            env = JSON.parse(readFileSync(file === "-" ? 0 : file, "utf8"));
+        }
+        catch {
+            throw new RotateError(`${file} is not a readable JSON envelope.`);
+        }
+        if (typeof env?.body !== "string" || typeof env?.signature !== "string")
+            throw new RotateError("The envelope needs a string \"body\" and a string \"signature\".");
+        const creds = savedCreds();
+        if (!creds?.key)
+            throw new RotateError("Not signed in. Run `shipvo login` as the app owner. Tokens cannot upload rotation statements.");
+        const norm = (u) => u.replace(/\/$/, "");
+        if (norm(creds.control ?? "") !== norm(cfg.controlPlane))
+            throw new RotateError(`shipvo.json controlPlane is ${cfg.controlPlane}, but you signed in at ${creds.control || "another host"}. Not sending your session key there. Fix controlPlane or run \`shipvo login\` for that host.`);
+        const url = `${cfg.controlPlane.replace(/\/$/, "")}/rotation/${encodeURIComponent(cfg.appId)}`;
+        let r;
+        try {
+            r = await (deps.fetchFn ?? fetch)(url, { method: "POST", headers: { authorization: `Bearer ${creds.key}`, "content-type": "application/json" }, body: JSON.stringify({ body: env.body, signature: env.signature }) });
+        }
+        catch (e) {
+            throw new RotateError(`Could not reach the control plane at ${cfg.controlPlane} (${e instanceof Error ? e.message : String(e)}).`);
+        }
+        const out = await r.json().catch(() => ({}));
+        if (!r.ok)
+            throw new RotateError(`The control plane refused the statement (HTTP ${r.status}): ${out.message ?? out.reason ?? out.error ?? "no reason given"}`);
+        console.log(json ? JSON.stringify({ ok: true, ...out }) : `Uploaded. Phones switch when they next fetch it.`);
+        return;
+    }
+    throw new RotateError(ROTATE_HELP);
+}