castrum 0.9.3 → 0.9.6

package/src/rust-ffi/scalar/validation.ts

@@ -0,0 +1,121 @@
+// src/rust-ffi/scalar/validation.ts — Validation & text-utility scalar methods.
+//
+// Mirrors rust/util/validation.rs (batch fixed-width hex validation) and
+// rust/util/text.rs (JS-RegExp metacharacter escaping). Stateless; on Bun the
+// string paths cross as cstring ARGs (engine-transcoded — zero TextEncoder)
+// and regexEscape returns via a cstring return (engine-cloned — zero decode).
+
+import { encoder, toBytes } from '../../shared/bytes'
+import { decodeUtf8 } from '../../shared/codec'
+import type { RustClientContext } from '../context'
+import { memoizeFfi, resolveNative } from '../context'
+
+/**
+ * Non-zeroing output allocation for the batch verdicts (`Buffer.allocUnsafe`
+ * skips the 4 KB memset a plain `new Uint8Array` pays; every byte is
+ * overwritten by the native write anyway).
+ */
+const allocOut = (n: number): Uint8Array =>
+  typeof Buffer !== 'undefined' && typeof Buffer.allocUnsafe === 'function'
+    ? Buffer.allocUnsafe(n)
+    : new Uint8Array(n)
+
+/** Validation / text-utility methods (`Pick<RustScalar, ...>`). */
+export function buildValidation(ctx: RustClientContext) {
+  const { transport } = ctx.runtime
+  const n = (name: string) => resolveNative(ctx, name)
+  // Lazy-memoized ffi surface: binds on first call (no eager dlopen at import).
+  const ffi = memoizeFfi(transport)
+
+  return {
+    /**
+     * Validate NEWLINE-separated strings as fixed-width hex (e.g. Mongo
+     * ObjectIds at width 24) in ONE native call → one verdict byte per line.
+     * Replaces the per-item `/^[0-9a-f]{24}$/` regex loops list endpoints
+     * scatter everywhere. Accepts an array of id strings directly — the join
+     * crosses as a `cstring` ARG, so the JS side never touches an encoder.
+     *
+     * @param input Newline-separated candidates as bytes, or an array of
+     *   candidate strings (joined internally with `\n`)
+     * @param width Exact expected length of each line (1..=4096)
+     * @returns Uint8Array of 1/0 verdicts, one per line (trailing newline
+     *   does not add an extra verdict)
+     * @throws On `width` outside 1..=4096
+     * @example
+     * ```ts
+     * rust.hexValidateBatch(['507f1f77bcf86cd799439011', 'nope'], 24) // [1, 0]
+     * ```
+     */
+    hexValidateBatch(input: Uint8Array | readonly string[], width: number): Uint8Array {
+      if (width === 0 || width > 4096 || !Number.isInteger(width)) {
+        throw new Error('hex validate batch: width must be an integer 1..=4096')
+      }
+      const f = ffi()
+      if (f) {
+        // Verdict count ≤ line count ≤ input length — one native pass.
+        const joined =
+          typeof input === 'string'
+            ? input
+            : Array.isArray(input)
+              ? (input as readonly string[]).join('\n')
+              : null
+        let out = allocOut(Math.min(joined !== null ? joined.length + 1 : input.length + 1, 4096))
+        let w =
+          joined !== null
+            ? f.hexValidateBatchStr(joined, width, out)
+            : f.hexValidateBatchInto(input as Uint8Array, width, out)
+        if (w > out.length) {
+          out = new Uint8Array(w)
+          w =
+            joined !== null
+              ? f.hexValidateBatchStr(joined, width, out)
+              : f.hexValidateBatchInto(input as Uint8Array, width, out)
+        }
+        return out.subarray(0, w)
+      }
+      const bytes = Array.isArray(input)
+        ? encoder.encode((input as readonly string[]).join('\n'))
+        : (input as Uint8Array)
+      return n('hexValidateBatch')(bytes, width) as Uint8Array
+    },
+
+    /**
+     * Escape JS-RegExp metacharacters (`\ . * + ? ^ $ { } | ( ) [ ]`) so a
+     * pattern built with `new RegExp(rust.regexEscape(userInput), 'i')`
+     * matches the input LITERALLY. Under Bun the whole call is the FFI
+     * crossing + the escape: the input crosses as a `cstring` ARG (engine-
+     * transcoded, zero encode) and the result returns as a `cstring`
+     * (engine-cloned, zero decode).
+     *
+     * @param input Arbitrary text or bytes (multi-byte UTF-8 passes through)
+     * @returns The escaped pattern string
+     * @example
+     * ```ts
+     * const re = new RegExp(rust.regexEscape('a.c*(x)'), 'i')
+     * re.test('A.C(X)') // true — literal match, not wildcard semantics
+     * ```
+     */
+    regexEscape(input: Uint8Array | string): string {
+      const f = ffi()
+      if (f) {
+        if (typeof input === 'string') {
+          const escaped = f.regexEscapeStr(input)
+          if (escaped === null) throw new Error('regex escape failed')
+          return escaped
+        }
+        // Bytes path: needed-size convention with a generous first guess.
+        const bytes = toBytes(input)
+        let out = new Uint8Array(bytes.length + 16)
+        let w = f.regexEscapeInto(bytes, out)
+        if (w > out.length) {
+          out = new Uint8Array(w)
+          w = f.regexEscapeInto(bytes, out)
+        }
+        return decodeUtf8(out.subarray(0, w))
+      }
+      // napi takes/returns strings directly.
+      const s = typeof input === 'string' ? input : decodeUtf8(toBytes(input))
+      return n('regexEscape')(s) as string
+    },
+  }
+}

