sos-sdk-node-ts 0.1.0 → 0.1.2

package/README.md

@@ -1,4 +1,13 @@
 # sos-sdk-node-ts
+## Blocking local-first SDK release
+
+The canonical contract is [`SDK_LAYERING.md`](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/SDK_LAYERING.md). Its
+indivisible order is **local packages -> full local test matrix -> merge every
+validated branch to `main` -> publish bottom-up -> install exact registry
+versions and commit lockfiles on `main` -> staging**. Never publish to discover
+deterministic failures and never commit a local package reference. Staging
+begins only after exact registry packages are installed and verified.
+
 
 SOSChain-specific Node adapters built above the shared runtime-neutral SDK.
 
@@ -22,6 +31,18 @@ emergency request over HTTPS with a stable idempotency key and validates the
 provider acknowledgement. The bearer credential remains only in the trusted
 Node runtime.
 
+## Secure-message CSPRNG adapter
+
+`sos-sdk-node-ts/secure-message-crypto` exports `NodeSecureRandomSource` and
+`createNodeSecureMessageCrypto()`. Node supplies only bytes from
+`node:crypto.randomBytes`; the runtime-neutral `sos-sdk-core-ts` package owns
+ML-KEM, key derivation, recipient CEK wrapping and AES content encryption.
+
+The factory handles UTF-8 text and binary audio through the same byte-oriented
+API. Applications select the protected `contentType`, apply their own upload or
+audio-duration limits, and authorize every recipient change before calling the
+shared core. See [docs/SECURE_MESSAGES.md](docs/SECURE_MESSAGES.md).
+
 ```bash
 npm ci
 npm run check

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 /** SOSChain-specific Node adapters over the shared runtime-neutral SDK. */
 export * from './emergency-dispatch.js';
+export * from './secure-message-crypto.js';

package/dist/index.js

@@ -1,2 +1,3 @@
 /** SOSChain-specific Node adapters over the shared runtime-neutral SDK. */
 export * from './emergency-dispatch.js';
+export * from './secure-message-crypto.js';

package/dist/secure-message-crypto.d.ts

@@ -0,0 +1,7 @@
+import { MultiRecipientSecureMessageCrypto, type SecureRandomSource } from 'sos-sdk-core-ts/secure-message-crypto';
+/** Node.js CSPRNG adapter. All ML-KEM, KDF and AES operations remain in shared core. */
+export declare class NodeSecureRandomSource implements SecureRandomSource {
+    getRandomBytes(length: number): Promise<Uint8Array>;
+}
+/** Create runtime-neutral secure-message crypto with the Node.js CSPRNG boundary. */
+export declare const createNodeSecureMessageCrypto: () => MultiRecipientSecureMessageCrypto;

package/dist/secure-message-crypto.js

@@ -0,0 +1,14 @@
+import { randomBytes } from 'node:crypto';
+import { MultiRecipientSecureMessageCrypto, } from 'sos-sdk-core-ts/secure-message-crypto';
+const NODE_RANDOM_BYTES_MAX_LENGTH = 2 ** 31 - 1;
+/** Node.js CSPRNG adapter. All ML-KEM, KDF and AES operations remain in shared core. */
+export class NodeSecureRandomSource {
+    async getRandomBytes(length) {
+        if (!Number.isSafeInteger(length) || length <= 0 || length > NODE_RANDOM_BYTES_MAX_LENGTH) {
+            throw new Error('secure_random_length_invalid');
+        }
+        return new Uint8Array(randomBytes(length));
+    }
+}
+/** Create runtime-neutral secure-message crypto with the Node.js CSPRNG boundary. */
+export const createNodeSecureMessageCrypto = () => (new MultiRecipientSecureMessageCrypto(new NodeSecureRandomSource()));

package/docs/SECURE_MESSAGES.md

@@ -0,0 +1,32 @@
+# Secure messages in Node.js
+
+Use `createNodeSecureMessageCrypto()` from
+`sos-sdk-node-ts/secure-message-crypto`. The factory composes the shared
+runtime-neutral implementation with a Node CSPRNG adapter.
+
+```ts
+import { createNodeSecureMessageCrypto } from 'sos-sdk-node-ts/secure-message-crypto';
+
+const secureMessages = createNodeSecureMessageCrypto();
+const recipient = await secureMessages.generateRecipientKeyPair(deviceKeyId);
+
+const envelope = await secureMessages.seal({
+  plaintext: recordedAudioBytes,
+  contentType: 'audio/ogg',
+  recipients: [recipient],
+});
+```
+
+Written messages use the same call after UTF-8 encoding, for example with
+`contentType: 'text/plain;charset=utf-8'`. Decrypt the returned bytes only in
+an authorized recipient runtime; decode text or play audio after decryption.
+
+`NodeSecureRandomSource` validates the requested size and returns a fresh copy
+of `node:crypto.randomBytes(...)`. It does not own keys or perform any other
+cryptographic operation. Never replace it with `Math.random`, timestamps,
+identifiers or deterministic application data.
+
+Recipient lifecycle and authorization remain separate. A service may rewrap a
+CEK to current device/channel keys and remove its temporary recipient entry,
+but only after the product has authorized that change. The storage service
+persists the opaque envelope and does not need plaintext access.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "SOSChain-specific Node adapters over the shared runtime-neutral SOS SDK",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -19,6 +19,10 @@
     "./emergency-dispatch": {
       "types": "./dist/emergency-dispatch.d.ts",
       "default": "./dist/emergency-dispatch.js"
+    },
+    "./secure-message-crypto": {
+      "types": "./dist/secure-message-crypto.d.ts",
+      "default": "./dist/secure-message-crypto.js"
     }
   },
   "files": [
@@ -35,7 +39,7 @@
     "prepack": "npm run check"
   },
   "dependencies": {
-    "sos-sdk-core-ts": "0.2.0"
+    "sos-sdk-core-ts": "0.2.2"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",