@novasamatech/host-container 0.8.5 → 0.8.6

package/dist/deriveEntropy.d.ts

@@ -2,8 +2,32 @@
  * Derives 32 bytes of deterministic entropy using the three-layer
  * BLAKE2b-256 scheme specified in RFC-0007.
  *
+ * Layer 1 derives the `rootEntropySource` from the raw root account secret.
+ * Hosts that never hold the raw secret but receive `rootEntropySource` over the
+ * SSO handshake (RFC-0007 "Option 1") should call
+ * {@link deriveProductEntropyFromSource} instead — it skips layer 1 and yields
+ * identical output.
+ *
  * @param rootAccountSecret - Raw BIP-39 entropy bytes of the root account
  * @param productId         - Identifier of the calling product (arbitrary-length string)
- * @param key               - Caller-chosen key, up to 32 bytes
+ * @param key               - Caller-chosen key, 1 to 32 bytes
  */
 export declare function deriveProductEntropy(rootAccountSecret: Uint8Array, productId: string, key: Uint8Array): Uint8Array;
+/**
+ * Derives 32 bytes of deterministic entropy from a precomputed
+ * `rootEntropySource` — layers 2 and 3 of the RFC-0007 scheme.
+ *
+ * Use this when the host never holds the raw `rootAccountSecret` but receives
+ * `rootEntropySource = blake2b256_keyed(rootAccountSecret, "product-entropy-derivation")`
+ * over the SSO handshake (RFC-0007 "Option 1"). Given the same `rootEntropySource`,
+ * `productId`, and `key`, the output is byte-for-byte identical to
+ * {@link deriveProductEntropy} called with the corresponding `rootAccountSecret`.
+ *
+ * Do NOT pass a `rootEntropySource` to {@link deriveProductEntropy}: that would
+ * re-apply layer 1 and produce a different, non-conforming result.
+ *
+ * @param rootEntropySource - 32-byte source derived from the root account secret
+ * @param productId         - Identifier of the calling product (arbitrary-length string)
+ * @param key               - Caller-chosen key, 1 to 32 bytes
+ */
+export declare function deriveProductEntropyFromSource(rootEntropySource: Uint8Array, productId: string, key: Uint8Array): Uint8Array;

package/dist/deriveEntropy.js

@@ -1,4 +1,6 @@
 import { blake2b } from '@noble/hashes/blake2.js';
+const textEncoder = new TextEncoder();
+const DOMAIN_SEPARATOR = textEncoder.encode('product-entropy-derivation');
 function blake2b256Keyed(message, key) {
     return blake2b(message, { dkLen: 32, key });
 }
@@ -9,16 +11,41 @@ function blake2b256(message) {
  * Derives 32 bytes of deterministic entropy using the three-layer
  * BLAKE2b-256 scheme specified in RFC-0007.
  *
+ * Layer 1 derives the `rootEntropySource` from the raw root account secret.
+ * Hosts that never hold the raw secret but receive `rootEntropySource` over the
+ * SSO handshake (RFC-0007 "Option 1") should call
+ * {@link deriveProductEntropyFromSource} instead — it skips layer 1 and yields
+ * identical output.
+ *
  * @param rootAccountSecret - Raw BIP-39 entropy bytes of the root account
  * @param productId         - Identifier of the calling product (arbitrary-length string)
- * @param key               - Caller-chosen key, up to 32 bytes
+ * @param key               - Caller-chosen key, 1 to 32 bytes
  */
 export function deriveProductEntropy(rootAccountSecret, productId, key) {
+    const rootEntropySource = blake2b256Keyed(rootAccountSecret, DOMAIN_SEPARATOR);
+    return deriveProductEntropyFromSource(rootEntropySource, productId, key);
+}
+/**
+ * Derives 32 bytes of deterministic entropy from a precomputed
+ * `rootEntropySource` — layers 2 and 3 of the RFC-0007 scheme.
+ *
+ * Use this when the host never holds the raw `rootAccountSecret` but receives
+ * `rootEntropySource = blake2b256_keyed(rootAccountSecret, "product-entropy-derivation")`
+ * over the SSO handshake (RFC-0007 "Option 1"). Given the same `rootEntropySource`,
+ * `productId`, and `key`, the output is byte-for-byte identical to
+ * {@link deriveProductEntropy} called with the corresponding `rootAccountSecret`.
+ *
+ * Do NOT pass a `rootEntropySource` to {@link deriveProductEntropy}: that would
+ * re-apply layer 1 and produce a different, non-conforming result.
+ *
+ * @param rootEntropySource - 32-byte source derived from the root account secret
+ * @param productId         - Identifier of the calling product (arbitrary-length string)
+ * @param key               - Caller-chosen key, 1 to 32 bytes
+ */
+export function deriveProductEntropyFromSource(rootEntropySource, productId, key) {
     if (key.length === 0 || key.length > 32) {
         throw new Error(`"key" must be between 1 and 32 bytes, got ${key.length}`);
     }
-    const textEncoder = new TextEncoder();
-    const rootEntropySource = blake2b256Keyed(rootAccountSecret, textEncoder.encode('product-entropy-derivation'));
     const perProductEntropy = blake2b256Keyed(rootEntropySource, blake2b256(textEncoder.encode(productId)));
     return blake2b256Keyed(perProductEntropy, key);
 }

package/dist/index.d.ts

@@ -3,6 +3,6 @@ export { createIframeProvider } from './createIframeProvider.js';
 export { createContainer } from './createContainer.js';
 export type { Container, ContainerHandlerOf, CreateContainerOptions, HostApiDebugMessageEvent } from './types.js';
 export { onHostApiDebugMessage } from './debugBus.js';
-export { deriveProductEntropy } from './deriveEntropy.js';
+export { deriveProductEntropy, deriveProductEntropyFromSource } from './deriveEntropy.js';
 export { createRateLimiter } from './rateLimiter.js';
 export type { CreateRateLimiterConfig, RateLimiter, RateLimiterConfig, RateLimiterStrategy } from './rateLimiter.js';

package/dist/index.js

@@ -2,5 +2,5 @@ export { createWebviewProvider } from './createWebviewProvider.js';
 export { createIframeProvider } from './createIframeProvider.js';
 export { createContainer } from './createContainer.js';
 export { onHostApiDebugMessage } from './debugBus.js';
-export { deriveProductEntropy } from './deriveEntropy.js';
+export { deriveProductEntropy, deriveProductEntropyFromSource } from './deriveEntropy.js';
 export { createRateLimiter } from './rateLimiter.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-container",
   "type": "module",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "Host container for hosting and managing products within the Polkadot ecosystem.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "@noble/hashes": "2.2.0",
     "polkadot-api": ">=2",
     "@polkadot-api/substrate-client": "^0.7.0",
-    "@novasamatech/host-api": "0.8.5",
+    "@novasamatech/host-api": "0.8.6",
     "nanoevents": "9.1.0",
     "nanoid": "5.1.11",
     "neverthrow": "^8.2.0"