@pulse-compute/crypto 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -6,15 +6,16 @@
 > **Install directly:** Yes, when an application uses the crypto verification surface directly; JWT applications receive it transitively.<br>
 > **Supported entry points:** `@pulse-compute/crypto`<br>
 > **Stability:** The package root is the supported bounded verification contract; realization and Native integration subpaths remain toolchain-only.<br>
-> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.1/packages/crypto/)
+> **npm:** [`@pulse-compute/crypto`](https://www.npmjs.com/package/@pulse-compute/crypto)<br>
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.2/packages/crypto/)
 >
-> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.1` package policy.
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.2` package policy.
 <!-- pulse-package-status:end -->
 
 Provider-neutral cryptographic verification contracts for Pulse.
 
 This package and `@pulse-compute/jwt` are members of the synchronized
-`1.0.0-beta.1` release catalog.
+`1.0.0-beta.2` release catalog.
 
 ## Verification contract
 
@@ -125,3 +126,15 @@ The G3 composition and shared ES256 corpus are recorded in
 `wasm/.test-results/jwt-g3/jwt-g3-evidence.json`. This working-candidate proof
 does not add signing, remote key discovery, fallback, publication, or
 deployment.
+
+## Trusted byte-output composition
+
+S3 uses Crypto-owned SHA-256 and HMAC-SHA256 byte outputs. Native composes the
+existing guest-source unit; Node JavaScript explicitly binds Web Crypto through
+`@pulse-compute/crypto/provider`. The trusted seam snapshots Uint8Array input,
+allows at most 32768 data bytes and 8192 HMAC key bytes, returns exactly 32 bytes,
+and wipes input staging on success or failure. It rejects unavailable selected
+primitives and does not fall back. Empty HMAC keys use the equivalent padded
+zero block required by HMAC, preserving Native semantics despite Web Crypto's
+zero-length import restriction. This provider seam does not add an author-facing
+signing API or change JWT key limits.

package/as/pulse-hmac-as.ts

@@ -313,3 +313,32 @@ export function pulse_crypto_hs256_verify(
   __pulse_crypto_wipe(expected)
   return result
 }
