@pulse-compute/provider-node 0.0.0 → 1.0.0-beta.2

package/src/runtime/conditional-kv.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+const host = require('@pulse-compute/runtime/host');
+
+// One explicit instance is one local authority. Reuse it across requests/targets
+// to exercise shared storage. Identity/sequence injection is for deterministic
+// host tests, never application input. This is not durable production storage.
+function createNodeKvReference(options = {}) {
+  const identity = options.kvInstanceId === undefined ? randomUUID() : options.kvInstanceId;
+  if (typeof identity !== 'string' || !/^[a-zA-Z0-9_-]{1,64}$/.test(identity)) throw new TypeError('Node KV instance identity must be bounded ASCII.');
+  let sequence = options.kvGenerationStart === undefined ? 0n : BigInt(options.kvGenerationStart);
+  if (sequence < 0n || sequence >= (1n << 128n)) throw new TypeError('Node KV generation sequence is out of range.');
+  const stores = new Map(), records = new Map();
+  const hooks = options.kvHooks || {};
+  function nextGeneration() {
+    if (sequence >= (1n << 128n) - 1n) throw new Error('Node KV generation space exhausted.');
+    sequence += 1n;
+    return `node-kv-v1:${identity}:${sequence.toString(16).padStart(32, '0')}`;
+  }
+  function namespace(name) {
+    host.normalizeKvNamespace(name, options);
+    if (!stores.has(name)) { stores.set(name, new Map()); records.set(name, new Map()); }
+    return { values: stores.get(name), entries: records.get(name) };
+  }
+  function put(name, key, value) {
+    const { entries, values } = namespace(name);
+    const wire = host.encodeConditionalKvValue(value, options);
+    const detached = host.decodeConditionalKvValue(wire, options);
+    const generation = nextGeneration();
+    entries.set(key, { wire, generation }); values.set(key, detached);
+  }
+  // Reject accessors instead of executing configuration as ambient code.
+  function entries(input) {
+    if (input === undefined || input === null) return [];
+    if (typeof input !== 'object' || Array.isArray(input) || ![null, Object.prototype].includes(Object.getPrototypeOf(input))) throw new TypeError('Node KV seed must be a data record.');
+    return Reflect.ownKeys(input).map((key) => {
+      const d = Object.getOwnPropertyDescriptor(input, key);
+      if (typeof key !== 'string' || !d.enumerable || !Object.prototype.hasOwnProperty.call(d, 'value')) throw new TypeError('Node KV seed must contain data properties.');
+      return [key, d.value];
+    });
+  }
+  for (const [name, values] of entries(options.kv)) for (const [key, value] of entries(values)) {
+    host.normalizeKvKey(key, options); put(name, key, value);
+  }
+  function apply(effect) {
+    const { entries } = namespace(effect.namespace);
+    const current = entries.get(effect.key);
+    if (effect.kind === 'kv.getVersioned') return current
+      ? Object.freeze({ status: 'found', generation: current.generation, value: host.decodeConditionalKvValue(current.wire, options) })
+      : Object.freeze({ status: 'not-found' });
+    if (effect.kind === 'kv.compareAndSwap' && !new RegExp(`^node-kv-v1:${identity}:[0-9a-f]{32}$`).test(effect.generation)) {
+      return Object.freeze({ status: 'not-stored', reason: 'invalid-generation' });
+    }
+    // No await, callback, or provider GET/PUT between predicate and mutation.
+    const matches = effect.kind === 'kv.insertIfAbsent' ? !current : current && current.generation === effect.generation;
+    if (!matches) return Object.freeze({ status: 'conflict' });
+    put(effect.namespace, effect.key, effect.value);
+    return Object.freeze({ status: 'stored' });
+  }
+  async function prepareConditionalKv(effect, execution = {}) {
+    if (hooks.prepare) await hooks.prepare(effect, execution);
+    return async () => {
+      if (hooks.dispatch) await hooks.dispatch(effect, execution);
+      if (execution.signal && execution.signal.aborted) throw new Error('Node KV operation stopped before acceptance.');
+      const result = apply(effect);
+      if (result.status === 'found' && hooks.read) return hooks.read(result, effect, execution);
+      if (result.status === 'stored' && hooks.afterCommit) await hooks.afterCommit(effect, execution);
+      return result;
+    };
+  }
+  return Object.freeze({
+    version: 'pulse.node-kv-reference.v1',
+    prepareConditionalKv,
+    // Historical Assets reads use this semantic view, never the generation table.
+    legacyStores() { return stores; },
+    kv(name) {
+      const { values } = namespace(name);
+      const conditional = (operation, key, generation, value) => {
+        const admitted = host.admitConditionalKv({ kind: `kv.${operation}`, namespace: name, key, generation, value }, options);
+        return host.executeConditionalKv(admitted, prepareConditionalKv, {}, options);
+      };
+      return Object.freeze({
+        get(key) { host.normalizeKvKey(key, options); return host.cloneKvValue(values.get(key), { ...options, allowUndefined: true }); },
+        put(key, value) { host.normalizeKvKey(key, options); put(name, key, value); return true; },
+        getVersioned(key) { return conditional('getVersioned', key); },
+        insertIfAbsent(key, value) { return conditional('insertIfAbsent', key, undefined, value); },
+        compareAndSwap(key, generation, value) { return conditional('compareAndSwap', key, generation, value); }
+      });
+    }
+  });
+}
+module.exports = Object.freeze({ createNodeKvReference });

