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

package/README.md

@@ -1,5 +1,140 @@
-# @pulse-compute/crypto
+# `@pulse-compute/crypto`
 
-> Bootstrap placeholder — no runtime or API.
+<!-- pulse-package-status:start -->
+> **Support tier:** Supported provider/extension surface<br>
+> **Audience:** Applications and first-party packages using provider-neutral cryptographic verification.<br>
+> **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>
+> **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.2` package policy.
+<!-- pulse-package-status:end -->
 
-This inert 0.0.0 package reserves the npm name for future Pulse releases.
+Provider-neutral cryptographic verification contracts for Pulse.
+
+This package and `@pulse-compute/jwt` are members of the synchronized
+`1.0.0-beta.2` release catalog.
+
+## Verification contract
+
+This package owns the verification surface while target planning owns backend
+selection. HS256 uses the MAC seam:
+
+```ts
+import { crypto } from '@pulse-compute/crypto'
+
+const result = await crypto.mac.verify({
+  algorithm: 'HS256',
+  key: {
+    type: 'hmac-key-bytes',
+    bytes: secretBytes,
+  },
+  data: messageBytes,
+  tag: authenticatorBytes,
+})
+```
+
+Keys, messages, and authenticators are byte inputs. The package never performs
+ambient string encoding. HS256 keys must be between 32 bytes and 4 KiB, data is
+bounded to 1 MiB, and authenticators are exactly 32 bytes.
+
+Verification returns one frozen, status-only result:
+
+- `valid`
+- `invalid-authenticator`
+- `invalid-key`
+- `invalid-input`
+- `realization-failure`
+
+Backend objects, error text, key material, messages, and authenticators do not
+cross the result boundary.
+
+G3 also activates ES256 through the signature seam. Its normalized request
+contains an exact 64-byte P-256 public key (`x || y`), the original signing
+input bytes, and an exact 64-byte JOSE signature (`r || s`). JavaScript keeps
+Web Crypto key objects inside the runtime-builtin adapter. Native uses the
+audited `guest-linked:pulse-es256-rustcrypto-p256` unit. Both return the same
+status-only result taxonomy, and neither retries another realization.
+
+Pulse profiles can declare HS256 and ES256 globally or replace that declaration
+in a named profile:
+
+```ts
+pulse: {
+  crypto: ['HS256', 'ES256'],
+},
+prod: {
+  crypto: {
+    HS256: { realization: 'guest-source:pulse-hmac-as' },
+    ES256: { realization: 'guest-linked:pulse-es256-rustcrypto-p256' },
+  },
+},
+```
+
+An empty array or object explicitly declares no algorithms. Planning considers
+only requirements emitted by reachable packages, resolves every declared
+algorithm against the selected target, reports the exact realization, and
+fails before lowering when the relationship
+`reachable demand ⊆ profile declaration ⊆ target capability` is invalid.
+Selection never enables detection or fallback.
+
+JavaScript targets now execute the selected `runtime-builtin` realization
+through Web Crypto with explicit HMAC/SHA-256 or ECDSA/P-256/SHA-256
+parameters. ES256 validates the normalized point before constructing a
+runtime-private public JWK, so malformed points cannot escape into a target's
+Web Crypto implementation. Key import and verification stay inside the
+byte-only public boundary; invalid authenticators, invalid keys, unavailable
+runtimes, and operation failures return normalized status-only results.
+
+The implementation imports no Node API and represents Node, browser, and
+Fastly JavaScript uniformly as `runtime-builtin`. It is not a Fastly Native
+host ABI.
+
+The Native realization is `guest-source:pulse-hmac-as`: first-party
+AssemblyScript compiled into the primary Native module. It implements bounded
+SHA-256 and HMAC-SHA-256, scans every authenticator byte before branching, and
+has no host imports, guest-link dependency, runtime probing, or fallback. Its
+source provenance, hash, resource limits, exports, and disabled-fallback posture
+are recorded in the Native manifest without recording key, data, or tag bytes.
+
+The crypto seal uses one versioned corpus for the JavaScript Web Crypto and Native
+AssemblyScript realizations. The corpus includes published RFC 4231 vectors,
+authenticator mismatches at the first, middle, and last byte, altered inputs,
+invalid key and tag shapes, and empty, maximum, and over-limit messages. The
+same proof covers profile replacement without array or object merging,
+unavailable exact realization pins, target capability failures, normalized
+result categories, disabled fallback, and report redaction.
+
+The Phase C seal records the locally observed artifact impact rather than treating
+it as a portable benchmark. With the repository's pinned toolchain, the
+default Native fixture grew from 2,212 to 5,385 bytes (3,173 bytes), and the
+experimental size profile grew from 2,058 to 4,951 bytes (2,893 bytes). The
+five emitted JavaScript runtime modules total 7,676 bytes, or 1,962 gzip bytes.
+
+## JWT composition
+
+`@pulse-compute/jwt` depends directly on this package. It uses `mac.verify` for
+HS256 and `signature.verify` for ES256. JWT owns compact-JWS, bounded public
+JWK/JWKS selection, and claims semantics; crypto owns fixed-width byte
+normalization, backend realization, and normalized authenticity status.
+Neither package duplicates the other's responsibility, and JWT has no active
+`jose`, Web Crypto, guest-direct, or provider-direct crypto path.
+
+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

@@ -0,0 +1,344 @@
+/*
+ * Pulse first-party HS256 guest-source realization.
+ *
+ * Algorithm sources:
+ * - NIST FIPS 180-4, Secure Hash Standard (SHA-256)
+ * - RFC 2104, HMAC
+ * - RFC 4231, HMAC-SHA test vectors
+ *
+ * This implementation is original Apache-2.0 Pulse source derived from the
+ * published algorithms. It has no host imports, ambient text encoding, or
+ * guest-link dependency.
+ */
+
+const __PULSE_CRYPTO_VALID: i32 = 1
+const __PULSE_CRYPTO_INVALID_AUTHENTICATOR: i32 = 0
+const __PULSE_CRYPTO_INVALID_KEY: i32 = -1
+const __PULSE_CRYPTO_INVALID_INPUT: i32 = -2
+
+const __PULSE_CRYPTO_HS256_KEY_MIN: i32 = 32
+const __PULSE_CRYPTO_HS256_KEY_MAX: i32 = 4096
+const __PULSE_CRYPTO_HS256_DATA_MAX: i32 = 1024 * 1024
+const __PULSE_CRYPTO_HS256_TAG_BYTES: i32 = 32
+const __PULSE_CRYPTO_SHA256_BLOCK_BYTES: i32 = 64
+
+const __PULSE_CRYPTO_SHA256_K = StaticArray.fromArray<u32>([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5,
+  0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+  0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
+  0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
+  0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+])
+
+@inline
+function __pulse_crypto_rotr(value: u32, bits: i32): u32 {
+  return (value >>> bits) | (value << (32 - bits))
+}
+
+class __PulseCryptoSha256 {
+  private state: StaticArray<u32> = StaticArray.fromArray<u32>([
+    0x6a09e667,
+    0xbb67ae85,
+    0x3c6ef372,
+    0xa54ff53a,
+    0x510e527f,
+    0x9b05688c,
+    0x1f83d9ab,
+    0x5be0cd19,
+  ])
+  private block: StaticArray<u8> = new StaticArray<u8>(__PULSE_CRYPTO_SHA256_BLOCK_BYTES)
+  private schedule: StaticArray<u32> = new StaticArray<u32>(64)
+  private blockLength: i32 = 0
+  private totalBytes: u64 = 0
+
+  updateByte(value: u8): void {
+    unchecked(this.block[this.blockLength] = value)
+    this.blockLength += 1
+    this.totalBytes += 1
+    if (this.blockLength == __PULSE_CRYPTO_SHA256_BLOCK_BYTES) {
+      this.transform()
+      this.blockLength = 0
+    }
+  }
+
+  updateMemory(pointer: usize, length: i32): void {
+    for (let index: i32 = 0; index < length; index += 1) {
+      this.updateByte(load<u8>(pointer + <usize>index))
+    }
+  }
+
+  updateStatic(bytes: StaticArray<u8>, length: i32): void {
+    for (let index: i32 = 0; index < length; index += 1) {
+      this.updateByte(unchecked(bytes[index]))
+    }
+  }
+
+  finish(): StaticArray<u8> {
+    const bitLength = this.totalBytes * 8
+    this.updateByte(0x80)
+    while (this.blockLength != 56) this.updateByte(0)
+    for (let shift: i32 = 56; shift >= 0; shift -= 8) {
+      this.updateByte(<u8>(bitLength >> shift))
+    }
+
+    const output = new StaticArray<u8>(__PULSE_CRYPTO_HS256_TAG_BYTES)
+    for (let wordIndex: i32 = 0; wordIndex < 8; wordIndex += 1) {
+      const word = unchecked(this.state[wordIndex])
+      const offset = wordIndex * 4
+      unchecked(output[offset] = <u8>(word >> 24))
+      unchecked(output[offset + 1] = <u8>(word >> 16))
+      unchecked(output[offset + 2] = <u8>(word >> 8))
+      unchecked(output[offset + 3] = <u8>word)
+    }
+    for (let index: i32 = 0; index < this.state.length; index += 1) {
+      unchecked(this.state[index] = 0)
+    }
+    for (let index: i32 = 0; index < this.block.length; index += 1) {
+      unchecked(this.block[index] = 0)
+    }
+    for (let index: i32 = 0; index < this.schedule.length; index += 1) {
+      unchecked(this.schedule[index] = 0)
+    }
+    return output
+  }
+
+  private transform(): void {
+    const schedule = this.schedule
+    for (let index: i32 = 0; index < 16; index += 1) {
+      const offset = index * 4
+      unchecked(schedule[index] =
+        (<u32>unchecked(this.block[offset]) << 24)
+        | (<u32>unchecked(this.block[offset + 1]) << 16)
+        | (<u32>unchecked(this.block[offset + 2]) << 8)
+        | <u32>unchecked(this.block[offset + 3]))
+    }
+    for (let index: i32 = 16; index < 64; index += 1) {
+      const before15 = unchecked(schedule[index - 15])
+      const before2 = unchecked(schedule[index - 2])
+      const sigma0 = __pulse_crypto_rotr(before15, 7)
+        ^ __pulse_crypto_rotr(before15, 18)
+        ^ (before15 >>> 3)
+      const sigma1 = __pulse_crypto_rotr(before2, 17)
+        ^ __pulse_crypto_rotr(before2, 19)
+        ^ (before2 >>> 10)
+      unchecked(schedule[index] =
+        unchecked(schedule[index - 16])
+        + sigma0
+        + unchecked(schedule[index - 7])
+        + sigma1)
+    }
+
+    let a = unchecked(this.state[0])
+    let b = unchecked(this.state[1])
+    let c = unchecked(this.state[2])
+    let d = unchecked(this.state[3])
+    let e = unchecked(this.state[4])
+    let f = unchecked(this.state[5])
+    let g = unchecked(this.state[6])
+    let h = unchecked(this.state[7])
+
+    for (let index: i32 = 0; index < 64; index += 1) {
+      const sum1 = __pulse_crypto_rotr(e, 6)
+        ^ __pulse_crypto_rotr(e, 11)
+        ^ __pulse_crypto_rotr(e, 25)
+      const choose = (e & f) ^ ((~e) & g)
+      const temporary1 = h
+        + sum1
+        + choose
+        + unchecked(__PULSE_CRYPTO_SHA256_K[index])
+        + unchecked(schedule[index])
+      const sum0 = __pulse_crypto_rotr(a, 2)
+        ^ __pulse_crypto_rotr(a, 13)
+        ^ __pulse_crypto_rotr(a, 22)
+      const majority = (a & b) ^ (a & c) ^ (b & c)
+      const temporary2 = sum0 + majority
+
+      h = g
+      g = f
+      f = e
+      e = d + temporary1
+      d = c
+      c = b
+      b = a
+      a = temporary1 + temporary2
+    }
+
+    unchecked(this.state[0] += a)
+    unchecked(this.state[1] += b)
+    unchecked(this.state[2] += c)
+    unchecked(this.state[3] += d)
+    unchecked(this.state[4] += e)
+    unchecked(this.state[5] += f)
+    unchecked(this.state[6] += g)
+    unchecked(this.state[7] += h)
+  }
+}
+
+function __pulse_crypto_wipe(bytes: StaticArray<u8>): void {
+  for (let index: i32 = 0; index < bytes.length; index += 1) {
+    unchecked(bytes[index] = 0)
+  }
+}
+
+function __pulse_crypto_memory_range_valid(pointer: i32, length: i32): bool {
+  if (pointer < 0 || length < 0) return false
+  if (length == 0) return true
+  const start = <u64><u32>pointer
+  const byteLength = <u64>memory.size() << 16
+  const end = start + <u64><u32>length
+  return end >= start && end <= byteLength
+}
+
+function __pulse_crypto_sha256_memory(pointer: usize, length: i32): StaticArray<u8> {
+  const sha = new __PulseCryptoSha256()
+  sha.updateMemory(pointer, length)
+  return sha.finish()
+}
+
+function __pulse_crypto_hmac_sha256(
+  keyPointer: usize,
+  keyLength: i32,
+  dataPointer: usize,
+  dataLength: i32,
+): StaticArray<u8> {
+  const keyBlock = new StaticArray<u8>(__PULSE_CRYPTO_SHA256_BLOCK_BYTES)
+  if (keyLength > __PULSE_CRYPTO_SHA256_BLOCK_BYTES) {
+    const keyDigest = __pulse_crypto_sha256_memory(keyPointer, keyLength)
+    for (let index: i32 = 0; index < __PULSE_CRYPTO_HS256_TAG_BYTES; index += 1) {
+      unchecked(keyBlock[index] = unchecked(keyDigest[index]))
+    }
+    __pulse_crypto_wipe(keyDigest)
+  } else {
+    for (let index: i32 = 0; index < keyLength; index += 1) {
+      unchecked(keyBlock[index] = load<u8>(keyPointer + <usize>index))
+    }
+  }
+
+  const inner = new __PulseCryptoSha256()
+  for (let index: i32 = 0; index < __PULSE_CRYPTO_SHA256_BLOCK_BYTES; index += 1) {
+    inner.updateByte(unchecked(keyBlock[index]) ^ 0x36)
+  }
+  inner.updateMemory(dataPointer, dataLength)
+  const innerDigest = inner.finish()
+
+  const outer = new __PulseCryptoSha256()
+  for (let index: i32 = 0; index < __PULSE_CRYPTO_SHA256_BLOCK_BYTES; index += 1) {
+    outer.updateByte(unchecked(keyBlock[index]) ^ 0x5c)
+  }
+  outer.updateStatic(innerDigest, __PULSE_CRYPTO_HS256_TAG_BYTES)
+  const output = outer.finish()
+
+  __pulse_crypto_wipe(keyBlock)
+  __pulse_crypto_wipe(innerDigest)
+  return output
+}
+
+/*
+ * Proof-only SHA-256 export used to bind the embedded primitive to FIPS 180-4
+ * vectors. It is not a configured public Pulse algorithm surface.
+ */
+export function pulse_crypto_sha256_digest(
+  dataPointer: i32,
+  dataLength: i32,
+  outputPointer: i32,
+  outputLength: i32,
+): i32 {
+  if (
+    dataLength < 0
+    || dataLength > __PULSE_CRYPTO_HS256_DATA_MAX
+    || outputLength != __PULSE_CRYPTO_HS256_TAG_BYTES
+    || !__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 index: i32 = 0; index < __PULSE_CRYPTO_HS256_TAG_BYTES; index += 1) {
+    store<u8>(<usize><u32>outputPointer + <usize>index, unchecked(digest[index]))
+  }
+  __pulse_crypto_wipe(digest)
+  return __PULSE_CRYPTO_VALID
+}
+
+export function pulse_crypto_hs256_verify(
+  keyPointer: i32,
+  keyLength: i32,
+  dataPointer: i32,
+  dataLength: i32,
+  tagPointer: i32,
+  tagLength: i32,
+): i32 {
+  if (
+    keyLength < __PULSE_CRYPTO_HS256_KEY_MIN
+    || keyLength > __PULSE_CRYPTO_HS256_KEY_MAX
+    || !__pulse_crypto_memory_range_valid(keyPointer, keyLength)
+  ) return __PULSE_CRYPTO_INVALID_KEY
+
+  if (
+    dataLength < 0
+    || dataLength > __PULSE_CRYPTO_HS256_DATA_MAX
+    || tagLength != __PULSE_CRYPTO_HS256_TAG_BYTES
+    || !__pulse_crypto_memory_range_valid(dataPointer, dataLength)
+    || !__pulse_crypto_memory_range_valid(tagPointer, tagLength)
+  ) return __PULSE_CRYPTO_INVALID_INPUT
+
+  const expected = __pulse_crypto_hmac_sha256(
+    <usize><u32>keyPointer,
+    keyLength,
+    <usize><u32>dataPointer,
+    dataLength,
+  )
+
+  // Every authenticator byte participates before the result branch.
+  let mismatch: u32 = 0
+  for (let index: i32 = 0; index < __PULSE_CRYPTO_HS256_TAG_BYTES; index += 1) {
+    mismatch |= <u32>(
+      unchecked(expected[index])
+      ^ load<u8>(<usize><u32>tagPointer + <usize>index)
+    )
+  }
+  const result = mismatch == 0
+    ? __PULSE_CRYPTO_VALID
+    : __PULSE_CRYPTO_INVALID_AUTHENTICATOR
+  __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/dist/contracts.d.ts

@@ -0,0 +1,198 @@
+export declare const CRYPTO_CONTRACT_VERSION: "pulse.crypto.verification.v1";
+export declare const CRYPTO_RUNTIME_BUILTIN_IMPLEMENTATION: "webcrypto.subtle.hmac-sha-256.v1";
+export declare const CRYPTO_GUEST_SOURCE_IMPLEMENTATION: "pulse-hmac-as.v1";
+export declare const CRYPTO_ES256_CONTRACT_VERSION: "pulse.crypto.es256-verification.v1";
+export declare const CRYPTO_ES256_RUNTIME_BUILTIN_IMPLEMENTATION: "webcrypto.subtle.ecdsa-p256-sha-256.v1";
+export declare const CRYPTO_ES256_GUEST_LINKED_REALIZATION: "guest-linked:pulse-es256-rustcrypto-p256";
+export declare const CRYPTO_ES256_GUEST_LINKED_IMPLEMENTATION: "rustcrypto.p256-0.13.2.ecdsa-0.16.9.sha2-0.10.9.v1";
+/**
+ * Executable algorithms remain intentionally narrower than frozen future
+ * contracts. G3, not G0, owns activation of ES256.
+ */
+export declare const CRYPTO_ALGORITHMS: readonly ["HS256", "ES256"];
+export type CryptoAlgorithm = typeof CRYPTO_ALGORITHMS[number];
+export type MacAlgorithm = 'HS256';
+export type SignatureAlgorithm = 'ES256';
+export declare const CRYPTO_VERIFICATION_STATUSES: readonly ["valid", "invalid-authenticator", "invalid-key", "invalid-input", "realization-failure"];
+export type CryptoVerificationStatus = typeof CRYPTO_VERIFICATION_STATUSES[number];
+export type CryptoVerificationResult = {
+    readonly status: 'valid';
+} | {
+    readonly status: 'invalid-authenticator';
+} | {
+    readonly status: 'invalid-key';
+} | {
+    readonly status: 'invalid-input';
+} | {
+    readonly status: 'realization-failure';
+};
+/**
+ * Raw HMAC key material. The algorithm-specific discriminant prevents this
+ * descriptor from being accepted as a future asymmetric verification key.
+ */
+export interface HmacKeyBytes {
+    readonly type: 'hmac-key-bytes';
+    readonly bytes: Uint8Array;
+}
+export type HmacVerificationKey = HmacKeyBytes;
+export interface MacVerifyRequest {
+    readonly algorithm: MacAlgorithm;
+    readonly key: HmacVerificationKey;
+    readonly data: Uint8Array;
+    readonly tag: Uint8Array;
+}
+/**
+ * Package-private normalized P-256 public point. JWK, SEC1, SPKI, PEM, and
+ * certificate representations never cross the crypto realization boundary.
+ */
+export interface P256PublicKeyBytes {
+    readonly type: 'p256-public-key-bytes';
+    /** Exactly 64 bytes: 32-byte big-endian x followed by 32-byte big-endian y. */
+    readonly bytes: Uint8Array;
+}
+export interface SignatureVerifyRequest {
+    readonly algorithm: SignatureAlgorithm;
+    readonly key: P256PublicKeyBytes;
+    /** Exact original signing bytes; never a reserialized JWT representation. */
+    readonly data: Uint8Array;
+    /** Exactly 64 bytes: 32-byte big-endian r followed by 32-byte big-endian s. */
+    readonly signature: Uint8Array;
+}
+/**
+ * Crypto-owned adapter input for the one JOSE representation accepted by the
+ * JWT composition. JWT has already validated the public JWK policy; crypto
+ * owns canonical coordinate/signature decoding into its fixed-width request.
+ */
+export interface Es256JoseVerifyInput {
+    readonly key: Readonly<{
+        readonly x: string;
+        readonly y: string;
+    }>;
+    readonly data: Uint8Array;
+    readonly signature: string;
+}
+export interface P256PublicKeyCoordinates {
+    readonly x: string;
+    readonly y: string;
+}
+export declare const CRYPTO_RESOURCE_LIMITS: Readonly<{
+    readonly hmacKeyBytesMinimum: 32;
+    readonly hmacKeyBytesMaximum: number;
+    readonly macDataBytesMaximum: number;
+    readonly hs256TagBytes: 32;
+    readonly es256PublicKeyBytes: 64;
+    readonly es256SignatureBytes: 64;
+    readonly es256SigningInputBytesMaximum: 16340;
+}>;
+export declare const CRYPTO_ES256_CONTRACT: Readonly<{
+    readonly version: "pulse.crypto.es256-verification.v1";
+    readonly status: "executable-g3";
+    readonly semanticOwner: "@pulse-compute/crypto";
+    readonly algorithm: "ES256";
+    readonly primitive: Readonly<{
+        kind: "ecdsa";
+        curve: "P-256";
+        hash: "SHA-256";
+    }>;
+    readonly operation: "verify";
+    readonly request: Readonly<{
+        function: "crypto.signature.verify";
+        keyType: "p256-public-key-bytes";
+        publicKeyEncoding: "raw-x-y-big-endian";
+        publicKeyBytes: 64;
+        dataBytesMaximum: 16340;
+        signatureEncoding: "jose-r-s-big-endian";
+        signatureBytes: 64;
+        derAccepted: false;
+    }>;
+    readonly runtimeBuiltin: Readonly<{
+        realization: "runtime-builtin";
+        implementation: "webcrypto.subtle.ecdsa-p256-sha-256.v1";
+        eligibleTargets: readonly ["node-javascript", "fastly-javascript"];
+    }>;
+    readonly native: Readonly<{
+        realization: "guest-linked:pulse-es256-rustcrypto-p256";
+        implementation: "rustcrypto.p256-0.13.2.ecdsa-0.16.9.sha2-0.10.9.v1";
+        eligibleTargets: readonly ["node-native", "fastly-native"];
+    }>;
+    readonly guest: Readonly<{
+        unitVersion: "pulse.guest-unit.v2";
+        unitId: "pulse.crypto.es256.rustcrypto-p256.v1";
+        module: "pulse_crypto_es256";
+        owner: "@pulse-compute/crypto";
+        abi: "pulse.crypto.es256.verify.v1";
+        export: Readonly<{
+            name: "pulse_crypto_es256_verify";
+            parameters: readonly ["i32", "i32"];
+            results: readonly ["i32"];
+        }>;
+        origin: "package-prebuilt";
+        sourceBuildDuringApplicationBuild: false;
+        memory: Readonly<{
+            identity: "pulse.guest-memory.invocation-frame.v2";
+            import: "env.memory";
+            minimumPages: 32;
+            maximumPages: 32;
+            growable: false;
+        }>;
+        start: "forbidden";
+        hostCallbacks: false;
+        allocator: false;
+    }>;
+    readonly frame: Readonly<{
+        identity: "pulse.crypto.es256.invocation-frame.v2";
+        byteOrder: "little-endian";
+        pointerWidthBits: 32;
+        magic: 844318032;
+        version: 2;
+        headerBytes: 64;
+        capacityBytes: 16640;
+        alignmentBytes: 16;
+        signingInputBytesMaximum: 16340;
+        publicKeyBytes: 64;
+        signatureBytes: 64;
+        rawPayloadBytesMaximum: 16468;
+        reservedHeaderAndAlignmentBytes: 172;
+        canonicalOffsets: Readonly<{
+            publicKey: 64;
+            signature: 128;
+            signingInput: 192;
+        }>;
+        header: Readonly<{
+            magic: 0;
+            version: 4;
+            headerLength: 8;
+            totalLength: 12;
+            algorithm: 16;
+            flags: 20;
+            signingInputOffset: 24;
+            signingInputLength: 28;
+            publicKeyOffset: 32;
+            publicKeyLength: 36;
+            signatureOffset: 40;
+            signatureLength: 44;
+            reserved0: 48;
+            reserved1: 52;
+            reserved2: 56;
+            reserved3: 60;
+        }>;
+        algorithmCode: 1;
+        flags: 0;
+        reservedWordCount: 4;
+        reservedWordValue: 0;
+        callerOwned: true;
+        synchronous: true;
+        retainable: false;
+        clearCapacityAfterReturnOrTrap: true;
+    }>;
+    readonly resultStatuses: readonly ["valid", "invalid-authenticator", "invalid-key", "invalid-input", "realization-failure"];
+    readonly resultCodes: Readonly<{
+        valid: 1;
+        invalidAuthenticator: 0;
+        invalidKey: -1;
+        invalidInput: -2;
+        realizationFailure: -3;
+    }>;
+    readonly automaticFallback: false;
+}>;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,EAAG,8BAAuC,CAAC;AAC/E,eAAO,MAAM,qCAAqC,EAChD,kCAA2C,CAAC;AAC9C,eAAO,MAAM,kCAAkC,EAC7C,kBAA2B,CAAC;AAC9B,eAAO,MAAM,6BAA6B,EACxC,oCAA6C,CAAC;AAChD,eAAO,MAAM,2CAA2C,EACtD,wCAAiD,CAAC;AACpD,eAAO,MAAM,qCAAqC,EAChD,0CAAmD,CAAC;AACtD,eAAO,MAAM,wCAAwC,EACnD,oDAA6D,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,6BAGnB,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAC/D,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AACnC,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAEzC,eAAO,MAAM,4BAA4B,oGAM9B,CAAC;AAEZ,MAAM,MAAM,wBAAwB,GAClC,OAAO,4BAA4B,CAAC,MAAM,CAAC,CAAC;AAE9C,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;QACrB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,sBAAsB;;;;;;;;EAQxB,CAAC;AAEZ,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoHvB,CAAC"}