+
+// Internal digest/MAC output contract. This frame is a rooted allocation owned
+// by Crypto; host callers may stage synchronously, copy the output, then wipe.
+// It does not grow Wasm memory per operation or overlap allocator-owned memory.
+const __pulse_crypto_bytes_frame = new Uint8Array(8192 + 32768 + 32)
+export function pulse_crypto_bytes_frame_v1(): i32 {
+  return <i32>__pulse_crypto_bytes_frame.dataStart
+}
+
+export function pulse_crypto_sha256_bytes_v1(dataPointer: i32, dataLength: i32, outputPointer: i32, outputLength: i32): i32 {
+  if (dataLength < 0 || dataLength > 32768 || outputLength != 32
+    || !__pulse_crypto_memory_range_valid(dataPointer, dataLength)
+    || !__pulse_crypto_memory_range_valid(outputPointer, outputLength)) return __PULSE_CRYPTO_INVALID_INPUT
+  const digest = __pulse_crypto_sha256_memory(<usize><u32>dataPointer, dataLength)
+  for (let i: i32 = 0; i < 32; i++) store<u8>(<usize><u32>outputPointer + <usize>i, unchecked(digest[i]))
+  __pulse_crypto_wipe(digest)
+  return __PULSE_CRYPTO_VALID
+}
+
+export function pulse_crypto_hmac_sha256_bytes_v1(keyPointer: i32, keyLength: i32, dataPointer: i32, dataLength: i32, outputPointer: i32, outputLength: i32): i32 {
+  if (keyLength < 0 || keyLength > 8192 || !__pulse_crypto_memory_range_valid(keyPointer, keyLength)) return __PULSE_CRYPTO_INVALID_KEY
+  if (dataLength < 0 || dataLength > 32768 || outputLength != 32
+    || !__pulse_crypto_memory_range_valid(dataPointer, dataLength)
+    || !__pulse_crypto_memory_range_valid(outputPointer, outputLength)) return __PULSE_CRYPTO_INVALID_INPUT
+  const digest = __pulse_crypto_hmac_sha256(<usize><u32>keyPointer, keyLength, <usize><u32>dataPointer, dataLength)
+  for (let i: i32 = 0; i < 32; i++) store<u8>(<usize><u32>outputPointer + <usize>i, unchecked(digest[i]))
+  __pulse_crypto_wipe(digest)
+  return __PULSE_CRYPTO_VALID
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-compute/crypto",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "license": "Apache-2.0",
   "engines": {
     "node": "^22.14.0 || ^24.0.0"
@@ -14,13 +14,15 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./pulsewasm-native": "./pulsewasm.native.cjs"
+    "./pulsewasm-native": "./pulsewasm.native.cjs",
+    "./provider": "./src/provider.cjs"
   },
   "files": [
     "as",
     "dist",
     "pulsewasm.native.cjs",
     "README.md",
+    "src/provider.cjs",
     "LICENSE",
     "NOTICE"
   ],
@@ -35,7 +37,7 @@
   "bugs": {
     "url": "https://github.com/pulse-compute/pulse/issues"
   },
-  "homepage": "https://pulsecompute.io/v1.0.0-beta.1/packages/crypto/",
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.2/packages/crypto/",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {

package/pulsewasm.native.cjs

@@ -14,7 +14,8 @@ function sha256(value) {
   return crypto.createHash('sha256').update(value).digest('hex');
 }
 
-function pulseHmacAssemblyScriptSource() {
+function pulseHmacAssemblyScriptSource(algorithm = 'HS256') {
+  if (!['HS256', 'SHA-256', 'HMAC-SHA256'].includes(algorithm)) throw new TypeError('Unsupported Crypto guest-source algorithm.');
   const source = fs.readFileSync(sourceFile, 'utf8');
   return Object.freeze({
     version: CRYPTO_GUEST_SOURCE_CONTRACT_VERSION,
@@ -25,7 +26,7 @@ function pulseHmacAssemblyScriptSource() {
     kind: 'guest-source',
     backend: 'pulse-hmac-as',
     backendVersion: 'pulse-hmac-as.v1',
-    algorithm: 'HS256',
+    algorithm,
     language: 'assemblyscript',
     license: 'Apache-2.0',
     origin: 'package-source',
@@ -42,13 +43,20 @@ function pulseHmacAssemblyScriptSource() {
     imports: Object.freeze([]),
     exports: Object.freeze([
       'pulse_crypto_hs256_verify',
-      'pulse_crypto_sha256_digest'
+      'pulse_crypto_sha256_digest',
+      'pulse_crypto_bytes_frame_v1',
+      'pulse_crypto_sha256_bytes_v1',
+      'pulse_crypto_hmac_sha256_bytes_v1'
     ]),
     resourceLimits: Object.freeze({
       hmacKeyBytesMinimum: 32,
       hmacKeyBytesMaximum: 4 * 1024,
       macDataBytesMaximum: 1024 * 1024,
-      hs256TagBytes: 32
+      hs256TagBytes: 32,
+      byteOperationKeyBytesMaximum: 8192,
+      byteOperationDataBytesMaximum: 32768,
+      byteOperationOutputBytes: 32,
+      byteOperationFrameBytes: 40992
     }),
     resultCodes: Object.freeze({
       valid: 1,
@@ -66,6 +74,39 @@ function pulseHmacAssemblyScriptSource() {
   });
 }
 
+function bindNativeDigestMac(moduleExports) {
+  const memory = moduleExports && moduleExports.memory;
+  const names = ['pulse_crypto_bytes_frame_v1', 'pulse_crypto_sha256_bytes_v1', 'pulse_crypto_hmac_sha256_bytes_v1'];
+  if (!(memory instanceof WebAssembly.Memory) || names.some((name) => typeof moduleExports[name] !== 'function')) {
+    throw new TypeError('Native Crypto digest/MAC exports are unavailable.');
+  }
+  const frameBytes = 8192 + 32768 + 32;
+  function run(data, key) {
+    if (!(data instanceof Uint8Array) || data.length > 32768
+      || (key !== undefined && (!(key instanceof Uint8Array) || key.length > 8192))) {
+      throw new TypeError('Native Crypto digest/MAC input exceeds its byte contract.');
+    }
+    const pointer = moduleExports.pulse_crypto_bytes_frame_v1() >>> 0;
+    if (pointer + frameBytes > memory.buffer.byteLength) throw new TypeError('Native Crypto frame is outside memory.');
+    const dataPointer = pointer + 8192;
+    const outputPointer = dataPointer + 32768;
+    try {
+      const view = new Uint8Array(memory.buffer);
+      view.set(data, dataPointer);
+      if (key !== undefined) view.set(key, pointer);
+      const code = key === undefined
+        ? moduleExports.pulse_crypto_sha256_bytes_v1(dataPointer, data.length, outputPointer, 32)
+        : moduleExports.pulse_crypto_hmac_sha256_bytes_v1(pointer, key.length, dataPointer, data.length, outputPointer, 32);
+      if (code !== 1) throw new TypeError('Native Crypto digest/MAC realization failed.');
+      return new Uint8Array(memory.buffer, outputPointer, 32).slice();
+    } finally {
+      // The Wasm allocator can grow memory while hashing: acquire a fresh view.
+      new Uint8Array(memory.buffer, pointer, frameBytes).fill(0);
+    }
+  }
+  return Object.freeze({ sha256: (data) => run(data), hmacSha256: (key, data) => run(data, key) });
+}
+
 function pulseEs256GuestUnit() {
   return Object.freeze({
     version: GUEST_UNIT_CONTRIBUTION_VERSION,
@@ -81,5 +122,6 @@ module.exports = Object.freeze({
   CRYPTO_GUEST_SOURCE_CONTRACT_VERSION,
   GUEST_UNIT_CONTRIBUTION_VERSION,
   pulseHmacAssemblyScriptSource,
+  bindNativeDigestMac,
   pulseEs256GuestUnit
 });

package/src/provider.cjs

@@ -0,0 +1,43 @@
+'use strict';
+
+// Trusted provider byte-output seam. JWT verification keeps its own key limits.
+const IMPLEMENTATIONS = Object.freeze({
+  'SHA-256': 'webcrypto.subtle.sha-256-bytes.v1',
+  'HMAC-SHA256': 'webcrypto.subtle.hmac-sha-256-bytes.v1'
+});
+function snapshot(value, maximum) {
+  if (!(value instanceof Uint8Array) || value.byteLength > maximum) throw new TypeError('Crypto byte input is outside its bound.');
+  return new Uint8Array(value);
+}
+function result(value) {
+  if (!(value instanceof ArrayBuffer) || value.byteLength !== 32) throw new TypeError('Crypto byte output is invalid.');
+  return new Uint8Array(value);
+}
+function bindJavascriptDigestMac(algorithms, subtle = globalThis.crypto && globalThis.crypto.subtle) {
+  if (!Array.isArray(algorithms) || new Set(algorithms).size !== algorithms.length || algorithms.some((name) => !Object.hasOwn(IMPLEMENTATIONS, name))) throw new TypeError('Crypto requires explicit supported byte algorithms.');
+  if (!subtle || algorithms.includes('SHA-256') && typeof subtle.digest !== 'function'
+    || algorithms.includes('HMAC-SHA256') && (typeof subtle.sign !== 'function' || typeof subtle.importKey !== 'function')) throw new TypeError('Selected Web Crypto byte realization is unavailable.');
+  const bytes = {};
+  if (algorithms.includes('SHA-256')) bytes.sha256 = async (input) => {
+    const data = snapshot(input, 32768);
+    try { return result(await subtle.digest({ name: 'SHA-256' }, data)); }
+    finally { data.fill(0); }
+  };
+  if (algorithms.includes('HMAC-SHA256')) bytes.hmacSha256 = async (keyInput, input) => {
+    let key = snapshot(keyInput, 8192);
+    let data;
+    try {
+      data = snapshot(input, 32768);
+      // HMAC pads an empty key to a zero block (RFC 2104). Web Crypto rejects
+      // a zero-length import; the equivalent padded block retains Native parity.
+      if (key.length === 0) key = new Uint8Array(64);
+      const imported = await subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256', length: key.length * 8 }, false, ['sign']);
+      return result(await subtle.sign({ name: 'HMAC' }, imported, data));
+    } finally { key.fill(0); if (data) data.fill(0); }
+  };
+  return Object.freeze({ bytes: Object.freeze(bytes), realization: Object.freeze({
+    target: 'javascript', automaticFallback: false,
+    algorithms: Object.freeze(algorithms.map((algorithm) => Object.freeze({ algorithm, realization: 'runtime-builtin', implementation: IMPLEMENTATIONS[algorithm], available: true, automaticFallback: false })))
+  }) });
+}
+module.exports = Object.freeze({ IMPLEMENTATIONS, bindJavascriptDigestMac });