package/src/runtime/index.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const compiledWasmNodeAdapterKv = require('./compiled-wasm-node-adapter-kv.js');
+const assetsProvider = require('./assets-provider.js');
+const routeHandlerEffects = require('./route-handler-effects.js');
+const canonicalApiRuntime = require('./canonical-api-runtime.js');
+
+module.exports = {
+  ...require('./conditional-kv.js'),
+  compiledWasmNodeAdapterKv,
+  assetsProvider,
+  routeHandlerEffects,
+  canonicalApiRuntime,
+  ...compiledWasmNodeAdapterKv,
+  ...assetsProvider,
+  ...routeHandlerEffects,
+  ...canonicalApiRuntime
+};

package/src/runtime/jwt-verifier.js

@@ -0,0 +1,264 @@
+'use strict';
+
+const {
+  CRYPTO_ES256_GUEST_LINKED_IMPLEMENTATION,
+  CRYPTO_ES256_GUEST_LINKED_REALIZATION,
+  CRYPTO_GUEST_SOURCE_IMPLEMENTATION
+} = require('@pulse-compute/wasm-contracts/crypto/contracts');
+
+const NODE_NATIVE_JWT_VERIFIER_VERSION = 'pulse.node-native-jwt-verifier.v1';
+const NODE_NATIVE_JWT_REALIZATIONS = Object.freeze({
+  HS256: Object.freeze({
+    algorithm: 'HS256',
+    realization: 'guest-source:pulse-hmac-as',
+    implementation: CRYPTO_GUEST_SOURCE_IMPLEMENTATION,
+    guestUnitRequired: false
+  }),
+  ES256: Object.freeze({
+    algorithm: 'ES256',
+    realization: CRYPTO_ES256_GUEST_LINKED_REALIZATION,
+    implementation: CRYPTO_ES256_GUEST_LINKED_IMPLEMENTATION,
+    guestUnitRequired: true
+  })
+});
+const NODE_NATIVE_JWT_REALIZATION = Object.freeze({
+  ...NODE_NATIVE_JWT_REALIZATIONS.HS256,
+  semanticOwner: '@pulse-compute/crypto',
+  automaticFallback: false
+});
+
+let providerModule;
+
+function dataRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  let prototype;
+  try { prototype = Object.getPrototypeOf(value); }
+  catch { return undefined; }
+  if (prototype !== Object.prototype && prototype !== null) return undefined;
+  const output = new Map();
+  try {
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== 'string') return undefined;
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (
+        !descriptor
+        || !descriptor.enumerable
+        || !Object.prototype.hasOwnProperty.call(descriptor, 'value')
+      ) return undefined;
+      output.set(key, descriptor.value);
+    }
+  } catch {
+    return undefined;
+  }
+  return output;
+}
+
+async function loadJwtProvider() {
+  if (!providerModule) providerModule = import('@pulse-compute/jwt/provider');
+  return providerModule;
+}
+
+function requestActive(executionOptions, jwtProvider) {
+  const execution = dataRecord(executionOptions);
+  const signal = execution && execution.get('signal');
+  if (signal && signal.aborted) {
+    throw jwtProvider.jwtError('PULSE_JWT_OPERATION_FAILED', {
+      category: 'request-cancelled',
+      automaticFallback: false
+    });
+  }
+}
+
+function requireCryptoVerifier(executionOptions, jwtProvider, algorithm) {
+  const execution = dataRecord(executionOptions);
+  const realization = dataRecord(execution && execution.get('cryptoRealization'));
+  const verifier = execution && execution.get('cryptoVerifier');
+  const expected = NODE_NATIVE_JWT_REALIZATIONS[algorithm];
+  const algorithms = realization && realization.get('algorithms');
+  const selected = Array.isArray(algorithms)
+    ? algorithms.map(dataRecord).find((entry) => (
+        entry
+        && expected
+        && entry.get('algorithm') === expected.algorithm
+        && entry.get('realization') === expected.realization
+        && entry.get('implementation') === expected.implementation
+        && entry.get('guestUnitRequired') === expected.guestUnitRequired
+        && entry.get('available') === true
+      ))
+    : undefined;
+  if (
+    !expected
+    || !realization
+    || realization.get('semanticOwner') !== '@pulse-compute/crypto'
+    || realization.get('automaticFallback') !== false
+    || !selected
+    || !dataRecord(verifier)
+  ) {
+    throw jwtProvider.jwtError('PULSE_JWT_TARGET_UNSUPPORTED', {
+      category: 'crypto-realization',
+      realization: expected && expected.realization,
+      implementation: expected && expected.implementation,
+      automaticFallback: false
+    });
+  }
+  return verifier;
+}
+
+function keyArtifact(executionOptions, artifactId, jwtProvider) {
+  const execution = dataRecord(executionOptions);
+  const artifacts = execution && execution.get('packageArtifacts');
+  const matches = Array.isArray(artifacts)
+    ? artifacts.filter((artifact) => {
+        const record = dataRecord(artifact);
+        return record && record.get('id') === artifactId;
+      })
+    : [];
+  if (matches.length !== 1) {
+    throw jwtProvider.jwtError('PULSE_JWT_KEY_INVALID', {
+      category: 'key-artifact',
+    });
+  }
+  const artifact = dataRecord(matches[0]);
+  const data = artifact && dataRecord(artifact.get('data'));
+  if (
+    !artifact
+    || artifact.get('version') !== 'pulse.jwt-es256-key-artifact.v1'
+    || artifact.get('contractId') !== 'pulse.jwt'
+    || artifact.get('package') !== '@pulse-compute/jwt'
+    || artifact.get('kind') !== 'jwt-es256-static-public-key'
+    || !data
+  ) {
+    throw jwtProvider.jwtError('PULSE_JWT_KEY_INVALID', {
+      category: 'key-artifact',
+    });
+  }
+  return Object.freeze(Object.fromEntries(data));
+}
+
+function effectInput(effect, executionOptions, jwtProvider) {
+  const record = dataRecord(effect);
+  const payload = dataRecord(record && record.get('payload'));
+  const resource = dataRecord(record && record.get('resource'));
+  if (
+    !record
+    || record.get('kind') !== 'jwt.verify'
+    || record.get('contractId') !== 'pulse.jwt'
+    || record.get('operation') !== 'verify'
+    || !payload
+    || !resource
+  ) {
+    throw jwtProvider.jwtError('PULSE_JWT_OPERATION_FAILED', {
+      category: 'verifier-input'
+    });
+  }
+  const authorization = payload.get('token');
+  if (authorization !== undefined && typeof authorization !== 'string') {
+    throw jwtProvider.jwtError('PULSE_JWT_BEARER_INVALID', {
+      category: 'authorization'
+    });
+  }
+  const keyType = resource.get('keyType');
+  const binding = resource.get('secretBinding');
+  const artifactId = resource.get('keyArtifactId');
+  let key;
+  if (keyType === 'secret') {
+    if (
+      artifactId !== null
+      || typeof binding !== 'string'
+      || binding.length === 0
+    ) throw jwtProvider.jwtError('PULSE_JWT_KEY_INVALID', {
+      category: 'secret-binding'
+    });
+    key = Object.freeze({ type: 'secret', binding });
+  } else if (keyType === 'jwk' || keyType === 'jwks') {
+    if (binding !== null || typeof artifactId !== 'string' || artifactId.length === 0) {
+      throw jwtProvider.jwtError('PULSE_JWT_KEY_INVALID', {
+        category: 'key-artifact'
+      });
+    }
+    key = keyArtifact(executionOptions, artifactId, jwtProvider);
+    if (key.type !== keyType) throw jwtProvider.jwtError('PULSE_JWT_KEY_INVALID', {
+      category: 'key-artifact'
+    });
+  } else {
+    throw jwtProvider.jwtError('PULSE_JWT_KEY_INVALID', { category: 'key' });
+  }
+  const policy = Object.fromEntries(
+    [...payload.entries()].filter(([name]) => name !== 'token')
+  );
+  return Object.freeze({
+    token: jwtProvider.bearerFromAuthorizationValue(authorization),
+    options: Object.freeze({
+      ...policy,
+      key
+    })
+  });
+}
+
+function createNodeNativeJwtVerify(baseOptions = {}) {
+  const secretLookup = baseOptions.secretLookup;
+  const captureWallClock = baseOptions.captureWallClock
+    || (() => Object.freeze({
+      unixEpochSeconds: Date.now() / 1000,
+      trusted: true
+    }));
+  return async function verifyNodeNativeJwt(effect, executionOptions = {}) {
+    const jwtProvider = await loadJwtProvider();
+    requestActive(executionOptions, jwtProvider);
+    const input = effectInput(effect, executionOptions, jwtProvider);
+    const selectedCrypto = requireCryptoVerifier(
+      executionOptions,
+      jwtProvider,
+      input.options.algorithms[0]
+    );
+    const execution = dataRecord(executionOptions);
+    const executionClock = execution && execution.get('captureJwtWallClock');
+    const host = {
+      async captureWallClock() {
+        requestActive(executionOptions, jwtProvider);
+        const captured = await (
+          typeof executionClock === 'function'
+            ? executionClock()
+            : captureWallClock()
+        );
+        requestActive(executionOptions, jwtProvider);
+        return captured;
+      },
+      resolveSecret: typeof secretLookup === 'function'
+        ? async (binding) => {
+            requestActive(executionOptions, jwtProvider);
+            const secret = await secretLookup(binding, executionOptions);
+            requestActive(executionOptions, jwtProvider);
+            return secret;
+          }
+        : undefined,
+      registerSensitiveValue(value) {
+        const register = execution && execution.get('registerRedactionValue');
+        if (typeof register === 'function') register(value);
+      }
+    };
+    const validateSchemaValue = execution && execution.get('validateSchemaValue');
+    if (typeof validateSchemaValue === 'function') {
+      host.validateClaims = async (schemaId, claims, context) => {
+        requestActive(executionOptions, jwtProvider);
+        const result = await validateSchemaValue(schemaId, claims, context);
+        requestActive(executionOptions, jwtProvider);
+        return result;
+      };
+    }
+    const result = await jwtProvider.verifyJwtWithCrypto(
+      input,
+      Object.freeze(host),
+      selectedCrypto
+    );
+    requestActive(executionOptions, jwtProvider);
+    return result;
+  };
+}
+
+module.exports = Object.freeze({
+  NODE_NATIVE_JWT_VERIFIER_VERSION,
+  NODE_NATIVE_JWT_REALIZATION,
+  NODE_NATIVE_JWT_REALIZATIONS,
+  createNodeNativeJwtVerify
+});