@fkn/package-manifest 0.1.0

package/build/index.js

@@ -0,0 +1,438 @@
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+//#region src/index.ts
+/** The derivation version, the leading character of every fingerprint and app id. */
+var APP_ID_VERSION = "1";
+/** RFC 4648 base32, lowercase, no padding. Lowercase because DNS folds case. */
+var BASE32_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+/** The whole app id grammar: 61 characters. The api refuses anything else under `fkn:`. */
+var APP_ID = /^fkn:app:1[a-z2-7]{52}$/;
+/** A root fingerprint: the same 53 characters without the `fkn:app:` prefix. */
+var ROOT_FINGERPRINT = /^1[a-z2-7]{52}$/;
+/** An app slug: 1 to 32 characters, permanent. A new slug is a new app. */
+var SLUG = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+/** How far ahead of the verifier's clock an `issuedAt` may sit, so CI and devices judge alike. */
+var ISSUED_AT_TOLERANCE_SECONDS = 300;
+/** The cap on a manifest's UTF-8 length, matching the broker's fetch cap. */
+var MANIFEST_MAX_BYTES = 16384;
+/** The label every signature is domain separated by. */
+var LABELS = {
+	keys: "fkn/app/v1/keys",
+	manifest: "fkn/app/v1/manifest",
+	succeed: "fkn/app/v1/succeed",
+	register: "fkn/app/v1/register"
+};
+var refuse = (code, message) => ({
+	ok: false,
+	code,
+	message
+});
+var encoder = new TextEncoder();
+var utf8 = (text) => encoder.encode(text);
+var concat = (...parts) => {
+	const total = parts.reduce((sum, part) => sum + part.length, 0);
+	const out = new Uint8Array(total);
+	let at = 0;
+	for (const part of parts) {
+		out.set(part, at);
+		at += part.length;
+	}
+	return out;
+};
+var compareBytes = (a, b) => {
+	const shared = Math.min(a.length, b.length);
+	for (let i = 0; i < shared; i++) {
+		const left = a[i];
+		const right = b[i];
+		if (left !== right) return left - right;
+	}
+	return a.length - b.length;
+};
+var sameBytes = (a, b) => compareBytes(a, b) === 0;
+var isBytes = (value) => value instanceof Uint8Array;
+/** RFC 4648 base32, lowercase, no padding. 32 bytes give exactly 52 characters. */
+var base32 = (bytes) => {
+	if (!isBytes(bytes)) throw new TypeError("base32 takes bytes");
+	let value = 0;
+	let bits = 0;
+	let out = "";
+	for (const byte of bytes) {
+		value = value << 8 | byte;
+		bits += 8;
+		while (bits >= 5) {
+			bits -= 5;
+			out += BASE32_ALPHABET[value >>> bits & 31];
+		}
+	}
+	if (bits > 0) out += BASE32_ALPHABET[value << 5 - bits & 31];
+	return out;
+};
+var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Standard base64, padded. The one spelling anything derived from bytes is stored or signed in. */
+var base64 = (bytes) => {
+	let out = "";
+	for (let i = 0; i < bytes.length; i += 3) {
+		const a = bytes[i];
+		const b = bytes[i + 1];
+		const c = bytes[i + 2];
+		out += BASE64_ALPHABET[a >>> 2];
+		out += BASE64_ALPHABET[(a & 3) << 4 | (b ?? 0) >>> 4];
+		out += b === void 0 ? "=" : BASE64_ALPHABET[(b & 15) << 2 | (c ?? 0) >>> 6];
+		out += c === void 0 ? "=" : BASE64_ALPHABET[c & 63];
+	}
+	return out;
+};
+/**
+* Standard base64 to bytes, or null. Padding is optional, so an unpadded input decodes; the
+* url-safe alphabet is NOT accepted, because one key must have one spelling.
+*/
+var fromBase64 = (text) => {
+	if (typeof text !== "string") return null;
+	const body = text.replace(/={0,2}$/, "");
+	if (body.length % 4 === 1) return null;
+	const out = new Uint8Array(Math.floor(body.length * 6 / 8));
+	let value = 0;
+	let bits = 0;
+	let at = 0;
+	for (const char of body) {
+		const index = BASE64_ALPHABET.indexOf(char);
+		if (index === -1) return null;
+		value = value << 6 | index;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out[at++] = value >>> bits & 255;
+		}
+	}
+	return out;
+};
+var bytesOfLength = (value, length) => {
+	if (typeof value !== "string") return null;
+	const bytes = fromBase64(value);
+	return bytes !== null && bytes.length === length ? bytes : null;
+};
+/** `1` + base32(sha256(root)). Throws unless the root is 32 bytes. */
+var rootFingerprintOf = (rootPub) => {
+	if (!isBytes(rootPub) || rootPub.length !== 32) throw new TypeError("A root public key is 32 bytes");
+	return "1" + base32(sha256(rootPub));
+};
+/**
+* `fkn:app:1` + base32(sha256(root || 0x00 || utf8(slug))). Throws on a root that is not 32 bytes
+* or a slug outside the grammar. The id commits to the root, so a different root for one slug is
+* simply a different app.
+*/
+var appIdOf = (rootPub, slug) => {
+	if (!isBytes(rootPub) || rootPub.length !== 32) throw new TypeError("A root public key is 32 bytes");
+	if (typeof slug !== "string" || !SLUG.test(slug)) throw new TypeError(`'${String(slug)}' is not an app slug`);
+	return `fkn:app:1${base32(sha256(concat(rootPub, new Uint8Array([0]), utf8(slug))))}`;
+};
+var NPM_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+var NPM_VERSION = /^[0-9A-Za-z.+-]{1,64}$/;
+var GH_REPO = /^[A-Za-z0-9-_.]+\/[A-Za-z0-9-_.]+$/;
+var GH_REF = /^[A-Za-z0-9-_./]{1,64}$/;
+var HTTPS_HOST = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(:\d{1,5})?$/;
+var HTTPS_PATH = /^\/[A-Za-z0-9\-_.~/]*$/;
+var BASE64URL = /^[A-Za-z0-9\-_]+$/;
+var canonicalSlashes = (rest) => rest.replace(/\/{2,}/g, "/").replace(/\/+$/, "");
+var encodeUriPath = (path) => base64(utf8(path)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+var decodeUriPath = (encoded) => {
+	const bytes = fromBase64(encoded.replace(/-/g, "+").replace(/_/g, "/"));
+	if (bytes === null) return null;
+	const path = Array.from(bytes, (byte) => String.fromCharCode(byte)).join("");
+	return HTTPS_PATH.test(path) && !path.includes("..") ? path : null;
+};
+var npmSource = (rest) => {
+	const at = rest.indexOf("@", rest.startsWith("@") ? 1 : 0);
+	const identifier = at === -1 ? rest : rest.slice(0, at);
+	const version = at === -1 ? null : rest.slice(at + 1);
+	if (!NPM_NAME.test(identifier) || identifier.length > 214) return null;
+	if (version !== null && !NPM_VERSION.test(version)) return null;
+	return `npm:${identifier}`;
+};
+var ghSource = (rest) => {
+	const at = rest.indexOf("@");
+	const identifier = at === -1 ? rest : rest.slice(0, at);
+	const version = at === -1 ? null : rest.slice(at + 1);
+	if (!GH_REPO.test(identifier)) return null;
+	if (version !== null && !GH_REF.test(version)) return null;
+	return `gh:${identifier}`;
+};
+var httpsPackageSource = (rest) => {
+	const at = rest.indexOf("@");
+	const host = at === -1 ? rest : rest.slice(0, at);
+	if (!HTTPS_HOST.test(host) || host.includes("..")) return null;
+	if (at === -1) return `https:${host}`;
+	const encoded = rest.slice(at + 1);
+	if (!BASE64URL.test(encoded)) return null;
+	const decoded = decodeUriPath(encoded);
+	if (decoded === null) return null;
+	const path = canonicalSlashes(decoded) || "/";
+	return path === "/" ? `https:${host}` : `https:${host}@${encodeUriPath(path)}`;
+};
+var httpsOriginSource = (input) => {
+	let url;
+	try {
+		url = new URL(input);
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "https:" || url.username !== "" || url.password !== "") return null;
+	const host = url.port === "" ? url.hostname : `${url.hostname}:${url.port}`;
+	return HTTPS_HOST.test(host) && !host.includes("..") ? `https:${host}` : null;
+};
+/**
+* The one canonical source id a caller id collapses to, or null when the caller can never own an
+* app: `http:`, `localhost:`, a bare name, and every `fkn:` form. Both the broker and the api call
+* this before comparing a source against a manifest's `sources`.
+*/
+var canonicalSourceOf = (callerId) => {
+	if (typeof callerId !== "string" || callerId.length === 0 || callerId.length > 512) return null;
+	const colon = callerId.indexOf(":");
+	if (colon <= 0) return null;
+	const scheme = callerId.slice(0, colon);
+	const rest = callerId.slice(colon + 1);
+	if (scheme === "https") return rest.startsWith("//") ? httpsOriginSource(callerId) : httpsPackageSource(rest);
+	if (scheme === "npm") return npmSource(rest);
+	if (scheme === "gh") return ghSource(rest);
+	return null;
+};
+/**
+* RFC 8785 (JCS): keys sorted by UTF-16 code units, no whitespace, ES6 number serialisation.
+* Throws on `undefined`, a non-finite number, or anything JSON has no form for.
+*/
+var canonicalJson = (value) => {
+	if (value === null) return "null";
+	if (typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new TypeError("canonicalJson refuses a non-finite number");
+		return JSON.stringify(value === 0 ? 0 : value);
+	}
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (typeof value === "object") {
+		const object = value;
+		return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+	}
+	throw new TypeError(`canonicalJson refuses a ${typeof value}`);
+};
+/**
+* The member set of a key list: each entry base64 of exactly 32 bytes, sorted bytewise, named once,
+* 1 to 64 of them, and never the root, because the key that names an app must not sign its releases.
+*/
+var memberSetOf = (members, rootPub) => {
+	if (!isBytes(rootPub) || rootPub.length !== 32) throw new TypeError("A root public key is 32 bytes");
+	if (!Array.isArray(members)) return refuse("KEYS_MEMBERS", "A key list names its members as an array");
+	if (members.length === 0) return refuse("KEYS_MEMBERS", "A key list names at least one member");
+	if (members.length > 64) return refuse("KEYS_MEMBERS", "A key list names at most 64 members");
+	const decoded = [];
+	for (const member of members) {
+		const bytes = bytesOfLength(member, 32);
+		if (bytes === null) return refuse("KEYS_MEMBERS", "Every member is base64 of a 32 byte public key");
+		if (sameBytes(bytes, rootPub)) return refuse("KEYS_MEMBERS", "The root is never a member of its own key list");
+		decoded.push(bytes);
+	}
+	decoded.sort(compareBytes);
+	let previous = null;
+	for (const member of decoded) {
+		if (previous !== null && sameBytes(previous, member)) return refuse("KEYS_MEMBERS", "A key list names each member once");
+		previous = member;
+	}
+	return decoded;
+};
+/**
+* `fkn/app/v1/keys\0<app>\0<serial>\0` followed by the canonical JSON of the member set in standard
+* padded base64. The re-encoding is what lets an unpadded input sign the same bytes, and the signer
+* builds the statement through this same function.
+*/
+var keyListStatement = (appId, serial, members) => {
+	if (!APP_ID.test(appId)) throw new TypeError(`'${String(appId)}' is not an app id`);
+	if (!Number.isSafeInteger(serial) || serial < 0) throw new TypeError("A key list serial is a non-negative safe integer");
+	const sorted = [...members].sort(compareBytes);
+	for (const member of sorted) if (!isBytes(member) || member.length !== 32) throw new TypeError("A key list member is 32 bytes");
+	return concat(utf8(`${LABELS.keys}\0${appId}\0${serial}\0`), utf8(canonicalJson(sorted.map(base64))));
+};
+/**
+* `fkn/app/v1/manifest\0` followed by the canonical JSON of the manifest WITHOUT its `sig`. Throws
+* when `sig` is still present, because the quiet version of that mistake is a statement nobody can
+* reproduce.
+*/
+var manifestStatement = (manifestWithoutSig) => {
+	if (manifestWithoutSig === null || typeof manifestWithoutSig !== "object" || Array.isArray(manifestWithoutSig)) throw new TypeError("A manifest statement is built over an object");
+	if ("sig" in manifestWithoutSig) throw new TypeError("A manifest statement excludes sig");
+	return concat(utf8(`${LABELS.manifest}\0`), utf8(canonicalJson(manifestWithoutSig)));
+};
+/** `fkn/app/v1/succeed\0<old>\0<new>`, signed by the OLD root and by nothing else. */
+var succeedStatement = (oldId, newId) => {
+	if (!APP_ID.test(oldId) || !APP_ID.test(newId)) throw new TypeError("A succession names two app ids");
+	return utf8(`${LABELS.succeed}\0${oldId}\0${newId}`);
+};
+/** `fkn/app/v1/register\0<challenge>`, signed by the root proving itself once at registration. */
+var registerStatement = (challengeId) => {
+	if (typeof challengeId !== "string" || challengeId.length === 0 || challengeId.length > 256 || challengeId.includes("\0")) throw new TypeError("A registration challenge is 1 to 256 characters and carries no NUL");
+	return utf8(`${LABELS.register}\0${challengeId}`);
+};
+/**
+* The single verification path. `zip215: false` is RFC 8032 / FIPS 186-5 rules; noble's ed25519
+* default is the permissive ZIP-215 one, which accepts non-canonical encodings and small-order keys,
+* so the option is what decides acceptance and is never left off.
+*/
+var verifySignature = (statement, sig, pub) => {
+	try {
+		return ed25519.verify(sig, statement, pub, { zip215: false });
+	} catch {
+		return false;
+	}
+};
+/**
+* The root's word on who may sign this app's manifests. Verifies the presented list; adoption and
+* membership order are the caller's, because only a store knows which list it holds.
+*/
+var verifyKeyList = (keys, rootPub, appId) => {
+	if (keys === null || typeof keys !== "object" || Array.isArray(keys)) return refuse("MALFORMED", "keys is an object");
+	const record = keys;
+	const serial = record["serial"];
+	if (typeof serial !== "number" || !Number.isSafeInteger(serial) || serial < 0) return refuse("MALFORMED", "keys.serial is a non-negative safe integer");
+	const members = memberSetOf(record["members"], rootPub);
+	if (!Array.isArray(members)) return members;
+	const sig = bytesOfLength(record["sig"], 64);
+	if (sig === null) return refuse("MALFORMED", "keys.sig is base64 of 64 bytes");
+	if (!verifySignature(keyListStatement(appId, serial, members), sig, rootPub)) return refuse("KEYS_SIG", "keys.sig is not the root's signature over this key list");
+	return {
+		serial,
+		members,
+		membersB64: members.map(base64),
+		sig: base64(sig)
+	};
+};
+/**
+* One succession entry. The old id is DERIVED from the old root and slug the entry carries, so an
+* app can never name an id it cannot prove; only the old root can produce the signature.
+*/
+var verifyPrevious = (entry, newAppId) => {
+	if (!APP_ID.test(newAppId)) throw new TypeError(`'${String(newAppId)}' is not an app id`);
+	if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return refuse("BAD_PREVIOUS", "A previous entry is an object");
+	const record = entry;
+	const root = bytesOfLength(record["root"], 32);
+	if (root === null) return refuse("BAD_PREVIOUS", "previous.root is base64 of 32 bytes");
+	const slug = record["slug"];
+	if (typeof slug !== "string" || !SLUG.test(slug)) return refuse("BAD_PREVIOUS", "previous.slug is not an app slug");
+	const oldId = record["app"];
+	if (typeof oldId !== "string" || !APP_ID.test(oldId)) return refuse("BAD_PREVIOUS", "previous.app is not an app id");
+	if (oldId !== appIdOf(root, slug)) return refuse("BAD_PREVIOUS", "previous.app is not the id of its own root and slug");
+	if (oldId === newAppId) return refuse("BAD_PREVIOUS", "An app cannot succeed itself");
+	const sig = bytesOfLength(record["sig"], 64);
+	if (sig === null) return refuse("BAD_PREVIOUS", "previous.sig is base64 of 64 bytes");
+	if (!verifySignature(succeedStatement(oldId, newAppId), sig, root)) return refuse("BAD_PREVIOUS", "previous.sig is not the old root's signature over this succession");
+	return {
+		oldId,
+		root,
+		slug
+	};
+};
+var textOf = (raw) => {
+	try {
+		const text = JSON.stringify(raw);
+		return typeof text === "string" ? text : refuse("MALFORMED", "A manifest is a JSON object");
+	} catch {
+		return refuse("MALFORMED", "A manifest is a JSON object");
+	}
+};
+/**
+* Every stateless check, in one order, over a manifest's text or its already-parsed value. The
+* caller supplies `now` in unix seconds; `source` and `webOrigin` are the api's two extra checks and
+* are skipped when absent. Everything a store decides (key list adoption, the newest manifest's
+* sources, the freshness window) stays with the caller.
+*/
+var verifyManifest = (raw, opts) => {
+	if (typeof opts.now !== "number" || !Number.isFinite(opts.now)) throw new TypeError("verifyManifest needs a numeric now");
+	let value;
+	let text;
+	if (typeof raw === "string") {
+		if (utf8(raw).length > 16384) return refuse("MALFORMED", `A manifest is at most ${MANIFEST_MAX_BYTES} bytes`);
+		try {
+			value = JSON.parse(raw);
+		} catch {
+			return refuse("MALFORMED", "A manifest is JSON");
+		}
+		text = raw;
+	} else {
+		value = raw;
+		const serialised = textOf(raw);
+		if (typeof serialised !== "string") return serialised;
+		if (utf8(serialised).length > 16384) return refuse("MALFORMED", `A manifest is at most ${MANIFEST_MAX_BYTES} bytes`);
+		text = serialised;
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return refuse("MALFORMED", "A manifest is a JSON object");
+	const manifest = value;
+	if (typeof manifest["v"] !== "number") return refuse("MALFORMED", "A manifest carries a numeric v");
+	if (manifest["v"] !== 1) return refuse("UNKNOWN_VERSION", `Manifest version ${String(manifest["v"])} is not known here`);
+	if (manifest["app"] === null) return {
+		ok: true,
+		kind: "released"
+	};
+	const root = bytesOfLength(manifest["root"], 32);
+	if (root === null) return refuse("BAD_ROOT", "root is base64 of a 32 byte public key");
+	const slug = manifest["slug"];
+	if (typeof slug !== "string" || !SLUG.test(slug)) return refuse("BAD_SLUG", `'${String(slug)}' is not an app slug`);
+	const app = manifest["app"];
+	if (typeof app !== "string" || !APP_ID.test(app)) return refuse("BAD_APP_ID", `'${String(app)}' is not an app id`);
+	if (app !== appIdOf(root, slug)) return refuse("BAD_APP_ID", "app is not the id of its own root and slug");
+	const key = bytesOfLength(manifest["key"], 32);
+	if (key === null) return refuse("MALFORMED", "key is base64 of a 32 byte public key");
+	const sources = manifest["sources"];
+	if (!Array.isArray(sources) || sources.length === 0 || sources.length > 32) return refuse("MALFORMED", "sources names 1 to 32 canonical source ids");
+	for (const source of sources) if (typeof source !== "string" || canonicalSourceOf(source) !== source) return refuse("MALFORMED", `'${String(source)}' is not a canonical source id`);
+	if (new Set(sources).size !== sources.length) return refuse("MALFORMED", "sources names each source once");
+	const rawName = manifest["name"];
+	if (rawName !== void 0 && (typeof rawName !== "string" || rawName.length === 0 || rawName.length > 64)) return refuse("MALFORMED", "name is 1 to 64 characters");
+	const name = rawName === void 0 ? null : rawName;
+	const issuedAt = manifest["issuedAt"];
+	if (typeof issuedAt !== "number" || !Number.isSafeInteger(issuedAt) || issuedAt < 0) return refuse("MALFORMED", "issuedAt is a non-negative safe integer");
+	const rawPrevious = manifest["previous"];
+	const previousEntries = [];
+	if (rawPrevious !== void 0) {
+		if (!Array.isArray(rawPrevious) || rawPrevious.length > 8) return refuse("MALFORMED", "previous names at most 8 apps");
+		previousEntries.push(...rawPrevious);
+	}
+	const sig = bytesOfLength(manifest["sig"], 64);
+	if (sig === null) return refuse("MALFORMED", "sig is base64 of 64 bytes");
+	const keys = verifyKeyList(manifest["keys"], root, app);
+	if ("ok" in keys) return keys;
+	if (!keys.members.some((member) => sameBytes(member, key))) return refuse("KEY_NOT_MEMBER", "key is not a member of the key list this manifest carries");
+	const withoutSig = { ...manifest };
+	delete withoutSig["sig"];
+	let statement;
+	try {
+		statement = manifestStatement(withoutSig);
+	} catch {
+		return refuse("MALFORMED", "A manifest carries only JSON values");
+	}
+	if (!verifySignature(statement, sig, key)) return refuse("BAD_SIG", "sig is not key's signature over this manifest");
+	if (opts.source !== void 0 && !sources.includes(opts.source)) return refuse("SOURCE_NOT_LISTED", `'${opts.source}' is not one of this manifest's sources`);
+	if (issuedAt > opts.now + 300) return refuse("ISSUED_AT_FUTURE", `issuedAt is more than 300 seconds ahead`);
+	if (opts.webOrigin !== void 0) {
+		const webSource = canonicalSourceOf(opts.webOrigin);
+		if (webSource !== null && sources.includes(webSource)) return refuse("WEB_ORIGIN_SOURCE", `'${webSource}' is the web origin and can never be an app's source`);
+	}
+	const previous = [];
+	for (const entry of previousEntries) {
+		const verified = verifyPrevious(entry, app);
+		if ("ok" in verified) return verified;
+		previous.push(verified);
+	}
+	return {
+		ok: true,
+		kind: "manifest",
+		app,
+		root,
+		slug,
+		key,
+		keys,
+		sources,
+		name,
+		issuedAt,
+		previous,
+		raw: text
+	};
+};
+//#endregion
+export { APP_ID, APP_ID_VERSION, BASE32_ALPHABET, ISSUED_AT_TOLERANCE_SECONDS, LABELS, MANIFEST_MAX_BYTES, ROOT_FINGERPRINT, SLUG, appIdOf, base32, base64, canonicalJson, canonicalSourceOf, fromBase64, keyListStatement, manifestStatement, memberSetOf, registerStatement, rootFingerprintOf, succeedStatement, verifyKeyList, verifyManifest, verifyPrevious, verifySignature };