package/src/rust-ffi/text.ts

@@ -1,16 +1,27 @@
 // src/rust-ffi/text.ts — String-oriented FFI namespace (text in → text out).
 //
 // `rust.text.*` is the ergonomic string API over the byte-level native
-// functions. Pure wrappers: encode input, call native, decode output.
+// functions. MOST of it is FFI-first with `cstring` args/returns: the engine
+// transcodes a JS string in-call, so there is no JS-side encode at all (and
+// byte-arg ops are not involved). Encode/decode wrappers exist only for the
+// napi fallback and for ops with no cstring form — plus a NUL guard wherever a
+// `cstring` ARG could truncate a verdict or a byte-exact value
+// (docs/FFI_BUN_GUIDE.md §6.1).
 //
 // Runtime dispatch is centralized in the adapter (`ctx.runtime`): the Bun
 // built-in delegations (urlEncode/urlDecode) come from `builtins.has(op)` and
 // the native call from `transport.ffi` / `transport.resolve` (bun:ffi first,
 // napi fallback) — no inline `isBun()` / `getBunFFI()`.
 
-import { decoder, encoder } from '../shared/bytes'
+import { decoder, encoder, hasNul } from '../shared/bytes'
 import { type RustClientContext, resolveNative } from './context'
 
+/**
+ * Scratch for the byte-path `Sec-WebSocket-Accept` fallback (28 chars; the
+ * NUL case only). Decoded synchronously before returning, so reuse is safe.
+ */
+const WS_ACCEPT_OUT = new Uint8Array(64)
+
 /** String-oriented FFI namespace. */
 export interface RustText {
   /**
@@ -91,8 +102,19 @@ export function buildText(ctx: RustClientContext): RustText {
       // FFI-first: `cstring` ARG + cstring return (native transfer both ways —
       // the engine transcodes the key in-engine, no JS encode). napi keeps the
       // encode/decode path.
+      //
+      // Exception: a NUL would truncate the `cstring` ARG, so the accept value
+      // would be computed for a PREFIX of the key. Encode and take the byte path
+      // in that (practically unreachable) case: still a wrong key for a client
+      // that sent a NUL, but wrong for the bytes the caller actually passed.
       const f = transport.ffi
-      if (f) return f.wsAcceptKey(key)
+      if (f) {
+        if (!hasNul(key)) return f.wsAcceptKey(key)
+        const w = f.wsAcceptKeyInto(encoder.encode(key), WS_ACCEPT_OUT)
+        return w > 0 && w <= WS_ACCEPT_OUT.length
+          ? decoder.decode(WS_ACCEPT_OUT.subarray(0, w))
+          : ''
+      }
       return decoder.decode(resolveNative(ctx, 'wsAcceptKey')(encoder.encode(key)) as Uint8Array)
     },
     validateEmail(input) {

package/src/selection.ts

@@ -18,8 +18,8 @@
 // live wiring, so it can't drift.
 
 import { getAddon, lazyAddon } from './native'
-import { provenImpl } from './shared/proven'
 import { runtimeNative } from './runtime/native'
+import { provenImpl } from './shared/proven'
 
 /** Recommended implementation for an operation. */
 export type OpImpl = 'native' | 'js'

package/src/shared/bytes.ts

@@ -4,10 +4,11 @@ import { decodeUtf8, encodeUtf8, encodeUtf8Into } from './codec'
 
 /**
  * Shared UTF-8 encoder (encode / encodeInto), backed by the runtime-native
- * codec (`src/shared/codec.ts`): on Bun the work is done by Bun's native
- * transfer machinery (`Bun.ArrayBufferSink` / a zero-copy `Buffer` view
- * write); under Node it falls back to `TextEncoder`. Reusing a single object
- * avoids allocation overhead in hot paths.
+ * codec (`src/shared/codec.ts`): a shared native `TextEncoder` singleton on
+ * both runtimes (on Bun 1.4 the engine-native implementation measures ~3x
+ * faster than the old `Bun.ArrayBufferSink` path) plus a zero-copy `Buffer`
+ * view write for `encodeInto`. Reusing a single object avoids allocation
+ * overhead in hot paths.
  *
  * `encode` accepts the string-or-bytes union the text-returning `rust.*` ops
  * surface (Bun returns strings, Node returns bytes) and normalizes to bytes —
@@ -133,3 +134,22 @@ export function toPlainBuffer(bytes: Uint8Array): Uint8Array {
   copy.set(bytes)
   return copy
 }
+
+/**
+ * Does this string contain a NUL (`U+0000`)?
+ *
+ * `bun:ffi` transcodes a JS string passed to a `cstring` ARG into a
+ * NUL-TERMINATED UTF-8 buffer, so an embedded NUL SILENTLY TRUNCATES the value
+ * natively (Bun's docs describe the transcode; the truncation is the C
+ * convention it inherits). That is fine for developer-supplied config, and a
+ * real bug wherever the callee answers with a VERDICT (a truncated prefix
+ * passes where the full input fails) or where the exact bytes ARE the result.
+ *
+ * Cheap: one `indexOf` scan, ~4 ns for typical inputs.
+ *
+ * @param s - The string to check.
+ * @returns `true` when a NUL is present.
+ */
+export function hasNul(s: string): boolean {
+  return s.indexOf('\u0000') !== -1
+}

package/src/shared/codec.ts

@@ -12,9 +12,10 @@ import { runtimeCodec } from '../runtime/codec'
 /**
  * Encode a string to UTF-8 bytes.
  *
- * On Bun this uses `Bun.ArrayBufferSink` (native UTF-8 writing — no
- * `TextEncoder`). Under Node it falls back to the standard `TextEncoder`.
- * The implementation is selected once at load via the runtime adapter.
+ * Both runtimes use a shared native `TextEncoder` singleton (on Bun 1.4 the
+ * engine-native implementation measures ~3x faster than the previous
+ * `Bun.ArrayBufferSink` start/write/flush path). The implementation is
+ * selected once at load via the runtime adapter.
  *
  * @param s - The string to encode to UTF-8 bytes.
  * @returns A fresh `Uint8Array` of the UTF-8 encoding of `s`.
@@ -64,6 +65,20 @@ export const encodeUtf8Into: (s: string, dest: Uint8Array, offset?: number) => n
  */
 export const decodeUtf8: (bytes: Uint8Array) => string = runtimeCodec.decodeUtf8
 
+/**
+ * Decode the byte RANGE `[start, end)` of `bytes` to a string (replacement
+ * mode on invalid). Zero-copy ranged decode for packed-wire unpackers — no
+ * per-field `subarray` view. ASCII ranges take a latin1 fast path (~2x on
+ * Bun); multi-byte ranges fall back to real UTF-8 decoding of that range.
+ *
+ * @param bytes - The backing byte buffer.
+ * @param start - Range start (inclusive, relative to the VIEW).
+ * @param end - Range end (exclusive, relative to the VIEW).
+ * @returns The decoded string.
+ */
+export const decodeUtf8Range: (bytes: Uint8Array, start: number, end: number) => string =
+  runtimeCodec.decodeUtf8Range
+
 /**
  * Decode UTF-8 bytes to a string, throwing on invalid UTF-8.
  *

package/src/task/index.ts

@@ -0,0 +1,24 @@
+// src/task/index.ts — public barrel for the off-thread task runtime.
+
+export {
+  TASK_OP,
+  TASK_STATUS_CANCELLED,
+  TASK_STATUS_ERROR,
+  TASK_STATUS_OK,
+  brotliCapacityGuess,
+  encodeArgon2VerifyArgs,
+  encodeBrotliDecompressArgs,
+  encodeGzipCompressHeader,
+  encodeGzipDecompressArgs,
+  encodePbkdf2Args,
+  gzipCompressUpperBound,
+} from './op'
+export type { TaskOpName } from './op'
+export { createTaskRuntime } from './runtime'
+export type {
+  Pbkdf2RunOptions,
+  TaskRunOptions,
+  TaskRuntime,
+  TaskRuntimeOptions,
+  TaskStats,
+} from './runtime'

package/src/task/op.ts

@@ -0,0 +1,171 @@
+// src/task/op.ts — pure task-op registry: numeric ids + packed-arg encoders.
+//
+// PURE by design (no addon, no module state) so the wire encoding is directly
+// unit-testable. The ids MUST match the `OP_*` constants in `rust/task/ops.rs`;
+// `test/unit/task/runtime.test.ts` pins the round-trip.
+
+/** Numeric op ids — mirror `rust/task/ops.rs`. */
+export const TASK_OP = {
+  /** args `[u32 maxDecompressed LE][gzip bytes]` (0 = native 64 MiB default). */
+  gzipDecompress: 1,
+  /** args `[u32 rounds][u32 dkLen][u32 saltLen][salt][password]`. */
+  pbkdf2Sha256: 2,
+  /** `gzipDecompress` writing into a caller buffer (zero-copy output). */
+  gzipDecompressInto: 3,
+  /** args `[u32 pwLen][u32 phcLen][password][phc]` → body is one byte (1 = match). */
+  argon2Verify: 4,
+  /** args `[u32 maxDecompressed LE][brotli bytes]` (0 = native 64 MiB default). */
+  brotliDecompress: 5,
+  /** `brotliDecompress` writing into a caller buffer (zero-copy output). */
+  brotliDecompressInto: 6,
+  /** args `[u32 level][gzip bytes]` (level clamped to 0-9 natively). */
+  gzipCompress: 7,
+} as const
+
+/** A task op name (`gzipDecompress`). */
+export type TaskOpName = keyof typeof TASK_OP
+
+/** Completion status codes (mirror `rust/task/ops.rs`). */
+export const TASK_STATUS_OK = 0
+/** The op returned an error; the body is the UTF-8 error message. */
+export const TASK_STATUS_ERROR = 1
+/** The task was cancelled before/while it ran; the body is empty. */
+export const TASK_STATUS_CANCELLED = 2
+/** The zero-copy destination was too small; the body is the exact size (u64 LE). */
+export const TASK_STATUS_TOO_SMALL = 3
+/** The op has no zero-copy form; fall back to the copy path. */
+export const TASK_STATUS_UNSUPPORTED = 4
+
+/** Shared zero-length payload (header-only ops). */
+const EMPTY = new Uint8Array(0)
+
+// Shared `[u32 header][bytes]` packing for the single-header codec ops (the
+// `maxDecompressed` cap for decompress, the level for compress).
+function packHeaderAndBytes(header: number, data: Uint8Array, out?: Uint8Array): Uint8Array {
+  const need = 4 + data.length
+  const dest = out !== undefined && out.length >= need ? out : new Uint8Array(need)
+  // View-aware: `out` may be a subarray with a non-zero byteOffset.
+  new DataView(dest.buffer, dest.byteOffset, need).setUint32(0, header >>> 0, true)
+  dest.set(data, 4)
+  return dest.subarray(0, need)
+}
+
+/**
+ * Pack the `gzip.decompress` task args: `[u32 maxDecompressed LE][gzip bytes]`.
+ *
+ * @param data            Compressed gzip bytes.
+ * @param maxDecompressed Output cap in bytes; `undefined`/`0` selects the
+ *                        native 64 MiB decompression-bomb default.
+ * @param out             Optional caller-owned destination (>= `4 + data.length`),
+ *                        returned as a view. Native copies args on submit, so the
+ *                        same buffer may be reused for the next submission — but
+ *                        only while the caller stays SYNCHRONOUS (a zero-copy
+ *                        retry re-submits after an await and must own its memory).
+ * @returns A packed args buffer.
+ */
+export function encodeGzipDecompressArgs(
+  data: Uint8Array,
+  maxDecompressed?: number,
+  out?: Uint8Array,
+): Uint8Array {
+  return packHeaderAndBytes(maxDecompressed ?? 0, data, out)
+}
+
+/**
+ * Pack the `brotli.decompress` task args: `[u32 maxDecompressed LE][bytes]`.
+ *
+ * @param data            Compressed brotli bytes.
+ * @param maxDecompressed Output cap in bytes (`undefined`/`0` → native 64 MiB).
+ * @param out             Optional caller-owned destination (see the gzip form).
+ * @returns A packed args buffer.
+ */
+export function encodeBrotliDecompressArgs(
+  data: Uint8Array,
+  maxDecompressed?: number,
+  out?: Uint8Array,
+): Uint8Array {
+  return packHeaderAndBytes(maxDecompressed ?? 0, data, out)
+}
+
+/**
+ * Pack the `gzip.compress` task HEADER: `[u32 level]`. The payload is passed
+ * separately so it can be read in place (zero-copy input) instead of copied.
+ *
+ * @param level Deflate level (`0`-`9`, clamped natively).
+ * @param out   Optional caller-owned destination (>= 4 bytes).
+ * @returns The 4-byte header.
+ */
+export function encodeGzipCompressHeader(level = 6, out?: Uint8Array): Uint8Array {
+  return packHeaderAndBytes(level, EMPTY, out)
+}
+
+/**
+ * Pack the `argon2id.verify` task args:
+ * `[u32 pwLen][u32 phcLen][password][phc]`. No `out` parameter on purpose: a
+ * shared scratch would keep a plaintext password alive far longer than a
+ * per-call allocation, which is the wrong trade for a secret.
+ *
+ * @param password Candidate password bytes.
+ * @param phc      PHC string bytes (`$argon2id$...`).
+ * @returns A packed args buffer owned by the caller (Rust copies it on submit).
+ */
+export function encodeArgon2VerifyArgs(password: Uint8Array, phc: Uint8Array): Uint8Array {
+  const out = new Uint8Array(8 + password.length + phc.length)
+  const view = new DataView(out.buffer)
+  view.setUint32(0, password.length >>> 0, true)
+  view.setUint32(4, phc.length >>> 0, true)
+  out.set(password, 8)
+  out.set(phc, 8 + password.length)
+  return out
+}
+
+/**
+ * Safe upper bound on the gzip size of `n` input bytes: deflate's worst case is
+ * stored blocks (5 bytes per block) plus the 18-byte gzip wrapper. The 16 KiB
+ * block assumption is deliberately conservative (real blocks are 64 KiB), so a
+ * destination sized with this can never be too small — no retry round trip.
+ *
+ * @param n Uncompressed input length in bytes.
+ * @returns An upper bound in bytes.
+ */
+export function gzipCompressUpperBound(n: number): number {
+  return n + 5 * (Math.ceil(n / 16384) + 1) + 18
+}
+
+/**
+ * Starting capacity for a brotli zero-copy destination. Brotli carries no
+ * ISIZE trailer, so there is no exact hint: this is a ratio guess, and the
+ * needed-size retry lands the exact size if it falls short.
+ *
+ * @param compressedLen Compressed input length in bytes.
+ * @returns A capacity guess in bytes (floored at the runtime's zero-copy size).
+ */
+export function brotliCapacityGuess(compressedLen: number): number {
+  return Math.max(64 * 1024, compressedLen * 8)
+}
+
+/**
+ * Pack the `pbkdf2.sha256` task args:
+ * `[u32 rounds][u32 dkLen][u32 saltLen][salt][password]`.
+ *
+ * @param password Password bytes (the PBKDF2 secret).
+ * @param salt     Salt bytes.
+ * @param rounds   Iteration count (clamped to >= 1 natively).
+ * @param dkLen    Derived-key length in bytes (default 32, capped at 1 MiB).
+ * @returns A packed args buffer owned by the caller (Rust copies it on submit).
+ */
+export function encodePbkdf2Args(
+  password: Uint8Array,
+  salt: Uint8Array,
+  rounds: number,
+  dkLen = 32,
+): Uint8Array {
+  const out = new Uint8Array(12 + salt.length + password.length)
+  const view = new DataView(out.buffer)
+  view.setUint32(0, rounds >>> 0, true)
+  view.setUint32(4, dkLen >>> 0, true)
+  view.setUint32(8, salt.length >>> 0, true)
+  out.set(salt, 12)
+  out.set(password, 12 + salt.length)
+  return out
+}