@scalebun-release/cli 2.5.0

package/lib/utils/validate.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nearest = nearest;
+exports.checkedEnum = checkedEnum;
+exports.checkedInt = checkedInt;
+exports.checkedPercent = checkedPercent;
+exports.checkedId = checkedId;
+exports.checkedVersionRange = checkedVersionRange;
+exports.checkedText = checkedText;
+const output_1 = require("./output");
+/**
+ * Checked parsers for everything the user can type.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ *
+ * Bad input was being handled three different ways, and two of them were
+ * silent:
+ *
+ *   1. Cast and hope.      `opts.platform as 'android' | 'ios'` — `--platform
+ *                          windows` sails through to the bundler.
+ *   2. Coerce to a default. `Math.max(1, Number(opts.limit) || 20)` — a typo'd
+ *                          `--limit abc` quietly means 20, and `--limit -5`
+ *                          quietly means 1.
+ *   3. Compare and shrug.  `if (opts.failOn === 'act')` — `--fail-on acts`
+ *                          matches nothing, so the CI gate the user asked for
+ *                          silently does not exist and the pipeline goes green.
+ *
+ * The third is the dangerous one and the pattern is general: an unrecognised
+ * value that falls through a comparison disables the behaviour it was meant to
+ * request, and disabled checks look exactly like passing checks. Every parser
+ * here refuses instead, names the flag, shows what was received, and — for
+ * enums — suggests the intended value when it is one edit away.
+ *
+ * All of them exit with ExitCode.Usage, because "you typed the command wrong"
+ * and "your project is not ready" (Gate/3) want opposite responses in CI.
+ */
+/**
+ * Edit distance, capped — only used to decide whether to offer a suggestion,
+ * so the exact number past 3 never matters.
+ */
+function distance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (Math.abs(m - n) > 3)
+        return 99;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+        const curr = [i];
+        for (let j = 1; j <= n; j++) {
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = curr;
+    }
+    return prev[n];
+}
+/** The allowed value closest to `raw`, when one is close enough to mean it. */
+function nearest(raw, allowed) {
+    let best = null;
+    let bestScore = 99;
+    const lower = raw.toLowerCase();
+    for (const option of allowed) {
+        const d = distance(lower, option.toLowerCase());
+        if (d < bestScore) {
+            bestScore = d;
+            best = option;
+        }
+    }
+    // Two edits on a short word is already a different word; scale the tolerance
+    // so `acts`→`act` is offered but `x`→`act` is not.
+    return best !== null && bestScore <= Math.max(1, Math.floor(best.length / 3)) ? best : null;
+}
+/**
+ * One of `allowed`, or exit.
+ *
+ * Replaces `if (opts.x === 'known')` chains, where an unrecognised value is
+ * indistinguishable from the flag not being passed at all.
+ */
+function checkedEnum(flag, raw, allowed, opts = {}) {
+    if (opts.caseInsensitive) {
+        const hit = allowed.find((a) => a.toLowerCase() === raw.toLowerCase());
+        if (hit)
+            return hit;
+    }
+    else if (allowed.includes(raw)) {
+        return raw;
+    }
+    const guess = nearest(raw, allowed);
+    (0, output_1.fail)(`${flag} must be one of ${allowed.join(', ')} — got "${raw}".`, [...(guess ? [`Did you mean ${flag} ${guess}?`] : []), ...(opts.details ?? [])], output_1.ExitCode.Usage);
+}
+/**
+ * A whole number in range, or exit.
+ *
+ * `Number('12abc')` is NaN and `Number('')` is 0 — both of which a `|| default`
+ * turns into a plausible-looking value the user never asked for. Everything
+ * that is not cleanly an integer is refused here instead.
+ */
+function checkedInt(flag, raw, opts = {}) {
+    if (raw === undefined || raw === null || raw === '') {
+        if (opts.fallback !== undefined)
+            return opts.fallback;
+        (0, output_1.fail)(`${flag} is required.`, opts.details ?? [], output_1.ExitCode.Usage);
+    }
+    const text = String(raw).trim();
+    const range = opts.min !== undefined && opts.max !== undefined
+        ? ` from ${opts.min} to ${opts.max}`
+        : opts.min !== undefined
+            ? ` of at least ${opts.min}`
+            : '';
+    // Deliberately strict: Number() accepts '0x10', '1e3', ' 12 ' and Infinity,
+    // none of which anyone means to type into a CLI flag.
+    if (!/^[+-]?\d+$/.test(text)) {
+        (0, output_1.fail)(`${flag} must be a whole number${range} — got "${text}".`, [
+            ...(/^[+-]?\d*\.\d+$/.test(text) ? ['Fractions are not accepted here.'] : []),
+            ...(opts.details ?? []),
+        ], output_1.ExitCode.Usage);
+    }
+    const n = Number(text);
+    if ((opts.min !== undefined && n < opts.min) || (opts.max !== undefined && n > opts.max)) {
+        (0, output_1.fail)(`${flag} must be a whole number${range} — got ${n}.`, opts.details ?? [], output_1.ExitCode.Usage);
+    }
+    return n;
+}
+/**
+ * A rollout percentage, 0-100.
+ *
+ * A trailing `%` is accepted because it is the obvious thing to type for a
+ * value the help text calls a percentage, and refusing it teaches nothing.
+ */
+function checkedPercent(flag, raw, fallback) {
+    const text = raw === undefined || raw === null ? '' : String(raw).trim().replace(/%$/, '');
+    return checkedInt(flag, text, {
+        min: 0,
+        max: 100,
+        fallback,
+        details: ['0 stages the release without serving it to anyone; 100 serves everyone.'],
+    });
+}
+/**
+ * An identifier, or exit.
+ *
+ * Catches the two ways ids arrive broken: an empty value from an unquoted
+ * shell variable that did not expand (`--app-id $APP` with APP unset becomes
+ * `--app-id` swallowing the NEXT flag), and a value with whitespace or a
+ * leading dash from a mis-quoted paste. Both otherwise reach the API and come
+ * back as a confusing 404.
+ */
+function checkedId(flag, raw) {
+    const text = String(raw ?? '').trim();
+    if (!text) {
+        (0, output_1.fail)(`${flag} was given an empty value.`, ['Check the variable it came from is set.'], output_1.ExitCode.Usage);
+    }
+    if (text.startsWith('-')) {
+        (0, output_1.fail)(`${flag} looks like it swallowed the next flag — got "${text}".`, ['An id never starts with "-". Check for a missing value earlier in the command.'], output_1.ExitCode.Usage);
+    }
+    if (/\s/.test(text)) {
+        (0, output_1.fail)(`${flag} must not contain spaces — got "${text}".`, ['Quote the value if it came from a variable.'], output_1.ExitCode.Usage);
+    }
+    return text;
+}
+/**
+ * A semver range the server will accept, or exit.
+ *
+ * Deliberately loose. Ranges legitimately look like `1.0.0`, `^1.0.0`,
+ * `>=1.0.0`, `1.x`, `>=1.0.0 <2.0.0` and `*`, and a strict grammar here would
+ * reject valid input the API would have taken. The check is only for the
+ * shapes that are certainly wrong — empty, or containing no version at all —
+ * because those come back as a 400 describing a field the user never typed.
+ */
+function checkedVersionRange(flag, raw) {
+    const text = String(raw ?? '').trim();
+    if (!text) {
+        (0, output_1.fail)(`${flag} was given an empty value.`, ['Use a range like ">=1.0.0", "^1.2.0" or "1.x".'], output_1.ExitCode.Usage);
+    }
+    if (text !== '*' && !/\d/.test(text)) {
+        (0, output_1.fail)(`${flag} does not look like a version range — got "${text}".`, ['Use a range like ">=1.0.0", "^1.2.0", "1.x", or "*" for any version.'], output_1.ExitCode.Usage);
+    }
+    return text;
+}
+/** Non-empty free text, or exit. Trims, so a whitespace-only value is empty. */
+function checkedText(flag, raw, opts = {}) {
+    const text = String(raw ?? '').trim();
+    if (!text)
+        (0, output_1.fail)(`${flag} was given an empty value.`, [], output_1.ExitCode.Usage);
+    if (opts.max && text.length > opts.max) {
+        (0, output_1.fail)(`${flag} must be ${opts.max} characters or fewer — got ${text.length}.`, [], output_1.ExitCode.Usage);
+    }
+    return text;
+}
+//# sourceMappingURL=validate.js.map

