@nice-code/util 0.25.0 → 0.26.0

package/build/index.d.cts

@@ -230,8 +230,34 @@ declare class StorageAdapter {
 }
 //#endregion
 //#region src/crypto/client_key_link/ClientCryptoKeyLink.d.ts
+/**
+ * How the local identity (the exchange + verify key pairs) is allowed to come into being:
+ *
+ * - `"lazy"` (default): generate + persist the identity on first use. Correct for frontend / ephemeral
+ *   peers, and safe on a *strongly-consistent* store (a read miss genuinely means "never written").
+ * - `"required"`: never auto-mint. `ensureLocal*` throws {@link IdentityNotProvisionedError} if no
+ *   identity was loaded from storage; the only way to mint is the explicit one-shot
+ *   {@link ClientCryptoKeyLink.provisionIdentity}. Use this for a shared backend identity that must
+ *   stay stable across isolates: on an *eventually-consistent* store (e.g. Cloudflare KV) a transient
+ *   read miss must NOT be allowed to silently fork a second identity — that would change the server's
+ *   verify key and get it permanently rejected by every trust-on-first-use-pinned client.
+ */
+type TIdentityMode = "lazy" | "required";
+/**
+ * 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.
+ */
+declare class IdentityNotProvisionedError extends Error {
+  constructor(message?: string);
+}
 interface IClientCryptoKeyLink_Constructor {
   storageAdapter?: StorageAdapter;
+  /**
+   * Controls whether the local identity may be minted on first use. Defaults to `"lazy"` (unchanged
+   * behavior). Pass `"required"` for a stable shared backend identity — see {@link TIdentityMode}.
+   */
+  identityMode?: TIdentityMode;
 }
 interface ILinkedClientPublicKeys {
   verifyPublicKey?: TSerializedCryptoKeyData_Ed25519_Raw;
@@ -270,12 +296,14 @@ declare class ClientCryptoKeyLink {
   private localVerifyKeyPair;
   private linkedClientKeys;
   private storage;
+  private readonly identityMode;
   private initialized;
   private initializePromise;
   private localExchangeKeyPairPromise;
   private localVerifyKeyPairPromise;
   constructor({
-    storageAdapter
+    storageAdapter,
+    identityMode
   }?: IClientCryptoKeyLink_Constructor);
   /**
    * Loads the local key pairs and any linked client public keys from storage (when a storage
@@ -285,6 +313,20 @@ declare class ClientCryptoKeyLink {
    */
   initialize(): Promise<void>;
   private runInitialize;
+  /**
+   * 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.
+   */
+  provisionIdentity(): Promise<void>;
   /**
    * 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}
@@ -293,15 +335,29 @@ declare class ClientCryptoKeyLink {
    */
   private loadStoredLocalKeys;
   /**
-   * 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.
    */
   private ensureLocalExchangeKeyPair;
   /**
-   * Returns the local verify (Ed25519) key pair, generating and persisting it on first use.
-   * Concurrent callers share a single generation.
+   * 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.
+   */
+  private mintLocalExchangeKeyPair;
+  /**
+   * 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.
    */
   private ensureLocalVerifyKeyPair;
+  /**
+   * 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.
+   */
+  private mintLocalVerifyKeyPair;
   private loadLinkedClients;
   private serializeExchangeKeyPair;
   private serializeVerifyKeyPair;
@@ -377,6 +433,48 @@ declare class ClientCryptoKeyLink {
   reset(): Promise<void>;
   private getLinkedClient;
   private getAesGcmKeyForLinkedClient;
+  /**
+   * 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).
+   */
+  deriveSharedAesGcmKey({
+    exchangePublicKey,
+    saltString,
+    infoString,
+    bindVerifyKeysIntoDerivation,
+    verifyPublicKey
+  }: {
+    exchangePublicKey: TSerializedCryptoKeyData_X25519_Raw;
+    saltString?: string;
+    infoString?: string;
+    bindVerifyKeysIntoDerivation?: boolean; /** The peer's verify public key — required when `bindVerifyKeysIntoDerivation` is true. */
+    verifyPublicKey?: TSerializedCryptoKeyData_Ed25519_Raw;
+  }): Promise<CryptoKey>;
+  /**
+   * 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}.
+   */
+  deriveLocalSealKey(options?: {
+    version?: string;
+  }): Promise<CryptoKey>;
   encryptDataForLinkedClient({
     dataToEncrypt,
     linkedClientId
@@ -523,8 +621,8 @@ declare const importEd25519Key: {
       readonly nonExtractable: (input: `ed25519::raw_base64::${string}` | `ed25519::jwk::${string}`) => Promise<CryptoKey>;
     };
     fromSerializedObject: {
-      readonly extractable: (input: TSerializedCryptoKeyData_Ed25519_Jwk_Transformed | TSerializedCryptoKeyData_Ed25519_Raw_Transformed) => Promise<CryptoKey>;
-      readonly nonExtractable: (input: TSerializedCryptoKeyData_Ed25519_Jwk_Transformed | TSerializedCryptoKeyData_Ed25519_Raw_Transformed) => Promise<CryptoKey>;
+      readonly extractable: (input: TSerializedCryptoKeyData_Ed25519_Raw_Transformed | TSerializedCryptoKeyData_Ed25519_Jwk_Transformed) => Promise<CryptoKey>;
+      readonly nonExtractable: (input: TSerializedCryptoKeyData_Ed25519_Raw_Transformed | TSerializedCryptoKeyData_Ed25519_Jwk_Transformed) => Promise<CryptoKey>;
     };
     fromJwk: {
       readonly extractable: (input: JsonWebKey) => Promise<CryptoKey>;
@@ -767,5 +865,5 @@ declare function createMemoryStorageMethods_json(memoryStorageMap?: TMemoryStora
 declare const createMemoryStorageAdapter_json: (options?: TCreateMemoryStorageOptions_json) => StorageAdapter;
 declare function createTypedMemoryStorage_json<T extends Record<string, any>>(options?: TCreateMemoryStorageOptions_json): ITypedStorage<T>;
 //#endregion
-export { ClientCryptoKeyLink, DEFAULT_COMBINED_TEXT_DATA_SEPARATOR, ECryptoKeyAlgo, ECryptoKeyFormat, EStorageAdapterType, ICreateKVStorageMethodsOptions, ISerializedKeyData_Ed25519_Jwk, ISerializedKeyData_Ed25519_Raw, ISerializedKeyData_X25519_Jwk, ISerializedKeyData_X25519_Raw, IStorageAdapterConstructor, IStorageAdapterMethods_Json, IStorageAdapterMethods_String, IStorageKeyGetterAndSetter, ITypedStorage, StorageAdapter, StringKeys, TCreateDurableObjectStorageOptions, TCreateKVStorageOptions, TEncryptedAesGcmBytes, TEncryptedAesGcmPayload, TEncryptedAesGcmPayload_Transformed, TMemoryStorage_json, TMemoryStorage_string, TSerializedCryptoKeyData_Ed25519_Jwk, TSerializedCryptoKeyData_Ed25519_Jwk_Transformed, TSerializedCryptoKeyData_Ed25519_Raw, TSerializedCryptoKeyData_Ed25519_Raw_Transformed, TSerializedCryptoKeyData_X25519_Jwk, TSerializedCryptoKeyData_X25519_Jwk_Transformed, TSerializedCryptoKeyData_X25519_Raw, TSerializedCryptoKeyData_X25519_Raw_Transformed, TSerializedCryptoKeyPairDataEd25519, TSerializedCryptoKeyPairDataX25519, TSerializedKeyData, TStorageAdapterMethods, type TTypeAndId, TVerifyChallengeWithSignature_Input, TVerifyChallengeWithSignature_WithThrow_Input, buildVerifyKeyBoundInfoString, convertEd25519FormattedStringToObject, convertEd25519FormattedStringToSerializedKeyData, convertEd25519JwkDataStringToObject, convertEd25519JwkDataStringToSerializedKeyData, convertEd25519RawDataStringToObject, convertEd25519RawDataStringToSerializedKeyData, convertX25519FormattedStringToObject, convertX25519FormattedStringToSerializedKeyData, convertX25519JwkDataStringToObject, convertX25519JwkDataStringToSerializedKeyData, convertX25519RawDataStringToObject, convertX25519RawDataStringToSerializedKeyData, createAesGcmKeyFromX25519Keys, createDurableObjectStorageAdapter, createDurableObjectStorageMethods, createDurableObjectTypedStorage, createKVStorageAdapter, createKVStorageMethods, createKVTypedStorage, createMemoryStorageAdapter_json, createMemoryStorageAdapter_string, createMemoryStorageMethods_json, createMemoryStorageMethods_string, createSharedBitsFromX25519, createTypedMemoryStorage_json, createTypedMemoryStorage_string, createTypedStorage, createTypedWebLocalStorage, createTypedWebSessionStorage, createWebLocalStorageAdapter, createWebLocalStorageMethods, createWebSessionStorageAdapter, createWebSessionStorageMethods, decryptBytesWithAesGcmKey, decryptTextDataWithAesGcmKey, encryptBytesWithAesGcmKey, encryptTextDataWithAesGcmKey, generateEd25519KeyPair, generateX25519KeyPair, importEd25519Key, importX25519Key, serializeEd25519Key_Jwk, serializeEd25519Key_Raw, serializeX25519Key_Jwk, serializeX25519Key_Raw, signCombinedTextDataWithKeyEd25519, signTextDataWithKeyEd25519, vCryptoKeyPairDataEd25519, vCryptoKeyPairDataX25519, vEncryptedAesGcmPayload, vSerializedCryptoKeyDataEd25519_Jwk, vSerializedCryptoKeyDataEd25519_Raw, vSerializedCryptoKeyDataX25519_Jwk, vSerializedCryptoKeyDataX25519_Raw, vVerifyChallengeWithSignature_Input, vVerifyChallengeWithSignature_WithThrow_Input, verifyWithKeyEd25519 };
+export { ClientCryptoKeyLink, DEFAULT_COMBINED_TEXT_DATA_SEPARATOR, ECryptoKeyAlgo, ECryptoKeyFormat, EStorageAdapterType, ICreateKVStorageMethodsOptions, ISerializedKeyData_Ed25519_Jwk, ISerializedKeyData_Ed25519_Raw, ISerializedKeyData_X25519_Jwk, ISerializedKeyData_X25519_Raw, IStorageAdapterConstructor, IStorageAdapterMethods_Json, IStorageAdapterMethods_String, IStorageKeyGetterAndSetter, ITypedStorage, IdentityNotProvisionedError, StorageAdapter, StringKeys, TCreateDurableObjectStorageOptions, TCreateKVStorageOptions, TEncryptedAesGcmBytes, TEncryptedAesGcmPayload, TEncryptedAesGcmPayload_Transformed, TIdentityMode, TMemoryStorage_json, TMemoryStorage_string, TSerializedCryptoKeyData_Ed25519_Jwk, TSerializedCryptoKeyData_Ed25519_Jwk_Transformed, TSerializedCryptoKeyData_Ed25519_Raw, TSerializedCryptoKeyData_Ed25519_Raw_Transformed, TSerializedCryptoKeyData_X25519_Jwk, TSerializedCryptoKeyData_X25519_Jwk_Transformed, TSerializedCryptoKeyData_X25519_Raw, TSerializedCryptoKeyData_X25519_Raw_Transformed, TSerializedCryptoKeyPairDataEd25519, TSerializedCryptoKeyPairDataX25519, TSerializedKeyData, TStorageAdapterMethods, type TTypeAndId, TVerifyChallengeWithSignature_Input, TVerifyChallengeWithSignature_WithThrow_Input, buildVerifyKeyBoundInfoString, convertEd25519FormattedStringToObject, convertEd25519FormattedStringToSerializedKeyData, convertEd25519JwkDataStringToObject, convertEd25519JwkDataStringToSerializedKeyData, convertEd25519RawDataStringToObject, convertEd25519RawDataStringToSerializedKeyData, convertX25519FormattedStringToObject, convertX25519FormattedStringToSerializedKeyData, convertX25519JwkDataStringToObject, convertX25519JwkDataStringToSerializedKeyData, convertX25519RawDataStringToObject, convertX25519RawDataStringToSerializedKeyData, createAesGcmKeyFromX25519Keys, createDurableObjectStorageAdapter, createDurableObjectStorageMethods, createDurableObjectTypedStorage, createKVStorageAdapter, createKVStorageMethods, createKVTypedStorage, createMemoryStorageAdapter_json, createMemoryStorageAdapter_string, createMemoryStorageMethods_json, createMemoryStorageMethods_string, createSharedBitsFromX25519, createTypedMemoryStorage_json, createTypedMemoryStorage_string, createTypedStorage, createTypedWebLocalStorage, createTypedWebSessionStorage, createWebLocalStorageAdapter, createWebLocalStorageMethods, createWebSessionStorageAdapter, createWebSessionStorageMethods, decryptBytesWithAesGcmKey, decryptTextDataWithAesGcmKey, encryptBytesWithAesGcmKey, encryptTextDataWithAesGcmKey, generateEd25519KeyPair, generateX25519KeyPair, importEd25519Key, importX25519Key, serializeEd25519Key_Jwk, serializeEd25519Key_Raw, serializeX25519Key_Jwk, serializeX25519Key_Raw, signCombinedTextDataWithKeyEd25519, signTextDataWithKeyEd25519, vCryptoKeyPairDataEd25519, vCryptoKeyPairDataX25519, vEncryptedAesGcmPayload, vSerializedCryptoKeyDataEd25519_Jwk, vSerializedCryptoKeyDataEd25519_Raw, vSerializedCryptoKeyDataX25519_Jwk, vSerializedCryptoKeyDataX25519_Raw, vVerifyChallengeWithSignature_Input, vVerifyChallengeWithSignature_WithThrow_Input, verifyWithKeyEd25519 };
 //# sourceMappingURL=index.d.cts.map

package/build/index.d.mts

@@ -230,8 +230,34 @@ declare class StorageAdapter {
 }
 //#endregion
 //#region src/crypto/client_key_link/ClientCryptoKeyLink.d.ts
+/**
+ * How the local identity (the exchange + verify key pairs) is allowed to come into being:
+ *
+ * - `"lazy"` (default): generate + persist the identity on first use. Correct for frontend / ephemeral
+ *   peers, and safe on a *strongly-consistent* store (a read miss genuinely means "never written").
+ * - `"required"`: never auto-mint. `ensureLocal*` throws {@link IdentityNotProvisionedError} if no
+ *   identity was loaded from storage; the only way to mint is the explicit one-shot
+ *   {@link ClientCryptoKeyLink.provisionIdentity}. Use this for a shared backend identity that must
+ *   stay stable across isolates: on an *eventually-consistent* store (e.g. Cloudflare KV) a transient
+ *   read miss must NOT be allowed to silently fork a second identity — that would change the server's
+ *   verify key and get it permanently rejected by every trust-on-first-use-pinned client.
+ */
+type TIdentityMode = "lazy" | "required";
+/**
+ * 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.
+ */
+declare class IdentityNotProvisionedError extends Error {
+  constructor(message?: string);
+}
 interface IClientCryptoKeyLink_Constructor {
   storageAdapter?: StorageAdapter;
+  /**
+   * Controls whether the local identity may be minted on first use. Defaults to `"lazy"` (unchanged
+   * behavior). Pass `"required"` for a stable shared backend identity — see {@link TIdentityMode}.
+   */
+  identityMode?: TIdentityMode;
 }
 interface ILinkedClientPublicKeys {
   verifyPublicKey?: TSerializedCryptoKeyData_Ed25519_Raw;
@@ -270,12 +296,14 @@ declare class ClientCryptoKeyLink {
   private localVerifyKeyPair;
   private linkedClientKeys;
   private storage;
+  private readonly identityMode;
   private initialized;
   private initializePromise;
   private localExchangeKeyPairPromise;
   private localVerifyKeyPairPromise;
   constructor({
-    storageAdapter
+    storageAdapter,
+    identityMode
   }?: IClientCryptoKeyLink_Constructor);
   /**
    * Loads the local key pairs and any linked client public keys from storage (when a storage
@@ -285,6 +313,20 @@ declare class ClientCryptoKeyLink {
    */
   initialize(): Promise<void>;
   private runInitialize;
+  /**
+   * 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.
+   */
+  provisionIdentity(): Promise<void>;
   /**
    * 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}
@@ -293,15 +335,29 @@ declare class ClientCryptoKeyLink {
    */
   private loadStoredLocalKeys;
   /**
-   * 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.
    */
   private ensureLocalExchangeKeyPair;
   /**
-   * Returns the local verify (Ed25519) key pair, generating and persisting it on first use.
-   * Concurrent callers share a single generation.
+   * 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.
+   */
+  private mintLocalExchangeKeyPair;
+  /**
+   * 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.
    */
   private ensureLocalVerifyKeyPair;
+  /**
+   * 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.
+   */
+  private mintLocalVerifyKeyPair;
   private loadLinkedClients;
   private serializeExchangeKeyPair;
   private serializeVerifyKeyPair;
@@ -377,6 +433,48 @@ declare class ClientCryptoKeyLink {
   reset(): Promise<void>;
   private getLinkedClient;
   private getAesGcmKeyForLinkedClient;
+  /**
+   * 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).
+   */
+  deriveSharedAesGcmKey({
+    exchangePublicKey,
+    saltString,
+    infoString,
+    bindVerifyKeysIntoDerivation,
+    verifyPublicKey
+  }: {
+    exchangePublicKey: TSerializedCryptoKeyData_X25519_Raw;
+    saltString?: string;
+    infoString?: string;
+    bindVerifyKeysIntoDerivation?: boolean; /** The peer's verify public key — required when `bindVerifyKeysIntoDerivation` is true. */
+    verifyPublicKey?: TSerializedCryptoKeyData_Ed25519_Raw;
+  }): Promise<CryptoKey>;
+  /**
+   * 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}.
+   */
+  deriveLocalSealKey(options?: {
+    version?: string;
+  }): Promise<CryptoKey>;
   encryptDataForLinkedClient({
     dataToEncrypt,
     linkedClientId
@@ -523,8 +621,8 @@ declare const importEd25519Key: {
       readonly nonExtractable: (input: `ed25519::raw_base64::${string}` | `ed25519::jwk::${string}`) => Promise<CryptoKey>;
     };
     fromSerializedObject: {
-      readonly extractable: (input: TSerializedCryptoKeyData_Ed25519_Jwk_Transformed | TSerializedCryptoKeyData_Ed25519_Raw_Transformed) => Promise<CryptoKey>;
-      readonly nonExtractable: (input: TSerializedCryptoKeyData_Ed25519_Jwk_Transformed | TSerializedCryptoKeyData_Ed25519_Raw_Transformed) => Promise<CryptoKey>;
+      readonly extractable: (input: TSerializedCryptoKeyData_Ed25519_Raw_Transformed | TSerializedCryptoKeyData_Ed25519_Jwk_Transformed) => Promise<CryptoKey>;
+      readonly nonExtractable: (input: TSerializedCryptoKeyData_Ed25519_Raw_Transformed | TSerializedCryptoKeyData_Ed25519_Jwk_Transformed) => Promise<CryptoKey>;
     };
     fromJwk: {
       readonly extractable: (input: JsonWebKey) => Promise<CryptoKey>;
@@ -767,5 +865,5 @@ declare function createMemoryStorageMethods_json(memoryStorageMap?: TMemoryStora
 declare const createMemoryStorageAdapter_json: (options?: TCreateMemoryStorageOptions_json) => StorageAdapter;
 declare function createTypedMemoryStorage_json<T extends Record<string, any>>(options?: TCreateMemoryStorageOptions_json): ITypedStorage<T>;
 //#endregion
-export { ClientCryptoKeyLink, DEFAULT_COMBINED_TEXT_DATA_SEPARATOR, ECryptoKeyAlgo, ECryptoKeyFormat, EStorageAdapterType, ICreateKVStorageMethodsOptions, ISerializedKeyData_Ed25519_Jwk, ISerializedKeyData_Ed25519_Raw, ISerializedKeyData_X25519_Jwk, ISerializedKeyData_X25519_Raw, IStorageAdapterConstructor, IStorageAdapterMethods_Json, IStorageAdapterMethods_String, IStorageKeyGetterAndSetter, ITypedStorage, StorageAdapter, StringKeys, TCreateDurableObjectStorageOptions, TCreateKVStorageOptions, TEncryptedAesGcmBytes, TEncryptedAesGcmPayload, TEncryptedAesGcmPayload_Transformed, TMemoryStorage_json, TMemoryStorage_string, TSerializedCryptoKeyData_Ed25519_Jwk, TSerializedCryptoKeyData_Ed25519_Jwk_Transformed, TSerializedCryptoKeyData_Ed25519_Raw, TSerializedCryptoKeyData_Ed25519_Raw_Transformed, TSerializedCryptoKeyData_X25519_Jwk, TSerializedCryptoKeyData_X25519_Jwk_Transformed, TSerializedCryptoKeyData_X25519_Raw, TSerializedCryptoKeyData_X25519_Raw_Transformed, TSerializedCryptoKeyPairDataEd25519, TSerializedCryptoKeyPairDataX25519, TSerializedKeyData, TStorageAdapterMethods, type TTypeAndId, TVerifyChallengeWithSignature_Input, TVerifyChallengeWithSignature_WithThrow_Input, buildVerifyKeyBoundInfoString, convertEd25519FormattedStringToObject, convertEd25519FormattedStringToSerializedKeyData, convertEd25519JwkDataStringToObject, convertEd25519JwkDataStringToSerializedKeyData, convertEd25519RawDataStringToObject, convertEd25519RawDataStringToSerializedKeyData, convertX25519FormattedStringToObject, convertX25519FormattedStringToSerializedKeyData, convertX25519JwkDataStringToObject, convertX25519JwkDataStringToSerializedKeyData, convertX25519RawDataStringToObject, convertX25519RawDataStringToSerializedKeyData, createAesGcmKeyFromX25519Keys, createDurableObjectStorageAdapter, createDurableObjectStorageMethods, createDurableObjectTypedStorage, createKVStorageAdapter, createKVStorageMethods, createKVTypedStorage, createMemoryStorageAdapter_json, createMemoryStorageAdapter_string, createMemoryStorageMethods_json, createMemoryStorageMethods_string, createSharedBitsFromX25519, createTypedMemoryStorage_json, createTypedMemoryStorage_string, createTypedStorage, createTypedWebLocalStorage, createTypedWebSessionStorage, createWebLocalStorageAdapter, createWebLocalStorageMethods, createWebSessionStorageAdapter, createWebSessionStorageMethods, decryptBytesWithAesGcmKey, decryptTextDataWithAesGcmKey, encryptBytesWithAesGcmKey, encryptTextDataWithAesGcmKey, generateEd25519KeyPair, generateX25519KeyPair, importEd25519Key, importX25519Key, serializeEd25519Key_Jwk, serializeEd25519Key_Raw, serializeX25519Key_Jwk, serializeX25519Key_Raw, signCombinedTextDataWithKeyEd25519, signTextDataWithKeyEd25519, vCryptoKeyPairDataEd25519, vCryptoKeyPairDataX25519, vEncryptedAesGcmPayload, vSerializedCryptoKeyDataEd25519_Jwk, vSerializedCryptoKeyDataEd25519_Raw, vSerializedCryptoKeyDataX25519_Jwk, vSerializedCryptoKeyDataX25519_Raw, vVerifyChallengeWithSignature_Input, vVerifyChallengeWithSignature_WithThrow_Input, verifyWithKeyEd25519 };
+export { ClientCryptoKeyLink, DEFAULT_COMBINED_TEXT_DATA_SEPARATOR, ECryptoKeyAlgo, ECryptoKeyFormat, EStorageAdapterType, ICreateKVStorageMethodsOptions, ISerializedKeyData_Ed25519_Jwk, ISerializedKeyData_Ed25519_Raw, ISerializedKeyData_X25519_Jwk, ISerializedKeyData_X25519_Raw, IStorageAdapterConstructor, IStorageAdapterMethods_Json, IStorageAdapterMethods_String, IStorageKeyGetterAndSetter, ITypedStorage, IdentityNotProvisionedError, StorageAdapter, StringKeys, TCreateDurableObjectStorageOptions, TCreateKVStorageOptions, TEncryptedAesGcmBytes, TEncryptedAesGcmPayload, TEncryptedAesGcmPayload_Transformed, TIdentityMode, TMemoryStorage_json, TMemoryStorage_string, TSerializedCryptoKeyData_Ed25519_Jwk, TSerializedCryptoKeyData_Ed25519_Jwk_Transformed, TSerializedCryptoKeyData_Ed25519_Raw, TSerializedCryptoKeyData_Ed25519_Raw_Transformed, TSerializedCryptoKeyData_X25519_Jwk, TSerializedCryptoKeyData_X25519_Jwk_Transformed, TSerializedCryptoKeyData_X25519_Raw, TSerializedCryptoKeyData_X25519_Raw_Transformed, TSerializedCryptoKeyPairDataEd25519, TSerializedCryptoKeyPairDataX25519, TSerializedKeyData, TStorageAdapterMethods, type TTypeAndId, TVerifyChallengeWithSignature_Input, TVerifyChallengeWithSignature_WithThrow_Input, buildVerifyKeyBoundInfoString, convertEd25519FormattedStringToObject, convertEd25519FormattedStringToSerializedKeyData, convertEd25519JwkDataStringToObject, convertEd25519JwkDataStringToSerializedKeyData, convertEd25519RawDataStringToObject, convertEd25519RawDataStringToSerializedKeyData, convertX25519FormattedStringToObject, convertX25519FormattedStringToSerializedKeyData, convertX25519JwkDataStringToObject, convertX25519JwkDataStringToSerializedKeyData, convertX25519RawDataStringToObject, convertX25519RawDataStringToSerializedKeyData, createAesGcmKeyFromX25519Keys, createDurableObjectStorageAdapter, createDurableObjectStorageMethods, createDurableObjectTypedStorage, createKVStorageAdapter, createKVStorageMethods, createKVTypedStorage, createMemoryStorageAdapter_json, createMemoryStorageAdapter_string, createMemoryStorageMethods_json, createMemoryStorageMethods_string, createSharedBitsFromX25519, createTypedMemoryStorage_json, createTypedMemoryStorage_string, createTypedStorage, createTypedWebLocalStorage, createTypedWebSessionStorage, createWebLocalStorageAdapter, createWebLocalStorageMethods, createWebSessionStorageAdapter, createWebSessionStorageMethods, decryptBytesWithAesGcmKey, decryptTextDataWithAesGcmKey, encryptBytesWithAesGcmKey, encryptTextDataWithAesGcmKey, generateEd25519KeyPair, generateX25519KeyPair, importEd25519Key, importX25519Key, serializeEd25519Key_Jwk, serializeEd25519Key_Raw, serializeX25519Key_Jwk, serializeX25519Key_Raw, signCombinedTextDataWithKeyEd25519, signTextDataWithKeyEd25519, vCryptoKeyPairDataEd25519, vCryptoKeyPairDataX25519, vEncryptedAesGcmPayload, vSerializedCryptoKeyDataEd25519_Jwk, vSerializedCryptoKeyDataEd25519_Raw, vSerializedCryptoKeyDataX25519_Jwk, vSerializedCryptoKeyDataX25519_Raw, vVerifyChallengeWithSignature_Input, vVerifyChallengeWithSignature_WithThrow_Input, verifyWithKeyEd25519 };
 //# sourceMappingURL=index.d.mts.map

package/build/index.mjs

@@ -428,17 +428,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
@@ -461,6 +474,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
@@ -479,10 +510,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();
@@ -497,10 +539,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();
@@ -718,6 +771,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,
@@ -1045,6 +1150,6 @@ function createTypedMemoryStorage_json(options) {
 	return createTypedStorage({ storageAdapter: createMemoryStorageAdapter_json(options) });
 }
 //#endregion
-export { ClientCryptoKeyLink, DEFAULT_COMBINED_TEXT_DATA_SEPARATOR, ECryptoKeyAlgo, ECryptoKeyFormat, EStorageAdapterType, StorageAdapter, buildVerifyKeyBoundInfoString, convertEd25519FormattedStringToObject, convertEd25519FormattedStringToSerializedKeyData, convertEd25519JwkDataStringToObject, convertEd25519JwkDataStringToSerializedKeyData, convertEd25519RawDataStringToObject, convertEd25519RawDataStringToSerializedKeyData, convertX25519FormattedStringToObject, convertX25519FormattedStringToSerializedKeyData, convertX25519JwkDataStringToObject, convertX25519JwkDataStringToSerializedKeyData, convertX25519RawDataStringToObject, convertX25519RawDataStringToSerializedKeyData, createAesGcmKeyFromX25519Keys, createDurableObjectStorageAdapter, createDurableObjectStorageMethods, createDurableObjectTypedStorage, createKVStorageAdapter, createKVStorageMethods, createKVTypedStorage, createMemoryStorageAdapter_json, createMemoryStorageAdapter_string, createMemoryStorageMethods_json, createMemoryStorageMethods_string, createSharedBitsFromX25519, createTypedMemoryStorage_json, createTypedMemoryStorage_string, createTypedStorage, createTypedWebLocalStorage, createTypedWebSessionStorage, createWebLocalStorageAdapter, createWebLocalStorageMethods, createWebSessionStorageAdapter, createWebSessionStorageMethods, decryptBytesWithAesGcmKey, decryptTextDataWithAesGcmKey, encryptBytesWithAesGcmKey, encryptTextDataWithAesGcmKey, generateEd25519KeyPair, generateX25519KeyPair, importEd25519Key, importX25519Key, serializeEd25519Key_Jwk, serializeEd25519Key_Raw, serializeX25519Key_Jwk, serializeX25519Key_Raw, signCombinedTextDataWithKeyEd25519, signTextDataWithKeyEd25519, vCryptoKeyPairDataEd25519, vCryptoKeyPairDataX25519, vEncryptedAesGcmPayload, vSerializedCryptoKeyDataEd25519_Jwk, vSerializedCryptoKeyDataEd25519_Raw, vSerializedCryptoKeyDataX25519_Jwk, vSerializedCryptoKeyDataX25519_Raw, vVerifyChallengeWithSignature_Input, vVerifyChallengeWithSignature_WithThrow_Input, verifyWithKeyEd25519 };
+export { ClientCryptoKeyLink, DEFAULT_COMBINED_TEXT_DATA_SEPARATOR, ECryptoKeyAlgo, ECryptoKeyFormat, EStorageAdapterType, IdentityNotProvisionedError, StorageAdapter, buildVerifyKeyBoundInfoString, convertEd25519FormattedStringToObject, convertEd25519FormattedStringToSerializedKeyData, convertEd25519JwkDataStringToObject, convertEd25519JwkDataStringToSerializedKeyData, convertEd25519RawDataStringToObject, convertEd25519RawDataStringToSerializedKeyData, convertX25519FormattedStringToObject, convertX25519FormattedStringToSerializedKeyData, convertX25519JwkDataStringToObject, convertX25519JwkDataStringToSerializedKeyData, convertX25519RawDataStringToObject, convertX25519RawDataStringToSerializedKeyData, createAesGcmKeyFromX25519Keys, createDurableObjectStorageAdapter, createDurableObjectStorageMethods, createDurableObjectTypedStorage, createKVStorageAdapter, createKVStorageMethods, createKVTypedStorage, createMemoryStorageAdapter_json, createMemoryStorageAdapter_string, createMemoryStorageMethods_json, createMemoryStorageMethods_string, createSharedBitsFromX25519, createTypedMemoryStorage_json, createTypedMemoryStorage_string, createTypedStorage, createTypedWebLocalStorage, createTypedWebSessionStorage, createWebLocalStorageAdapter, createWebLocalStorageMethods, createWebSessionStorageAdapter, createWebSessionStorageMethods, decryptBytesWithAesGcmKey, decryptTextDataWithAesGcmKey, encryptBytesWithAesGcmKey, encryptTextDataWithAesGcmKey, generateEd25519KeyPair, generateX25519KeyPair, importEd25519Key, importX25519Key, serializeEd25519Key_Jwk, serializeEd25519Key_Raw, serializeX25519Key_Jwk, serializeX25519Key_Raw, signCombinedTextDataWithKeyEd25519, signTextDataWithKeyEd25519, vCryptoKeyPairDataEd25519, vCryptoKeyPairDataX25519, vEncryptedAesGcmPayload, vSerializedCryptoKeyDataEd25519_Jwk, vSerializedCryptoKeyDataEd25519_Raw, vSerializedCryptoKeyDataX25519_Jwk, vSerializedCryptoKeyDataX25519_Raw, vVerifyChallengeWithSignature_Input, vVerifyChallengeWithSignature_WithThrow_Input, verifyWithKeyEd25519 };
 
 //# sourceMappingURL=index.mjs.map