@nice-code/util 0.25.0 → 0.26.0

package/build/index.cjs

@@ -452,17 +452,30 @@ const serializeX25519Key_Raw = async (key) => {
 };
 //#endregion
 //#region src/crypto/client_key_link/ClientCryptoKeyLink.ts
+/**
+* Thrown by the local-key getters when the link is in {@link TIdentityMode} `"required"` and no
+* identity has been provisioned. Surfacing this (instead of silently minting a fresh identity on a
+* storage miss) is what keeps a shared backend identity from forking across isolates.
+*/
+var IdentityNotProvisionedError = class extends Error {
+	constructor(message = "ClientCryptoKeyLink: identity not provisioned (identityMode 'required'). Call provisionIdentity() once, out-of-band, before serving.") {
+		super(message);
+		this.name = "IdentityNotProvisionedError";
+	}
+};
 var ClientCryptoKeyLink = class {
 	localExchangeKeyPair;
 	localVerifyKeyPair;
 	linkedClientKeys = /* @__PURE__ */ new Map();
 	storage;
+	identityMode;
 	initialized = false;
 	initializePromise;
 	localExchangeKeyPairPromise;
 	localVerifyKeyPairPromise;
-	constructor({ storageAdapter } = {}) {
+	constructor({ storageAdapter, identityMode } = {}) {
 		if (storageAdapter != null) this.storage = createTypedStorage({ storageAdapter });
+		this.identityMode = identityMode ?? "lazy";
 	}
 	/**
 	* Loads the local key pairs and any linked client public keys from storage (when a storage
@@ -485,6 +498,24 @@ var ClientCryptoKeyLink = class {
 		this.initialized = true;
 	}
 	/**
+	* Provision the local identity once: load any persisted identity, then mint + persist the exchange
+	* and verify key pairs only if absent. Idempotent — a no-op when an identity already exists.
+	*
+	* This is the *only* way to mint when {@link TIdentityMode} is `"required"`. Run it from a single
+	* coordinated writer (a deploy hook, a first-boot path, a locked admin route) — **never on the hot
+	* request path** — because concurrent provisioning over an eventually-consistent store could read
+	* "absent" on two isolates at once and fork divergent identities. The serving path uses `"required"`,
+	* which never mints, so a transient storage miss fails that one request loudly instead of forking.
+	*
+	* A genuine storage *read error* propagates here (it is never coerced to "absent"), so an outage
+	* surfaces rather than silently minting a replacement identity.
+	*/
+	async provisionIdentity() {
+		await this.initialize();
+		await this.mintLocalExchangeKeyPair();
+		await this.mintLocalVerifyKeyPair();
+	}
+	/**
 	* Loads the local key pairs from storage if they were previously persisted. Does NOT generate
 	* fresh keys — local identity is created lazily on first use (see {@link ensureLocalExchangeKeyPair}
 	* / {@link ensureLocalVerifyKeyPair}), so a verify-only or otherwise key-less consumer never
@@ -503,10 +534,21 @@ var ClientCryptoKeyLink = class {
 		};
 	}
 	/**
-	* Returns the local exchange (X25519) key pair, generating and persisting it on first use.
-	* Concurrent callers share a single generation.
+	* Returns the local exchange (X25519) key pair. In `"lazy"` mode it generates + persists it on first
+	* use; in `"required"` mode it throws {@link IdentityNotProvisionedError} when none was loaded (mint
+	* only via {@link provisionIdentity}). The read path of every encrypt/derive operation.
 	*/
 	async ensureLocalExchangeKeyPair() {
+		if (this.localExchangeKeyPair != null) return this.localExchangeKeyPair;
+		if (this.identityMode === "required") throw new IdentityNotProvisionedError();
+		return this.mintLocalExchangeKeyPair();
+	}
+	/**
+	* Generates + persists the local exchange key pair if absent, returning an already-loaded pair
+	* untouched (so provisioning is idempotent). Bypasses the `"required"` guard by design — it is the
+	* sole minting path. Concurrent callers share a single generation.
+	*/
+	async mintLocalExchangeKeyPair() {
 		if (this.localExchangeKeyPair != null) return this.localExchangeKeyPair;
 		this.localExchangeKeyPairPromise ??= (async () => {
 			const keyPair = await generateX25519KeyPair();
@@ -521,10 +563,21 @@ var ClientCryptoKeyLink = class {
 		}
 	}
 	/**
-	* Returns the local verify (Ed25519) key pair, generating and persisting it on first use.
-	* Concurrent callers share a single generation.
+	* Returns the local verify (Ed25519) key pair. In `"lazy"` mode it generates + persists it on first
+	* use; in `"required"` mode it throws {@link IdentityNotProvisionedError} when none was loaded (mint
+	* only via {@link provisionIdentity}). The read path of every sign operation.
 	*/
 	async ensureLocalVerifyKeyPair() {
+		if (this.localVerifyKeyPair != null) return this.localVerifyKeyPair;
+		if (this.identityMode === "required") throw new IdentityNotProvisionedError();
+		return this.mintLocalVerifyKeyPair();
+	}
+	/**
+	* Generates + persists the local verify key pair if absent, returning an already-loaded pair
+	* untouched (so provisioning is idempotent). Bypasses the `"required"` guard by design — it is the
+	* sole minting path. Concurrent callers share a single generation.
+	*/
+	async mintLocalVerifyKeyPair() {
 		if (this.localVerifyKeyPair != null) return this.localVerifyKeyPair;
 		this.localVerifyKeyPairPromise ??= (async () => {
 			const keyPair = await generateEd25519KeyPair();
@@ -742,6 +795,58 @@ var ClientCryptoKeyLink = class {
 		});
 		return sharedEncryptKey;
 	}
+	/**
+	* Derive the shared AES-GCM key from *explicit* key material + this link's local exchange private
+	* key, returning a standalone key that is **not** stored in (or read from) the per-`linkedClientId`
+	* cache. Use it to give a single session its own immutable key: two sessions that share one
+	* `linkedClientId` (e.g. a secure WebSocket and a secure HTTP exchange to the same peer) would
+	* otherwise clobber each other's cached shared key — the second handshake's re-link drops the
+	* first's key, so frames on the other transport fail to decrypt. Mirrors the derivation in
+	* {@link getAesGcmKeyForLinkedClient} exactly, so the resulting key matches the peer's.
+	*
+	* Requires the local identity to be loaded — call {@link initialize} first when resuming a link
+	* cold (the handshake paths have already initialized by the time they hold key material).
+	*/
+	async deriveSharedAesGcmKey({ exchangePublicKey, saltString, infoString, bindVerifyKeysIntoDerivation, verifyPublicKey }) {
+		const localExchangeKeyPair = await this.ensureLocalExchangeKeyPair();
+		const externalX25519PublicKey = await importX25519Key.public.fromFormattedString.extractable(exchangePublicKey);
+		let derivedInfoString = infoString;
+		if (bindVerifyKeysIntoDerivation === true) {
+			if (verifyPublicKey == null) throw new Error("ClientCryptoKeyLink.deriveSharedAesGcmKey: a verify public key is required when binding verify keys into the derivation");
+			derivedInfoString = buildVerifyKeyBoundInfoString({
+				infoString,
+				verifyPublicKeys: [await this.getLocalVerifyPublicKey(), verifyPublicKey]
+			});
+		}
+		return await createAesGcmKeyFromX25519Keys({
+			internalX25519PrivateKey: localExchangeKeyPair.privateKey,
+			externalX25519PublicKey,
+			saltString,
+			infoString: derivedInfoString
+		});
+	}
+	/**
+	* Derive a symmetric AES-GCM key bound to **this link's own identity** — for sealing data the server
+	* hands a client and reads back later (e.g. a stateless secure-exchange session ticket), where only
+	* this server (any isolate that loaded the same persisted identity) can open it.
+	*
+	* Deterministic: an X25519 ECDH of the local exchange private key against its own public key, fed
+	* through the same vetted HKDF as peer key derivation, with a fixed versioned info label. So every
+	* isolate sharing the persisted identity derives the identical key, and no raw private-key bytes are
+	* exposed. The {@link version} is part of the label, so a future rotation can run two keys during a
+	* grace window (old tickets opened with `v1` while new ones issue under `v2`).
+	*
+	* Requires the local identity (call {@link initialize} / {@link provisionIdentity} first); in
+	* `"required"` mode an unprovisioned link throws {@link IdentityNotProvisionedError}.
+	*/
+	async deriveLocalSealKey(options) {
+		const localExchangeKeyPair = await this.ensureLocalExchangeKeyPair();
+		return await createAesGcmKeyFromX25519Keys({
+			internalX25519PrivateKey: localExchangeKeyPair.privateKey,
+			externalX25519PublicKey: localExchangeKeyPair.publicKey,
+			infoString: `exchange-ticket-seal/${options?.version ?? "v1"}`
+		});
+	}
 	async encryptDataForLinkedClient({ dataToEncrypt, linkedClientId }) {
 		return await encryptTextDataWithAesGcmKey({
 			dataToEncrypt,
@@ -1074,6 +1179,7 @@ exports.DEFAULT_COMBINED_TEXT_DATA_SEPARATOR = DEFAULT_COMBINED_TEXT_DATA_SEPARA
 exports.ECryptoKeyAlgo = ECryptoKeyAlgo;
 exports.ECryptoKeyFormat = ECryptoKeyFormat;
 exports.EStorageAdapterType = EStorageAdapterType;
+exports.IdentityNotProvisionedError = IdentityNotProvisionedError;
 exports.StorageAdapter = StorageAdapter;
 exports.buildVerifyKeyBoundInfoString = buildVerifyKeyBoundInfoString;
 exports.convertEd25519FormattedStringToObject = convertEd25519FormattedStringToObject;