@formancy/data-server 0.0.0-stage → 0.1.0

package/dist/secrets-DhKHG-Y9.mjs

@@ -0,0 +1,689 @@
+import { KeyObject, createPublicKey, createSecretKey } from "node:crypto";
+import { open, readFile } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { errors, exportJWK, importSPKI, jwtVerify } from "jose";
+import { constants } from "node:fs";
+//#region src/ed25519.ts
+/**
+* What an Ed25519 public key's 32 bytes are, as far as a verifier has to ask
+* (0059): a point on the curve, and whether it is one of small order.
+*
+* createPublicKey imports every point of small order, and under such a key a
+* signature nobody made verifies: R the identity and S zero verified 64
+* messages of 64 under the identity, and 34 of 64 under the point of order 2
+* (Node 22.22.1, 2026-10-13). A key A is of small order exactly when [8]A,
+* its multiple by the curve's cofactor, is the identity, which is what this
+* computes from the curve itself: no list of points is transcribed.
+*/
+const P = 2n ** 255n - 19n;
+function mod(value) {
+	const rest = value % P;
+	return rest < 0n ? rest + P : rest;
+}
+function power(base, exponent) {
+	let result = 1n;
+	let square = mod(base);
+	for (let rest = exponent; rest > 0n; rest >>= 1n) {
+		if ((rest & 1n) === 1n) result = result * square % P;
+		square = square * square % P;
+	}
+	return result;
+}
+/** d = -121665/121666 (RFC 8032 section 5.1). */
+const D = mod(-121665n * power(121666n, P - 2n));
+/** A square root of -1 modulo p (RFC 8032 section 5.1.3). */
+const ROOT_OF_MINUS_ONE = power(2n, (P - 1n) / 4n);
+/**
+* The point an encoding names, or undefined when it names none (RFC 8032
+* section 5.1.3). y is read modulo p, as OpenSSL reads it, where the RFC
+* refuses y at or above p: such a key is what the server would verify with.
+*/
+function decode(bytes) {
+	let y = 0n;
+	for (let index = 31; index >= 0; index--) y = y << 8n | BigInt(index === 31 ? bytes[index] & 127 : bytes[index]);
+	y = mod(y);
+	const sign = BigInt(bytes[31] >> 7);
+	const u = mod(y * y - 1n);
+	const v = mod(D * y * y + 1n);
+	let x = mod(u * power(v, 3n) * power(u * power(v, 7n), (P - 5n) / 8n));
+	const check = mod(v * x * x);
+	if (check === mod(-u)) x = mod(x * ROOT_OF_MINUS_ONE);
+	else if (check !== u) return void 0;
+	if (x === 0n && sign === 1n) return void 0;
+	if ((x & 1n) !== sign) x = P - x;
+	return {
+		x,
+		y
+	};
+}
+/** [8]A in projective coordinates, by doubling three times (a = -1; dbl-2008-hwcd), and whether it is the identity. */
+function eightTimesIsIdentity({ x, y }) {
+	let [X, Y, Z] = [
+		x,
+		y,
+		1n
+	];
+	for (let doubling = 0; doubling < 3; doubling++) {
+		const A = mod(X * X);
+		const B = mod(Y * Y);
+		const C = mod(2n * Z * Z);
+		const E = mod((X + Y) * (X + Y) - A - B);
+		const G = mod(B - A);
+		const F = mod(G - C);
+		const H = mod(-A - B);
+		[X, Y, Z] = [
+			mod(E * F),
+			mod(G * H),
+			mod(F * G)
+		];
+	}
+	return X === 0n && Y === Z;
+}
+/** What the 32 bytes of an Ed25519 public key are: a JWK's `x`, once createPublicKey has imported it, which refuses any other length. */
+function ed25519Point(bytes) {
+	const point = decode(bytes);
+	if (point === void 0) return "no point";
+	return eightTimesIsIdentity(point) ? "small order" : "a point";
+}
+//#endregion
+//#region src/identity-keys.ts
+/**
+* The keys a host identity token is verified with (0014, 0059): one shared
+* secret, one public key, or a JSON Web Key Set read from a file, each of its
+* keys selected by the kid a token names.
+*
+* A `KeySet` is opaque. Its constructor refuses every caller but the
+* builders below, which check what they are given, so a set the verifier
+* meets is always one that `readKeySet`, `KeySet.fromSecret` or
+* `KeySet.fromPem` made: one algorithm, public keys or long secrets, every kid
+* distinct.
+*
+* Nothing a sentence here says comes from the file. JSON.parse's own message
+* quotes the text around the error, and the text may be a secret, so a file
+* that does not parse gets one fixed sentence; every other sentence names a
+* key by its kid, when that is in the alphabet below and could not be a
+* secret, or by its place in the file, and names a member, never its value.
+*
+* The class, its prototype and every set are frozen, and a set is verified
+* with only through `verifyWithKeySet`, which index.ts does not export: code
+* that reaches the class can replace none of its methods, and no caller can
+* verify under a set with looser options than identity.ts passes.
+*/
+const KEY_SET_ALGORITHMS = [
+	"RS256",
+	"ES256",
+	"EdDSA",
+	"HS256"
+];
+function isKeySetAlgorithm(value) {
+	return KEY_SET_ALGORITHMS.some((algorithm) => algorithm === value);
+}
+/** jose's floor for RS256, which it checks only when a token arrives; a set is refused for it when it is read. */
+const MIN_RSA_BITS = 2048;
+/**
+* The least RSA public exponent a key in force may have: FIPS 186's floor for
+* an RSA key pair is an odd e above 2^16. createPublicKey imports e = 1, under
+* which a signature is its own message's padding and anyone signs any token.
+*/
+const MIN_RSA_EXPONENT = 65537n;
+/** A sentence saying why a set was refused. It holds no text of the file, so it may be logged. */
+var KeySetRefusal = class extends Error {
+	name = "KeySetRefusal";
+};
+/**
+* The alphabet of a kid that may be named in a sentence: base64 and base64url,
+* and the punctuation providers use. Anchored, one class, so nothing in it
+* backtracks.
+*/
+const KID = /^[A-Za-z0-9._~+/=-]+$/;
+/** The key types of a public key. A kid beside one is a name, often a 43-character thumbprint, as Keycloak's are. */
+const PUBLIC_KEY_TYPES = [
+	"RSA",
+	"EC",
+	"OKP"
+];
+/** As many base64 characters as a secret HS256 takes: 32 bytes are 43 of them. */
+const SECRET_CHARACTERS = Math.ceil(256 / 6);
+const BASE64_CHARACTER = /[A-Za-z0-9_+/-]/g;
+/** Private key members (RFC 7518 section 6, and AKP's `priv`). Their presence in a verifier's file refuses the whole set. */
+const PRIVATE_MEMBERS = [
+	"d",
+	"p",
+	"q",
+	"dp",
+	"dq",
+	"qi",
+	"oth",
+	"priv"
+];
+/** What a key must be to verify each algorithm. */
+const VERIFIES = {
+	RS256: {
+		kty: "RSA",
+		kind: "an RSA"
+	},
+	ES256: {
+		kty: "EC",
+		crv: "P-256",
+		kind: "an EC"
+	},
+	EdDSA: {
+		kty: "OKP",
+		crv: "Ed25519",
+		kind: "an Ed25519"
+	},
+	HS256: {
+		kty: "oct",
+		kind: "a secret"
+	}
+};
+/** Only the builders hold this, so only they can call the constructor. */
+const BUILD = Symbol("KeySet builder");
+function isEntry(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Whether a kid could be key material: one beside a key that is not a public
+* key, that is its own `k` or holds as many base64 characters as a secret.
+* Every kid fits the alphabet a secret is written in, and a kid is logged --
+* in a sentence, and on the planes and SIGHUP lines -- so a secret pasted
+* where the kid belongs would reach the log through it.
+*/
+function kidCouldBeSecret(entry) {
+	const kid = entry["kid"];
+	if (typeof kid !== "string" || PUBLIC_KEY_TYPES.includes(entry["kty"])) return false;
+	return kid === entry["k"] || (kid.match(BASE64_CHARACTER)?.length ?? 0) >= SECRET_CHARACTERS;
+}
+/** A key as a sentence names it: `"kid"` when its kid is in the alphabet and could not be a secret, otherwise `#n`, its place in the file from 1. */
+function nameOf(entry, index) {
+	return typeof entry["kid"] === "string" && KID.test(entry["kid"]) && !kidCouldBeSecret(entry) ? entry["kid"] : `#${String(index + 1)}`;
+}
+function quoted(name) {
+	return name.startsWith("#") ? name : `"${name}"`;
+}
+/**
+* Why a key cannot verify `algorithm`, or why its publisher says it is not for
+* that, as the member that says so; undefined when it is in force. `use` is
+* asked before `alg`, because what a key is for is what its publisher says
+* first: Keycloak's encryption key says both.
+*/
+function leftOutBecause(entry, algorithm) {
+	const wanted = VERIFIES[algorithm];
+	if (entry["kty"] !== wanted.kty) return "kty";
+	if (wanted.crv !== void 0 && entry["crv"] !== wanted.crv) return "crv";
+	if (entry["use"] !== void 0 && entry["use"] !== "sig") return "use";
+	const ops = entry["key_ops"];
+	if (ops !== void 0 && !(Array.isArray(ops) && ops.includes("verify"))) return "key_ops";
+	if (entry["alg"] !== void 0 && entry["alg"] !== algorithm) return "alg";
+}
+/**
+* The key, imported now and synchronously, so a set that cannot verify is
+* refused when it is read rather than at its first token: an off-curve point
+* is refused by createPublicKey, where jose would refuse it only then, and an
+* RSA modulus is measured from the imported key, because createPublicKey
+* imports one of no bits at all (M4). A key under which anyone can sign --
+* an RSA exponent of 1, an Ed25519 point of small order -- imports too, and is
+* refused here.
+*/
+function importKey(entry, algorithm, kid) {
+	const name = quoted(kid);
+	if (algorithm === "HS256") {
+		const k = entry["k"];
+		if (typeof k !== "string") throw new KeySetRefusal(`key ${name} has no "k"`);
+		const bytes = Buffer.from(k, "base64url");
+		if (bytes.toString("base64url") !== k) throw new KeySetRefusal(`key ${name}'s "k" is not base64url without padding`);
+		if (bytes.length < 32) throw new KeySetRefusal(`key ${name} is shorter than ${String(32)} bytes, which HS256 needs (0014)`);
+		return createSecretKey(bytes);
+	}
+	let key;
+	try {
+		key = createPublicKey({
+			key: entry,
+			format: "jwk"
+		});
+	} catch {
+		throw new KeySetRefusal(`key ${name} does not import as ${VERIFIES[algorithm].kind} public key`);
+	}
+	if (algorithm === "RS256") {
+		const details = key.asymmetricKeyDetails;
+		if ((details?.modulusLength ?? 0) < MIN_RSA_BITS) throw new KeySetRefusal(`key ${name} is an RSA key of fewer than ${String(MIN_RSA_BITS)} bits, which RS256 refuses`);
+		const exponent = details?.publicExponent ?? 0n;
+		if (exponent < MIN_RSA_EXPONENT || exponent % 2n === 0n) throw new KeySetRefusal(`key ${name}'s RSA public exponent is not an odd number of at least ${String(MIN_RSA_EXPONENT)}: under an exponent of 1 anyone signs any token`);
+	}
+	if (algorithm === "EdDSA") {
+		const point = ed25519Point(Buffer.from(String(entry["x"]), "base64url"));
+		if (point === "no point") throw new KeySetRefusal(`key ${name} does not import as ${VERIFIES[algorithm].kind} public key`);
+		if (point === "small order") throw new KeySetRefusal(`key ${name} is an Ed25519 point of small order, under which a signature nobody made verifies`);
+	}
+	return key;
+}
+function signatureFailed(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED";
+}
+let branded;
+let verifyUnder;
+var KeySet = class KeySet {
+	#algorithm;
+	/** A set read from a file: its keys in force, in file order, each selected by its kid. */
+	#keys;
+	#leftOut;
+	/** A one-key setting's key, which ignores a token's kid as it always has. */
+	#single;
+	constructor(build, algorithm, keys, leftOut, single) {
+		if (build !== BUILD) throw new TypeError("a KeySet is made by readKeySet, KeySet.fromSecret or KeySet.fromPem");
+		this.#algorithm = algorithm;
+		this.#keys = keys;
+		this.#leftOut = leftOut;
+		this.#single = single;
+		Object.freeze(this);
+	}
+	static {
+		branded = (value) => typeof value === "object" && value !== null && #keys in value;
+		verifyUnder = (set, token, options) => set.#verify(token, options);
+	}
+	/**
+	* A JSON Web Key Set, `{"keys":[…]}`, read for one algorithm. Throws a
+	* `KeySetRefusal` for an algorithm not one of the four, a file that does
+	* not parse, an entry that is not an object, any key holding a private
+	* member, a key in force without a kid in the alphabet, with another's kid
+	* or with one that could be a secret, one that does not import, an RSA key
+	* under 2048 bits or with an exponent under 65537 or even, an Ed25519 point
+	* of small order, a secret under 32 bytes, and a file with no key in force.
+	* A key that cannot verify the algorithm is left out and named.
+	*/
+	static read(text, algorithm) {
+		if (!isKeySetAlgorithm(algorithm)) throw new KeySetRefusal("the algorithm of a key set is RS256, ES256, EdDSA or HS256");
+		let document;
+		try {
+			document = JSON.parse(text);
+		} catch {
+			throw new KeySetRefusal("the identity key set file is not JSON");
+		}
+		const entries = isEntry(document) ? document["keys"] : void 0;
+		if (!Array.isArray(entries) || entries.length === 0) throw new KeySetRefusal("the identity key set is not an object with a non-empty \"keys\" array");
+		const checked = entries.map((entry, index) => {
+			if (!isEntry(entry)) throw new KeySetRefusal(`key #${String(index + 1)} of the identity key set is not an object`);
+			const member = PRIVATE_MEMBERS.find((candidate) => entry[candidate] !== void 0);
+			if (member !== void 0) throw new KeySetRefusal(`key ${quoted(nameOf(entry, index))} holds the private member "${member}": a verifier's file holds public keys only`);
+			return entry;
+		});
+		const inForce = [];
+		const leftOut = [];
+		for (const [index, entry] of checked.entries()) {
+			const because = leftOutBecause(entry, algorithm);
+			if (because !== void 0) {
+				leftOut.push({
+					key: nameOf(entry, index),
+					because
+				});
+				continue;
+			}
+			const kid = entry["kid"];
+			if (kid === void 0) throw new KeySetRefusal(`key #${String(index + 1)} has no "kid": a key in force is selected by it`);
+			if (typeof kid !== "string" || !KID.test(kid)) throw new KeySetRefusal(`key #${String(index + 1)}'s "kid" is not a non-empty string of A-Z, a-z, 0-9 and . _ ~ + / = -`);
+			if (kidCouldBeSecret(entry)) throw new KeySetRefusal(`key #${String(index + 1)}'s "kid" could be a secret -- it is its "k", or ${String(SECRET_CHARACTERS)} base64 characters or more -- and a kid is logged, so it is a name, never key material`);
+			if (inForce.some((other) => other.kid === kid)) throw new KeySetRefusal(`two keys in force are both "${kid}": a kid selects one key`);
+			inForce.push({
+				kid,
+				key: importKey(entry, algorithm, kid)
+			});
+		}
+		if (inForce.length === 0) throw new KeySetRefusal(`no key in the file can verify ${algorithm} (left out: ${leftOut.map((key) => `${key.key} (${key.because})`).join(", ")})`);
+		return new KeySet(BUILD, algorithm, inForce, leftOut, void 0);
+	}
+	/** `FORMANCY_DATA_IDENTITY_SECRET`'s key: HS256 over the secret's UTF-8 bytes, at least 32 of them. */
+	static fromSecret(secret) {
+		if (Buffer.byteLength(secret, "utf8") < 32) throw new KeySetRefusal(`the identity secret must be at least ${String(32)} bytes`);
+		return new KeySet(BUILD, "HS256", [], [], createSecretKey(Buffer.from(secret, "utf8")));
+	}
+	/** `FORMANCY_DATA_IDENTITY_PUBLIC_KEY_FILE`'s key: an SPKI PEM, imported by jose as it always was, for RS256, ES256 or EdDSA and never HS256. */
+	static async fromPem(pem, algorithm) {
+		if (algorithm !== "RS256" && algorithm !== "ES256" && algorithm !== "EdDSA") throw new KeySetRefusal("a public key verifies RS256, ES256 or EdDSA: HS256 is a shared secret, never a public key");
+		let key;
+		try {
+			key = await importSPKI(pem, algorithm);
+		} catch {
+			throw new KeySetRefusal(`the identity public key is not an SPKI PEM public key for ${algorithm}`);
+		}
+		return new KeySet(BUILD, algorithm, [], [], key);
+	}
+	/** Whether `value` is a set the builders made. A brand check, so neither a look-alike nor an object made from the prototype passes. */
+	static is(value) {
+		return branded(value);
+	}
+	get algorithm() {
+		return this.#algorithm;
+	}
+	/** The kids in force, in file order; none for a one-key setting, which ignores kids. */
+	get kids() {
+		return this.#keys.map((entry) => entry.kid);
+	}
+	get leftOut() {
+		return this.#leftOut;
+	}
+	/** The type of each key in force, `public` or `secret`: what a test can ask of a key without being handed it. */
+	get keyTypes() {
+		return this.#single === void 0 ? this.#keys.map((entry) => entry.key.type) : [this.#single.type];
+	}
+	/** What `next` adds, removes and replaces of this set's kids. A key is replaced when its kid stays and its key does not. */
+	compare(next) {
+		const before = new Map(this.#keys.map((entry) => [entry.kid, entry.key]));
+		const after = new Map(next.#keys.map((entry) => [entry.kid, entry.key]));
+		return {
+			added: [...after.keys()].filter((kid) => !before.has(kid)),
+			removed: [...before.keys()].filter((kid) => !after.has(kid)),
+			replaced: [...after].filter(([kid, key]) => before.has(kid) && !before.get(kid).equals(key)).map(([kid]) => kid)
+		};
+	}
+	/**
+	* A one-key setting's key as a key set file holding it under `kid`: what
+	* `identity-keys-cli.mjs convert` writes. The secret's key is the base64url
+	* of the bytes this set verifies with, not the secret's text, which is also
+	* valid base64url and another key (M2). Read back before it is returned.
+	* This is key material; nothing logs it.
+	*/
+	async document(kid) {
+		const single = this.#single;
+		if (single === void 0) throw new KeySetRefusal("a set read from a file is a key set file already");
+		if (!KID.test(kid)) throw new KeySetRefusal("a kid is a non-empty string of A-Z, a-z, 0-9 and . _ ~ + / = -");
+		const { kty, ...material } = single instanceof KeyObject && single.type === "secret" ? {
+			kty: "oct",
+			k: single.export().toString("base64url")
+		} : await exportJWK(single);
+		const text = `${JSON.stringify({ keys: [{
+			kty,
+			kid,
+			alg: this.#algorithm,
+			...material
+		}] }, null, 2)}\n`;
+		KeySet.read(text, this.#algorithm);
+		return text;
+	}
+	/**
+	* jwtVerify under this set, its algorithm pinned. A one-key setting's key is
+	* the key, as it always was. A set's key is chosen inside jwtVerify by its
+	* key resolver, which jose calls only after it has refused a malformed
+	* token or another algorithm, so those keep their codes (M5):
+	*
+	* - a kid that is a string selects that key and no other, and one the set
+	*   does not hold is `ERR_JWKS_NO_MATCHING_KEY`, even when another key
+	*   would verify;
+	* - no kid: each key in force in file order, moving on only past a
+	*   signature that does not verify, as PostgREST does; any other refusal
+	*   (expired, another audience, a missing claim) is the answer.
+	*
+	* No member of the token's header but its kid chooses a key: one that
+	* carries a `jwk`, or names a `jku` or `x5u`, is verified against the set
+	* alone (identity.test.ts).
+	*/
+	async #verify(token, options) {
+		const pinned = {
+			...options,
+			algorithms: [this.#algorithm]
+		};
+		if (this.#single !== void 0) return jwtVerify(token, this.#single, pinned);
+		const keys = this.#keys;
+		let kidless = false;
+		const select = (header) => {
+			const { kid } = header;
+			if (kid === void 0) {
+				kidless = true;
+				return keys[0].key;
+			}
+			if (typeof kid !== "string") throw new errors.JWSInvalid("the token's \"kid\" is not a string");
+			const selected = keys.find((entry) => entry.kid === kid);
+			if (selected === void 0) throw new errors.JWKSNoMatchingKey();
+			return selected.key;
+		};
+		try {
+			return await jwtVerify(token, select, pinned);
+		} catch (error) {
+			if (!kidless || !signatureFailed(error)) throw error;
+		}
+		for (const { key } of keys.slice(1)) try {
+			return await jwtVerify(token, key, pinned);
+		} catch (error) {
+			if (!signatureFailed(error)) throw error;
+		}
+		throw new errors.JWSSignatureVerificationFailed();
+	}
+};
+Object.freeze(KeySet.prototype);
+Object.freeze(KeySet);
+/** The one function that checks a key set file's text; see `KeySet.read`. */
+function readKeySet(text, algorithm) {
+	return KeySet.read(text, algorithm);
+}
+/** Whether `value` is a set the builders made: identity.ts's check, which nothing outside this module can replace. */
+function isKeySet(value) {
+	return branded(value);
+}
+/**
+* jwtVerify under a set the builders made, its algorithm pinned (see
+* `KeySet#verify`). identity.ts's one way to verify; index.ts does not export
+* it, so an embedder cannot call it with looser options than identity.ts's.
+*/
+function verifyWithKeySet(set, token, options) {
+	return verifyUnder(set, token, options);
+}
+//#endregion
+//#region src/identity.ts
+/** Why a token is refused when the verifier is handed something that is not a set the builders made. */
+const NOT_A_KEY_SET = "the identity key set is not one readKeySet made";
+/**
+* The set a one-key setting verifies with: a secret's UTF-8 bytes, at least
+* 32 of them, or the PEM as jose imports it. What `identity-keys-cli.mjs
+* convert` writes is this set's key, so the two never differ.
+*/
+async function oneKeySet(key) {
+	return key.kind === "secret" ? KeySet.fromSecret(key.secret) : KeySet.fromPem(key.pem, key.algorithm);
+}
+/**
+* A verifier for the host application's tokens, built once at startup.
+*
+* Fails at construction on a configuration that would accept forgeries — a
+* short secret, a key that does not parse, a key set no builder checked —
+* rather than on the first request. The algorithm is pinned per key kind, and
+* for a whole key set, so a token cannot choose `none` or swap an asymmetric
+* key for a shared one.
+*
+* A key set's `keys` is asked once per token, so a set read again replaces
+* the one in force between tokens, and a verification that has begun
+* finishes on the set it began with.
+*/
+async function createIdentityVerifier(options) {
+	let keys;
+	if (options.key.kind === "key-set") {
+		keys = options.key.keys;
+		if (!isKeySet(keys())) throw new Error(NOT_A_KEY_SET);
+	} else {
+		const set = await oneKeySet(options.key);
+		keys = () => set;
+	}
+	const rolesClaim = options.rolesClaim ?? "roles";
+	const tolerance = options.clockToleranceSeconds ?? 30;
+	return async (token) => {
+		let set;
+		try {
+			set = keys();
+		} catch {
+			set = void 0;
+		}
+		if (!isKeySet(set)) return {
+			ok: false,
+			reason: NOT_A_KEY_SET
+		};
+		let payload;
+		try {
+			({payload} = await verifyWithKeySet(set, token, {
+				issuer: options.issuer,
+				audience: options.audience,
+				clockTolerance: tolerance,
+				requiredClaims: ["sub", "exp"]
+			}));
+		} catch (error) {
+			return {
+				ok: false,
+				reason: typeof error === "object" && error !== null && "code" in error ? String(error.code) : "ERR_JWT_INVALID"
+			};
+		}
+		const id = payload.sub;
+		if (typeof id !== "string" || id === "") return {
+			ok: false,
+			reason: "the token has no subject"
+		};
+		const roles = payload[rolesClaim] ?? [];
+		if (!Array.isArray(roles) || !roles.every((role) => typeof role === "string")) return {
+			ok: false,
+			reason: `the ${rolesClaim} claim is not a list of strings`
+		};
+		const attributes = {};
+		for (const [attribute, claim] of Object.entries(options.attributes)) {
+			const value = payload[claim];
+			if (value === void 0) continue;
+			if (typeof value === "string") attributes[attribute] = value;
+			else if (typeof value === "number" && Number.isSafeInteger(value)) attributes[attribute] = String(value);
+			else return {
+				ok: false,
+				reason: `the ${claim} claim is not a string or a whole number`
+			};
+		}
+		return {
+			ok: true,
+			identity: {
+				actor: {
+					id,
+					roles: [...roles]
+				},
+				attributes
+			}
+		};
+	};
+}
+//#endregion
+//#region src/identity-file.ts
+/**
+* A key set file's text, read the way a read always finishes: opened without
+* waiting for a writer, and refused unless it is a regular file. readFile on
+* a FIFO waited for a writer, and a read again that never finished held every
+* later one behind it, SIGTERM's shutdown too. A file on a network mount that
+* stalls still stalls the read: nothing here can tell a slow server from a
+* lost one.
+*/
+async function readKeySetText(path) {
+	const handle = await open(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+	try {
+		if (!(await handle.stat()).isFile()) throw new KeySetRefusal(`the identity key set file ${path} is not a regular file`);
+		return await handle.readFile("utf8");
+	} finally {
+		await handle.close();
+	}
+}
+async function readSet(path, algorithm, read) {
+	let text;
+	try {
+		text = await read(path);
+	} catch (error) {
+		if (error instanceof KeySetRefusal) throw error;
+		throw new KeySetRefusal(`the identity key set file ${path} cannot be read`);
+	}
+	return readKeySet(text, algorithm);
+}
+/**
+* The key set in `path`, read now -- a refused set throws, which stops the
+* server at start -- and read again whenever `readAgain` is called: on SIGHUP
+* in the running server (main.ts), and by an embedder wherever it chooses.
+*
+* A read that fails keeps the set in force, a key removed from the file
+* included, because a typo or a half-written file must not refuse every
+* token; the outcome says so, and the same file then stops the next start
+* until it is fixed. `read` is injected for the tests; the server and the
+* tool read through readKeySetText.
+*/
+async function openKeySetFile(path, algorithm, read = readKeySetText) {
+	let current = await readSet(path, algorithm, read);
+	const readOnce = async () => {
+		let next;
+		try {
+			next = await readSet(path, algorithm, read);
+		} catch (error) {
+			return {
+				read: false,
+				kids: current.kids,
+				problem: error instanceof KeySetRefusal ? error.message : "the identity key set file could not be read as a key set"
+			};
+		}
+		const { added, removed, replaced } = current.compare(next);
+		current = next;
+		if (added.length === 0 && removed.length === 0 && replaced.length === 0) return {
+			read: true,
+			changed: false,
+			kids: next.kids,
+			leftOut: next.leftOut
+		};
+		return {
+			read: true,
+			changed: true,
+			kids: next.kids,
+			added,
+			removed,
+			replaced,
+			leftOut: next.leftOut
+		};
+	};
+	let queue = Promise.resolve();
+	return {
+		current: () => current,
+		readAgain: () => {
+			const outcome = queue.then(readOnce);
+			queue = outcome;
+			return outcome;
+		}
+	};
+}
+//#endregion
+//#region src/secrets.ts
+const DEFAULT_SOURCE = {
+	env: process.env,
+	readFile: (path) => readFile(path, "utf8")
+};
+const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
+/**
+* The value behind a secret reference.
+*
+* Configuration names a secret, never contains one (plan section 3: "a
+* server-side secret reference"). Two forms: `env:NAME`, read from the
+* environment, and `file:/absolute/path`, read from a file — which is how
+* Docker and Kubernetes hand secrets to a container.
+*
+* **No error message ever contains the reference's value**, only its form. The
+* commonest mistake is pasting the secret itself where its reference belongs,
+* and an error that echoed the input would print the secret into a log.
+*/
+async function resolveSecret(reference, source = DEFAULT_SOURCE) {
+	if (reference.startsWith("env:")) {
+		const name = reference.slice(4);
+		if (!ENV_NAME.test(name)) throw new Error("an env: secret reference names a variable in upper case, digits and underscores");
+		const value = source.env[name];
+		if (value === void 0 || value === "") throw new Error(`the environment variable ${name} is unset or empty`);
+		return value;
+	}
+	if (reference.startsWith("file:")) {
+		const path = reference.slice(5);
+		if (!isAbsolute(path)) throw new Error("a file: secret reference needs an absolute path");
+		let text;
+		try {
+			text = await source.readFile(path);
+		} catch {
+			throw new Error(`the secret file ${path} cannot be read`);
+		}
+		const value = text.endsWith("\r\n") ? text.slice(0, -2) : text.endsWith("\n") ? text.slice(0, -1) : text;
+		if (value === "") throw new Error(`the secret file ${path} is empty`);
+		return value;
+	}
+	throw new Error("a secret reference is env:NAME or file:/absolute/path. If you pasted the secret itself here, move it into one of those instead.");
+}
+//#endregion
+export { KeySet as a, readKeySet as c, oneKeySet as i, openKeySetFile as n, KeySetRefusal as o, createIdentityVerifier as r, isKeySetAlgorithm as s, resolveSecret as t };
+
+//# sourceMappingURL=secrets-DhKHG-Y9.mjs.map