package/lib/utils/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"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"}

package/lib/vendor/ota-protocol/base64.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Standard Base64 for the transport envelope (docs §4).
+ *
+ * Decoding is STRICT and canonical: only the standard alphabet, correct padding,
+ * length a multiple of 4, and — crucially — the decode→re-encode round trip must
+ * reproduce the input exactly. That last check rejects "alternative encodings"
+ * (non-zero unused trailing bits), which is a protocol requirement.
+ */
+export declare function encodeBase64(bytes: Uint8Array): string;
+export declare function decodeBase64Strict(value: string, maxBytes: number, what?: string): Uint8Array;
+//# sourceMappingURL=base64.d.ts.map

package/lib/vendor/ota-protocol/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../../../src/vendor/ota-protocol/base64.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEtD;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,SAAW,GACd,UAAU,CAoBZ"}

package/lib/vendor/ota-protocol/base64.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Standard Base64 for the transport envelope (docs §4).
+ *
+ * Decoding is STRICT and canonical: only the standard alphabet, correct padding,
+ * length a multiple of 4, and — crucially — the decode→re-encode round trip must
+ * reproduce the input exactly. That last check rejects "alternative encodings"
+ * (non-zero unused trailing bits), which is a protocol requirement.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeBase64 = encodeBase64;
+exports.decodeBase64Strict = decodeBase64Strict;
+const types_1 = require("./types");
+const STD_B64 = /^[A-Za-z0-9+/]*={0,2}$/;
+function encodeBase64(bytes) {
+    return Buffer.from(bytes).toString('base64');
+}
+function decodeBase64Strict(value, maxBytes, what = 'base64') {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new types_1.OtaProtocolError('INVALID_BASE64', `${what}: empty or not a string`);
+    }
+    // Reject oversized inputs before allocating (a base64 char is ~0.75 bytes).
+    if (value.length > Math.ceil((maxBytes * 4) / 3) + 4) {
+        throw new types_1.OtaProtocolError('INVALID_BASE64', `${what}: exceeds size limit`);
+    }
+    if (value.length % 4 !== 0 || !STD_B64.test(value)) {
+        throw new types_1.OtaProtocolError('INVALID_BASE64', `${what}: not canonical standard base64`);
+    }
+    const decoded = Buffer.from(value, 'base64');
+    // Buffer.from is lenient; enforce canonical form by re-encoding.
+    if (decoded.toString('base64') !== value) {
+        throw new types_1.OtaProtocolError('INVALID_BASE64', `${what}: non-canonical base64`);
+    }
+    if (decoded.length > maxBytes) {
+        throw new types_1.OtaProtocolError('INVALID_BASE64', `${what}: decoded size exceeds limit`);
+    }
+    return new Uint8Array(decoded);
+}
+//# sourceMappingURL=base64.js.map

package/lib/vendor/ota-protocol/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"","sources":["../../../src/vendor/ota-protocol/base64.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAMH,oCAEC;AAED,gDAwBC;AAhCD,mCAA2C;AAE3C,MAAM,OAAO,GAAG,wBAAwB,CAAC;AAEzC,SAAgB,YAAY,CAAC,KAAiB;IAC5C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED,SAAgB,kBAAkB,CAChC,KAAa,EACb,QAAgB,EAChB,IAAI,GAAG,QAAQ;IAEf,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,wBAAgB,CAAC,gBAAgB,EAAE,GAAG,IAAI,yBAAyB,CAAC,CAAC;IACjF,CAAC;IACD,4EAA4E;IAC5E,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,wBAAgB,CAAC,gBAAgB,EAAE,GAAG,IAAI,sBAAsB,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,wBAAgB,CAAC,gBAAgB,EAAE,GAAG,IAAI,iCAAiC,CAAC,CAAC;IACzF,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC7C,iEAAiE;IACjE,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,KAAK,EAAE,CAAC;QACzC,MAAM,IAAI,wBAAgB,CAAC,gBAAgB,EAAE,GAAG,IAAI,wBAAwB,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,wBAAgB,CAAC,gBAAgB,EAAE,GAAG,IAAI,8BAA8B,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/lib/vendor/ota-protocol/codec.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Byte-exact serializer + bounds-checked parser for the ScaleBunSignedReleaseV1
+ * binary payload. This is the TypeScript REFERENCE implementation; the Kotlin and
+ * Swift verifiers and the backend must match it byte-for-byte against the
+ * committed fixtures. See docs/ota/SB-OTA-RSA-SHA256-V1.md.
+ *
+ * The signature is computed/verified over the exact bytes produced by
+ * {@link serializeSignedRelease}; verifiers must NOT re-serialize a parsed struct.
+ */
+import { ScaleBunSignedReleaseV1 } from './types';
+/** Serialize a signed release, validating every field and the overall limits. */
+export declare function serializeSignedRelease(p: ScaleBunSignedReleaseV1): Uint8Array;
+/**
+ * Parse + fully validate a signed payload. Throws {@link OtaProtocolError} with a
+ * stable code on any structural, enum, range, or consistency violation, on
+ * invalid UTF-8, on an oversized length prefix, and on trailing bytes.
+ */
+export declare function parseSignedRelease(bytes: Uint8Array): ScaleBunSignedReleaseV1;
+/**
+ * Parse ONLY enough of the payload to extract `keyId` (docs §5 step 4/5), so a
+ * verifier can resolve the trusted key before spending an RSA verify. Still fully
+ * bounds-checked. The returned keyId is NOT authenticated until the signature is
+ * verified over the whole payload.
+ */
+export declare function peekKeyId(bytes: Uint8Array): string;
+//# sourceMappingURL=codec.d.ts.map

package/lib/vendor/ota-protocol/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../../src/vendor/ota-protocol/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH,OAAO,EAAoB,uBAAuB,EAAgC,MAAM,SAAS,CAAC;AAqElG,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,uBAAuB,GAAG,UAAU,CAwE7E;AAgED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,uBAAuB,CAkH7E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAmBnD"}

package/lib/vendor/ota-protocol/codec.js

@@ -0,0 +1,349 @@
+"use strict";
+/**
+ * Byte-exact serializer + bounds-checked parser for the ScaleBunSignedReleaseV1
+ * binary payload. This is the TypeScript REFERENCE implementation; the Kotlin and
+ * Swift verifiers and the backend must match it byte-for-byte against the
+ * committed fixtures. See docs/ota/SB-OTA-RSA-SHA256-V1.md.
+ *
+ * The signature is computed/verified over the exact bytes produced by
+ * {@link serializeSignedRelease}; verifiers must NOT re-serialize a parsed struct.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeSignedRelease = serializeSignedRelease;
+exports.parseSignedRelease = parseSignedRelease;
+exports.peekKeyId = peekKeyId;
+const limits_1 = require("./limits");
+const types_1 = require("./types");
+const hex_1 = require("./hex");
+const utf8Encoder = new TextEncoder();
+const utf8DecoderFatal = new TextDecoder('utf-8', { fatal: true });
+// ─── serialize ──────────────────────────────────────────────────────────────
+class ByteWriter {
+    constructor() {
+        this.out = [];
+    }
+    u16(n) {
+        this.out.push((n >>> 8) & 0xff, n & 0xff);
+    }
+    u32(n) {
+        this.out.push((n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff);
+    }
+    u64(n) {
+        let big = BigInt(n);
+        const bytes = new Array(8);
+        for (let i = 7; i >= 0; i--) {
+            bytes[i] = Number(big & 0xffn);
+            big >>= 8n;
+        }
+        this.out.push(...bytes);
+    }
+    bytes(b) {
+        for (let i = 0; i < b.length; i++)
+            this.out.push(b[i]);
+    }
+    lenBytes(b) {
+        this.u32(b.length);
+        this.bytes(b);
+    }
+    string(s) {
+        this.lenBytes(utf8Encoder.encode(s));
+    }
+    finish() {
+        return Uint8Array.from(this.out);
+    }
+}
+function requireEnum(value, allowed, field) {
+    if (!allowed.includes(value)) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `${field}: invalid value ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function requireString(value, field, minLen) {
+    if (typeof value !== 'string') {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `${field}: not a string`);
+    }
+    const byteLen = utf8Encoder.encode(value).length;
+    if (byteLen < minLen) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `${field}: too short`);
+    }
+    if (byteLen > limits_1.MAX_STRING_FIELD_BYTES) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `${field}: exceeds ${limits_1.MAX_STRING_FIELD_BYTES} bytes`);
+    }
+    return value;
+}
+function requireUint(value, field, min = 0) {
+    if (!Number.isInteger(value) || value < min || value > limits_1.MAX_SAFE_UINT64) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `${field}: out of range`);
+    }
+    return value;
+}
+/** Serialize a signed release, validating every field and the overall limits. */
+function serializeSignedRelease(p) {
+    if (p.signatureAlgorithm !== limits_1.SIGNATURE_ALGORITHM) {
+        throw new types_1.OtaProtocolError('UNSUPPORTED_SIGNATURE_ALGORITHM', p.signatureAlgorithm);
+    }
+    if (p.hashAlgorithm !== limits_1.HASH_ALGORITHM) {
+        throw new types_1.OtaProtocolError('UNSUPPORTED_HASH_ALGORITHM', p.hashAlgorithm);
+    }
+    const platform = requireEnum(p.platform, limits_1.PLATFORMS, 'platform');
+    const artifactType = requireEnum(p.artifactType, limits_1.ARTIFACT_TYPES, 'artifactType');
+    requireString(p.keyId, 'keyId', 1);
+    requireString(p.projectId, 'projectId', 1);
+    requireString(p.applicationId, 'applicationId', 1);
+    requireString(p.releaseId, 'releaseId', 1);
+    requireString(p.bundleId, 'bundleId', 1);
+    requireString(p.targetAppVersion, 'targetAppVersion', 0);
+    requireString(p.targetRuntimeVersion, 'targetRuntimeVersion', 0);
+    requireString(p.minimumSdkVersion, 'minimumSdkVersion', 0);
+    requireUint(p.releaseSequence, 'releaseSequence');
+    requireUint(p.issuedAtEpochSeconds, 'issuedAtEpochSeconds', 1);
+    requireUint(p.expiresAtEpochSeconds, 'expiresAtEpochSeconds', 0);
+    requireUint(p.artifactSize, 'artifactSize', 1);
+    if (p.expiresAtEpochSeconds !== 0 && p.expiresAtEpochSeconds < p.issuedAtEpochSeconds) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'expiresAt < issuedAt');
+    }
+    const artifactSha = (0, hex_1.hexToBytes)(p.artifactSha256, limits_1.SHA256_LEN);
+    const resultSha = (0, hex_1.hexToBytes)(p.resultArtifactSha256, limits_1.SHA256_LEN);
+    // full/patch consistency (docs §3.3).
+    let baseBundleId = '';
+    let baseSha = new Uint8Array(0);
+    if (artifactType === 'patch') {
+        baseBundleId = requireString(p.baseBundleId, 'baseBundleId', 1);
+        baseSha = (0, hex_1.hexToBytes)(p.baseArtifactSha256, limits_1.SHA256_LEN);
+    }
+    else {
+        if (p.baseBundleId !== '' || p.baseArtifactSha256 !== '') {
+            throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'full artifact must not carry base fields');
+        }
+    }
+    const w = new ByteWriter();
+    w.bytes(limits_1.MAGIC_BYTES);
+    w.u16(limits_1.SCHEMA_VERSION);
+    w.string(limits_1.SIGNATURE_ALGORITHM);
+    w.string(limits_1.HASH_ALGORITHM);
+    w.string(p.keyId);
+    w.string(p.projectId);
+    w.string(p.applicationId);
+    w.string(p.releaseId);
+    w.string(p.bundleId);
+    w.string(platform);
+    w.string(artifactType);
+    w.string(p.targetAppVersion);
+    w.string(p.targetRuntimeVersion);
+    w.string(p.minimumSdkVersion);
+    w.u64(p.releaseSequence);
+    w.u64(p.issuedAtEpochSeconds);
+    w.u64(p.expiresAtEpochSeconds);
+    w.u64(p.artifactSize);
+    w.bytes(artifactSha);
+    w.string(baseBundleId);
+    w.lenBytes(baseSha);
+    w.bytes(resultSha);
+    const bytes = w.finish();
+    if (bytes.length > limits_1.MAX_SIGNED_PAYLOAD_BYTES) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `payload exceeds ${limits_1.MAX_SIGNED_PAYLOAD_BYTES} bytes`);
+    }
+    return bytes;
+}
+// ─── parse ──────────────────────────────────────────────────────────────────
+class ByteReader {
+    constructor(buf) {
+        this.buf = buf;
+        this.pos = 0;
+    }
+    ensure(n) {
+        if (n < 0 || this.pos + n > this.buf.length) {
+            throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'truncated payload');
+        }
+    }
+    fixed(n) {
+        this.ensure(n);
+        const slice = this.buf.subarray(this.pos, this.pos + n);
+        this.pos += n;
+        return slice;
+    }
+    u16() {
+        const b = this.fixed(2);
+        return (b[0] << 8) | b[1];
+    }
+    u32() {
+        const b = this.fixed(4);
+        // multiplication avoids the sign bit that << would set for values ≥ 2^31.
+        return b[0] * 0x1000000 + (b[1] << 16) + (b[2] << 8) + b[3];
+    }
+    u64() {
+        const b = this.fixed(8);
+        let big = 0n;
+        for (let i = 0; i < 8; i++)
+            big = (big << 8n) | BigInt(b[i]);
+        if (big > BigInt(limits_1.MAX_SAFE_UINT64)) {
+            throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'uint64 exceeds safe range');
+        }
+        return Number(big);
+    }
+    lenBytes(max, field) {
+        const len = this.u32();
+        if (len > max) {
+            throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `${field}: length ${len} exceeds ${max}`);
+        }
+        return this.fixed(len);
+    }
+    string(max, field) {
+        const bytes = this.lenBytes(max, field);
+        try {
+            return utf8DecoderFatal.decode(bytes);
+        }
+        catch {
+            throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `${field}: invalid UTF-8`);
+        }
+    }
+    remaining() {
+        return this.buf.length - this.pos;
+    }
+}
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+/**
+ * Parse + fully validate a signed payload. Throws {@link OtaProtocolError} with a
+ * stable code on any structural, enum, range, or consistency violation, on
+ * invalid UTF-8, on an oversized length prefix, and on trailing bytes.
+ */
+function parseSignedRelease(bytes) {
+    if (!(bytes instanceof Uint8Array)) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'input is not bytes');
+    }
+    if (bytes.length > limits_1.MAX_SIGNED_PAYLOAD_BYTES) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'payload exceeds size limit');
+    }
+    const r = new ByteReader(bytes);
+    const magic = r.fixed(limits_1.MAGIC_BYTES.length);
+    if (!equalBytes(magic, limits_1.MAGIC_BYTES)) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'bad magic');
+    }
+    const schemaVersion = r.u16();
+    if (schemaVersion !== limits_1.SCHEMA_VERSION) {
+        throw new types_1.OtaProtocolError('UNSUPPORTED_SCHEMA', `schemaVersion ${schemaVersion}`);
+    }
+    const signatureAlgorithm = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'signatureAlgorithm');
+    if (signatureAlgorithm !== limits_1.SIGNATURE_ALGORITHM) {
+        throw new types_1.OtaProtocolError('UNSUPPORTED_SIGNATURE_ALGORITHM', signatureAlgorithm);
+    }
+    const hashAlgorithm = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'hashAlgorithm');
+    if (hashAlgorithm !== limits_1.HASH_ALGORITHM) {
+        throw new types_1.OtaProtocolError('UNSUPPORTED_HASH_ALGORITHM', hashAlgorithm);
+    }
+    const keyId = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'keyId');
+    const projectId = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'projectId');
+    const applicationId = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'applicationId');
+    const releaseId = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'releaseId');
+    const bundleId = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'bundleId');
+    for (const [name, v] of [
+        ['keyId', keyId],
+        ['projectId', projectId],
+        ['applicationId', applicationId],
+        ['releaseId', releaseId],
+        ['bundleId', bundleId],
+    ]) {
+        if (v.length === 0)
+            throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `${name}: empty`);
+    }
+    const platformStr = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'platform');
+    if (!limits_1.PLATFORMS.includes(platformStr)) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `platform: ${platformStr}`);
+    }
+    const artifactTypeStr = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'artifactType');
+    if (!limits_1.ARTIFACT_TYPES.includes(artifactTypeStr)) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', `artifactType: ${artifactTypeStr}`);
+    }
+    const platform = platformStr;
+    const artifactType = artifactTypeStr;
+    const targetAppVersion = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'targetAppVersion');
+    const targetRuntimeVersion = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'targetRuntimeVersion');
+    const minimumSdkVersion = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'minimumSdkVersion');
+    const releaseSequence = r.u64();
+    const issuedAtEpochSeconds = r.u64();
+    const expiresAtEpochSeconds = r.u64();
+    const artifactSize = r.u64();
+    if (issuedAtEpochSeconds === 0) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'issuedAt is zero');
+    }
+    if (artifactSize === 0) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'artifactSize is zero');
+    }
+    if (expiresAtEpochSeconds !== 0 && expiresAtEpochSeconds < issuedAtEpochSeconds) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'expiresAt < issuedAt');
+    }
+    const artifactSha256 = (0, hex_1.bytesToHex)(r.fixed(limits_1.SHA256_LEN));
+    const baseBundleId = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'baseBundleId');
+    const baseShaBytes = r.lenBytes(limits_1.SHA256_LEN, 'baseArtifactSha256');
+    const resultArtifactSha256 = (0, hex_1.bytesToHex)(r.fixed(limits_1.SHA256_LEN));
+    // full/patch consistency (docs §3.3).
+    if (artifactType === 'full') {
+        if (baseBundleId.length !== 0 || baseShaBytes.length !== 0) {
+            throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'full artifact carries base fields');
+        }
+    }
+    else {
+        if (baseBundleId.length === 0 || baseShaBytes.length !== limits_1.SHA256_LEN) {
+            throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'patch artifact missing base fields');
+        }
+    }
+    if (r.remaining() !== 0) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'trailing bytes after payload');
+    }
+    return {
+        signatureAlgorithm,
+        hashAlgorithm,
+        keyId,
+        projectId,
+        applicationId,
+        releaseId,
+        bundleId,
+        platform,
+        artifactType,
+        targetAppVersion,
+        targetRuntimeVersion,
+        minimumSdkVersion,
+        releaseSequence,
+        issuedAtEpochSeconds,
+        expiresAtEpochSeconds,
+        artifactSize,
+        artifactSha256,
+        baseBundleId,
+        baseArtifactSha256: baseShaBytes.length === limits_1.SHA256_LEN ? (0, hex_1.bytesToHex)(baseShaBytes) : '',
+        resultArtifactSha256,
+    };
+}
+/**
+ * Parse ONLY enough of the payload to extract `keyId` (docs §5 step 4/5), so a
+ * verifier can resolve the trusted key before spending an RSA verify. Still fully
+ * bounds-checked. The returned keyId is NOT authenticated until the signature is
+ * verified over the whole payload.
+ */
+function peekKeyId(bytes) {
+    if (bytes.length > limits_1.MAX_SIGNED_PAYLOAD_BYTES) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'payload exceeds size limit');
+    }
+    const r = new ByteReader(bytes);
+    const magic = r.fixed(limits_1.MAGIC_BYTES.length);
+    if (!equalBytes(magic, limits_1.MAGIC_BYTES)) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'bad magic');
+    }
+    if (r.u16() !== limits_1.SCHEMA_VERSION) {
+        throw new types_1.OtaProtocolError('UNSUPPORTED_SCHEMA', 'schemaVersion');
+    }
+    r.string(limits_1.MAX_STRING_FIELD_BYTES, 'signatureAlgorithm');
+    r.string(limits_1.MAX_STRING_FIELD_BYTES, 'hashAlgorithm');
+    const keyId = r.string(limits_1.MAX_STRING_FIELD_BYTES, 'keyId');
+    if (keyId.length === 0) {
+        throw new types_1.OtaProtocolError('INVALID_SIGNED_PAYLOAD', 'keyId: empty');
+    }
+    return keyId;
+}
+//# sourceMappingURL=codec.js.map